Reference
Command line
Every agex command, its flags and output, the exit codes of agex wait, and which commands work while agex is closed.
The agex command reaches your agents, sessions and notes from any terminal. agex puts it in your PATH on first launch; see Download and install if it isn't there.
Run agex help for the list below, and agex help <command> or agex <command> --help for one command's lines.
agex: your agents, sessions and notes from the terminal
Open
agex [path...] Open folders as projects, files in a tab
agex open <path...> The same
Agents
agex agents [--state s] Running agents in every project (--json)
agex new [agent] [prompt...] Start an agent here; the default one unless named
agex wait <id> [--timeout 10m] Until it finishes (exit 0), asks you (2) or exits (3)
agex jump Go to the agent that has waited longest (⌘J)
agex focus <id> Bring an agent to the front
Sessions
agex history [words...] This project's past sessions (--all, --limit n, --json)
agex resume <n|id|words> Reopen one in agex (--print: the command instead)
agex interrupted Agents cut off when agex last quit (--all)
resume-all | dismiss <n>
Notes
agex todo Open to-dos on Todo.md (--all, --page name, --json)
agex todo add <text> Add one
agex todo done <n|words> Check one off
agex todo next Print the first open one
agex todo run [n] [--agent a] Start an agent on it
agex todo clear Remove the finished ones
agex notes [page] The pages, or one page (--path, --edit)
agex itself
agex notify <title> [body...] A popup and a sound in agex (--sound Glass)
agex update [--check] Install the latest release
agex version
agex install-cli Put agex in your PATH (--folder dir)
agex uninstall-cli
--project <name|folder> picks the project; it's the one you're in otherwise.
Open
| Command | What it does |
|---|---|
agex | Brings agex to the front, starting it if needed. |
agex [path...] | Opens folders as projects and files in a tab, like dropping them on the Dock icon. |
agex open <path...> | The same. |
agex . # add the folder you're in as a project
agex src/main.rs # open a file in a tab of the project that holds itA path that doesn't exist is an error. agex starts if it isn't running.
Agents
agex agents
Lists the running agents in every project, in agex or elsewhere: each one's id, its state and for how long, the agent, the project and its task. An agent running in another app shows that app after its task. agex ls is the same command.
| Flag | What it does |
|---|---|
--state <s> | Only agents in that state: waiting, working, done or idle. |
--json | Prints JSON instead of a table. |
agex agents --state waitingagex new
Starts an agent in the folder you're in and prints its id. With no agent named, or with default, it starts your default agent. agex starts if it isn't running.
agex new # the default agent
agex new claude # a named agent
agex new claude "fix the failing test" # with a first message
agex new "fix the failing test" # the default agent, with a first messageWhen the first word has a space in it, as a quoted prompt does, it's taken as the prompt, not an agent's name.
| Flag | What it does |
|---|---|
--prompt <text>, -p | The first message, as an option. Words after -- are added to it too. |
--project <name or folder> | Starts the agent in that project's folder instead. |
In a terminal it prints Started, id 7 (agex wait 7). When its output goes to a script or a pipe, it prints only the id.
agex wait
Waits until an agent's task is over, checking once a second, then prints a sentence such as Claude Code finished and exits with a code that says how it ended.
| Exit code | Meaning |
|---|---|
0 | It finished: it turned done, or went idle after working. |
2 | It's waiting for your answer. |
3 | It exited. |
124 | --timeout ran out first. |
1 | An error, such as no running agent with that id. |
--timeout, or -t, takes 90 or 90s (seconds), 10m or 2h.
id=$(agex new claude "fix the failing test")
agex wait "$id" --timeout 30m
case $? in
0) agex notify "Tests fixed" ;;
2) agex focus "$id" ;;
esacagex jump and agex focus
| Command | What it does |
|---|---|
agex jump | Goes to the agent that has waited longest, like ⌘J. |
agex focus <id> | Brings that agent to the front. |
Sessions
agex history
Lists the project's past sessions, newest first and numbered for agex resume: how long ago, the agent, the title and the branch. Words after the command narrow the list to matching sessions.
| Flag | What it does |
|---|---|
--limit <n>, -n | Shows n sessions (20 by default). |
--all, -a | Shows every session. |
--json | Prints JSON, with each session's agent, id, title, branch, modified (Unix time, in seconds) and resume command. |
agex resume
Reopens a past session in agex, or shows the agent that already has it open. agex starts if it isn't running. Name the session by:
- Its number in
agex history. - Its session id, or at least its first six characters.
- Words of its title. The newest session that matches wins.
agex resume 3
agex resume login bug
agex resume 3 --print # print the command that resumes it insteadagex interrupted
Lists the agents cut off when agex last quit, in this project: how long ago, the agent, the title and what it was doing. See Interrupted agents.
| Command | What it does |
|---|---|
agex interrupted | Lists them. --all lists every project's, with a project column; --json prints JSON. |
agex interrupted resume-all | Reopens every one in agex, starting it if needed. |
agex interrupted dismiss <n> | Dismisses number n from the list. |
Notes
These commands edit the same files as the Notes panel and the agents' skill. They work on the notes of the project holding the folder you're in, not on AGEX_NOTES_DIR, so they follow you when you cd into another repository.
agex todo
Lists the open to-dos on Todo.md, numbered. agex todos is the same command.
| Command | What it does |
|---|---|
agex todo | Lists the open to-dos. --all includes the finished ones; --json prints JSON. |
agex todo add <text> | Adds a to-do. It refuses one that's already listed. |
agex todo done <n or words> | Checks one off, by its number or by words that match exactly one open to-do. check works too. |
agex todo next | Prints the first open to-do. Exits with 1 when there's none. |
agex todo run [n] | Starts an agent in the project with the to-do as its first message: the first open one, unless you give a number or words. --agent <a> picks the agent. agex starts if needed. |
agex todo clear | Removes the finished to-dos. |
Every agex todo command takes --page <name> to work on another page.
agex todo add "update the changelog"
agex todo run --agent codex
agex todo done changelogagex notes
| Command | What it does |
|---|---|
agex notes | Lists the pages, with how many open to-dos each has. |
agex notes <page> | Prints that page as it's written. |
agex notes --path | Prints the project's notes folder, or the page's file with a page named. |
agex notes --edit | Opens a page in $VISUAL or $EDITOR (else vi), Todo unless you name one, creating it if needed. |
agex itself
| Command | What it does |
|---|---|
agex notify <title> [body...] | Shows a popup with a sound in agex, and a macOS notification while agex is in the background or closed. --body <text> adds to the body; --sound <name> picks a sound, like Glass. |
agex update | Installs the latest release over the installed app. If agex is running, quit and reopen it to switch. A copy that isn't an installed app prints the release page instead. |
agex update --check | Only says whether a newer release is out. |
agex version | Prints the version. agex --version and agex -V work too. |
agex install-cli | Puts the command in your PATH and turns on Add agex to PATH. --folder <dir> picks the folder and saves it as cli.folder. |
agex uninstall-cli | Removes the command from your PATH and turns Add agex to PATH off. |
agex --icon-report [path] | Explains which icon agex picks for a project, and why. See Project icons. |
Projects and the running app
Which project
The commands that work on one project (new, history, resume, interrupted, todo and notes) use the project holding the folder you're in: the deepest project that contains it. A repository inside a project folder, like a repository in your home folder, counts as its own project. Outside any project, it's the folder's repository, or else the folder itself.
--project <name or folder> picks another project, by its name (in any case) or by a folder.
When agex is closed
| While agex is closed | Commands |
|---|---|
| Work without it | history, resume --print, interrupted (listing and dismiss), todo (all but run), notes, notify, update, version, install-cli, uninstall-cli, help |
| Start agex first | agex, agex <path>, open, new, resume, interrupted resume-all, todo run |
Fail with agex isn't running | agents, wait, jump, focus |
With agex closed, agex notify posts a macOS notification.
Turn off control of the app
Control agex from the command in Settings › Command Line (cli.control) decides whether the command can start agents, jump to them, resume sessions and open projects in the app. Turned off, the command can still read your history and notes.
Output for scripts
- Tables use colors only when a person reads them in a terminal, and never when
NO_COLORis set. - When output goes to a script or a pipe,
agex newprints just the agent's id. - Errors go to stderr as
agex: <message>, with exit code1. - Short options:
-h(--help),-a(--all),-n(--limit),-p(--prompt) and-t(--timeout). Options also take--name=value.