agex
Docs menuCommand line

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

CommandWhat it does
agexBrings 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 it

A 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.

FlagWhat it does
--state <s>Only agents in that state: waiting, working, done or idle.
--jsonPrints JSON instead of a table.
agex agents --state waiting

agex 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 message

When the first word has a space in it, as a quoted prompt does, it's taken as the prompt, not an agent's name.

FlagWhat it does
--prompt <text>, -pThe 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 codeMeaning
0It finished: it turned done, or went idle after working.
2It's waiting for your answer.
3It exited.
124--timeout ran out first.
1An 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" ;;
esac

agex jump and agex focus

CommandWhat it does
agex jumpGoes 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.

FlagWhat it does
--limit <n>, -nShows n sessions (20 by default).
--all, -aShows every session.
--jsonPrints 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 instead

agex 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.

CommandWhat it does
agex interruptedLists them. --all lists every project's, with a project column; --json prints JSON.
agex interrupted resume-allReopens 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.

CommandWhat it does
agex todoLists 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 nextPrints 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 clearRemoves 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 changelog

agex notes

CommandWhat it does
agex notesLists the pages, with how many open to-dos each has.
agex notes <page>Prints that page as it's written.
agex notes --pathPrints the project's notes folder, or the page's file with a page named.
agex notes --editOpens a page in $VISUAL or $EDITOR (else vi), Todo unless you name one, creating it if needed.

agex itself

CommandWhat 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 updateInstalls 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 --checkOnly says whether a newer release is out.
agex versionPrints the version. agex --version and agex -V work too.
agex install-cliPuts 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-cliRemoves 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 closedCommands
Work without ithistory, resume --print, interrupted (listing and dismiss), todo (all but run), notes, notify, update, version, install-cli, uninstall-cli, help
Start agex firstagex, agex <path>, open, new, resume, interrupted resume-all, todo run
Fail with agex isn't runningagents, 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_COLOR is set.
  • When output goes to a script or a pipe, agex new prints just the agent's id.
  • Errors go to stderr as agex: <message>, with exit code 1.
  • Short options: -h (--help), -a (--all), -n (--limit), -p (--prompt) and -t (--timeout). Options also take --name=value.