Skip to content
Zero
The zero command

The zero command

How agents reach you: the zero command and the Claude Code plugin.

View as Markdown

zero is the command your agents use to reach you. When an agent needs an answer, your go-ahead or a command run on your Mac, it runs zero, and the ask shows in Zero’s inbox. Agents also use it to say where a task stands, start workers, show you tables and wake themselves up later. You rarely type it yourself.

How agents learn the command

  • Tasks Zero runs, in Claude Code, Codex and OpenCode, are told about zero when they start: how to ask you things, how to start workers and how to end a turn.
  • Claude Code also gets the zero skill from Zero’s Claude Code plugin, with every command and how to use it. See The Claude Code plugin below.
  • Any agent can run zero help for the full list.

Where the command lives

The command is inside Zero’s app, at /Applications/Zero.app/Contents/MacOS/zero-cli. When Zero updates, it links the command as ~/.local/bin/zero.

When an agent says zero: command not found, either the link is missing or ~/.local/bin isn’t on your shell’s path. Agents find commands through your login shell. Add the folder to your path in your shell’s profile, such as ~/.zprofile:

export PATH="$HOME/.local/bin:$PATH"

To make the link yourself:

mkdir -p ~/.local/bin && ln -sf /Applications/Zero.app/Contents/MacOS/zero-cli ~/.local/bin/zero

Two other messages mean Zero isn’t running: zero: Zero.app is not running and zero: Zero's daemon isn't running (open Zero). Open Zero and try again.

Ask you something

Each of these puts a card in your inbox. By default, the command waits until you answer, then prints your answer for the agent. With --async, it prints the ask’s id and returns at once. The answer reaches the agent later as a message.

Command Flags What you see in Zero
zero ask "question?" --option, --body, --title, --code, --block A question, or a choice when there are options. Each --option adds one option. The first option is the one that the agent recommends. An option that ends in “…” opens a box for your own words. --body adds a few sentences of detail under the question. --code shows a command or snippet in the card for you to run yourself.
zero approve "what" --body, --code A request for your go-ahead, with Yes, No and Suggest something else….
zero run 'command' --why, --cwd, --title, --allow Allow this command?, with Run, Reject and Suggest something else…. When you click Run, Zero runs the command on your Mac and gives its output back to the agent. --why is required: it says what the agent needs the output for.
zero withdraw <id> --reason The ask leaves your inbox, because the agent no longer needs it.

Zero refuses an ask whose question is longer than 140 characters or whose detail is longer than 280, and tells the agent to shorten it. Zero also refuses a question with choices such as “(a) … (b) …” in its text, and tells the agent to use --option.

Repeated reads with --allow. When an agent runs the same read-only command on different files, it can pass the start of the command as --allow, for example zero run 'cat logs/today.txt' --allow 'cat'. The card then also offers Run, and allow the same for this task. After you choose it, later commands of that kind from the same task, in the same folder, run without an ask.

Settings for asks

Setting Where What it does
Ask expiry Settings › Composer and inbox › Inbox › Ask expiry How long an ask waits for you before it expires, unless the agent sets its own with --ttl. The default is 60 minutes.

Open Settings with ⌘ , or the gear at the foot of the window’s left rail.

Say where a task stands

Command Flags What you see in Zero
zero note "where I am" --waiting, --needs "what you should do" The words show on the task’s row in the sidebar. --waiting marks the task Waiting: on someone other than you. --needs marks it Over to you: its work is done and a step is left for you. It stays until you write to the task or the agent posts a note without --needs.
zero done "what's done" --confirm TOKEN, --ask Marks the task Done. It takes two steps. Zero refuses the first run and gives what done means and a token. The agent then runs the command again with --confirm and the token within 5 minutes. With --ask, Zero asks you whether the task is done. A worker’s zero done marks it at once and asks no one: its lead judges it.
zero blocked "what blocks it" --confirm TOKEN Marks the task Blocked: it can’t go on until something outside the agent and you changes, such as an outage or another team’s access. A worker is also blocked when it needs a decision only its lead or you can make. It takes two steps, as zero done does. Agents that run in a sandbox use the zero_blocked tool instead. Until it’s confirmed, the task shows Waiting.
zero issue TICKET STATE ["text"] --session One row for an issue the task leads, under the task in the sidebar. The state is you, over, working, waiting, parked or done. you marks the task Needs you: the agent needs a decision or something only you can give. over marks it Over to you: the agent’s part is done, and a step is left for you, such as a review or a merge. A you or over row set before your last message to the task no longer sets the task’s state.

Zero starts a turn for a message from another task, an event or a reminder. The agent ends such a turn with a line that sets the task’s state. A worker ends every turn with one, and its lead hears how it ended. When a worker leaves the line out, Zero sends it back once to add it.

Last line State in Zero
[zero: done] Done, once zero done has confirmed it. Otherwise Replied.
[zero: waiting] Waiting: the next move is someone else’s, such as a review.
[zero: asked <id>] Needs you, while that ask is open.
[zero: working] Replied: the agent pauses between steps.
[zero: blocked] Waiting. Only zero blocked, once confirmed, marks the task Blocked.

Start and lead other tasks

Inside a task, zero spawn starts a worker of that task. The worker shows under the task in the sidebar. Zero tells its lead when the worker finishes, fails or gets stuck. Anywhere else, zero spawn starts a new task.

Zero puts a finished worker away an hour after its lead has its report. A worker that still follows something, watches or has a wake-up set stays. zero send to a worker that was put away brings it back. When Settings › Agents › Tasks › Archive done tasks is Never, workers stay too.

Command Flags What it does
zero spawn "task" --brief FILE, --loop NAME, --provider codex|claude|opencode, --model, --effort, --cwd, --label, --ticket, --permissions auto|unrestricted, --workspace ID Starts a worker, or a new task, and prints its id. A worker gets its lead’s folder and permissions, unless the flags give others. A new task gets Claude Code, Auto permissions and the current folder, unless the flags give others. --label names it.
zero send <task> "text" Sends a message to a task, by id or name. Zero resumes an offline task first, and brings an archived one back with its workers. When the sender is another task, the message is marked as that task’s and arrives between turns.
zero wait <task>... --any, --timeout MINUTES Waits until the tasks stop working, then prints how each ended. A task waiting on a command it started in the background is still working. An archived task is found as it was put away.
zero result <task> Prints the task’s last answer.
zero workers --session Lists the task’s workers.
zero adopt <task> --session Makes another task, or a Claude Code session, a worker of this one.
zero detach <worker> Lets a worker go: it becomes a task of its own.
zero close <worker>... Archives a worker the lead has read. It leaves the sidebar.
zero migrate <session id> --label, --workspace Brings a Claude Code, Codex or OpenCode session from outside Zero in as a task, with its history.
zero pause [task...] Pauses the tasks named, or every task, with their workers. Zero asks each working task to finish up and gives it five minutes, then the task stops. They show as Paused.
zero unpause [task...] Takes them off hold. Tasks with messages waiting continue.
zero tasks Lists every task: id, state, lead, ticket, Claude Code session, name and folder.
zero workspaces Lists your workspaces: id and name.
zero loops Lists your loops.
zero loop <name> Prints a loop’s words.

Show you things on a task

Command Flags What you see in Zero
zero table "Title" --column NAME, --row "a | b", --session A table in the task’s conversation. Give --column once per column and --row once per row. A cell holding a state, such as working or done, shows as a pill. In a column named for a risk, low, medium and high show as pills too. The table can also come as JSON on standard input: {"title", "columns", "rows"}.
zero attr NAME [VALUE] --session An attribute in the task’s details pane, such as zero attr PR https://github.com/example/app/pull/12. A link opens when you click it. Without a value, the command removes the attribute.
zero label "name" --ticket, --where PLACE, --session Renames the task. --ticket sets its ticket. --where sets the Where shown for it, such as a machine it runs on. --where "" shows its folder again.

Hear of changes and wake up later

Command Flags What it does
zero follow <url or topic>... --mine, --about "word,other words", --session The task hears of changes between its turns. It can follow a pull request, for its reviews, comments, checks, pushes and merge. It can also follow an issue, one comment thread in an issue, or a Slack thread or channel. In a busy channel, --mine passes on only messages that name the pull requests the task follows, and --about only those with these words. Settings › Following shows what tasks follow. So does each service’s page under Integrations in the window’s left rail.
zero unfollow <topic>... --all, --session Stops following.
zero following --session Lists what the task follows, and any trouble reading it.
zero watch -- command... --session Runs the command in the background. The task is told how it ended, so it doesn’t need to keep checking.
zero watch --file PATH --alert TEXT, --until TEXT, --quiet MINUTES Watches a log as it grows. A line with an --alert text is passed on, at most once a minute. --alert can be given more than once. --until ends the watch when a line has that text. --quiet says when the file stops growing. Text can be a pattern between slashes.
zero watch list, zero watch stop ID Lists or stops watches.
zero schedule "what for" --at TIME or --in DURATION Wakes the task at that time with “Scheduled:” and the words. TIME is 05:12 on your clock, 05:12Z, 05:12 UTC or a full date and time. DURATION is like 90m, 2h, 1d or 1h30m. Schedules stay when Zero restarts.
zero schedule list, zero schedule cancel ID Lists or cancels them.
zero remind <minutes> "text" --session The same as zero schedule, in minutes.
zero notify <task> "text" Gives a task words between its turns, for scripts.

Later, the browser, videos and scratchpads

Command Flags What it does
zero later save "note" --asked, --file PATH, --link URL, --attach FILE Saves work to Later in the window’s left rail. The note is a short headline. The file is the full write-up. --file - reads it from standard input. --link and --attach can each be given more than once. Without --asked, the item is a suggestion. It shows under Suggested by agents. Each task can have at most 3 open suggestions. A suggestion goes away after a week unless you keep it.
zero later list [words] Lists saved items, or those with these words.
zero later view <id> --version N Prints an item in full.
zero later edit <id> --note, --file, --link, --attach Changes an item.
zero later done <id>, open <id>, delete <id> Marks an item done or open again, or deletes it.
zero browser <tool> ['{json}'] --session Uses your Chrome, through Zero for Chrome, for agents that don’t have Zero’s browser tools. Screenshots are saved to a file. See Browsers and MCP servers.
zero video <file> --frames N, --at T,T…, --from T, --to T, --every S, --out DIR Turns a video into pictures an agent can look at. Without flags, it takes 12 pictures spread over the video.
zero mcp Runs Zero’s MCP server, for adding it to an agent by hand.

Commands for you in a terminal

Run these yourself to check on Zero.

Command Flags What it does
zero list --all Lists the open asks: id, state, kind, agent and title. --all lists every ask Zero keeps.
zero status <id> Prints an ask’s state and answer.
zero wait <id> Waits for an ask’s answer. If Zero restarts while it waits, it keeps waiting for up to 10 minutes.
zero say <agent> "text" Sends your words to an agent, as the inbox’s message box does.
zero board --watch Prints your tasks as the sidebar shows them, as JSON. --watch prints a new line each time something changes.
zero usage Each agent’s usage limits, as its CLI last reported them.
zero attach [agent] Shows one of Zero’s own terminal agents in your terminal, to watch or type in. ⌃ ] detaches. Without an agent, it lists them.

Flags every ask takes

Flag What it does Default
--async Prints the ask’s id and returns at once. Waits for your answer.
--agent NAME The name the ask comes from. Inside a task, that task. Elsewhere, the ZERO_AGENT variable.
--ticket ID The ticket the ask is about, shown with it. None.
--ttl MINUTES How long the ask waits before it expires. Ask expiry in Settings.

The command exits with 0 when you answered, 2 when you declined and 3 when the ask expired or was withdrawn. For zero run, the exit code is the command’s own.

Commands only hooks run

Three commands aren’t in zero help. Zero’s Claude Code plugin runs them, so you never need to:

  • zero permission turns Claude Code’s permission prompt into an ask in your inbox, and sends your answer back. Always allow also saves the rule Claude Code suggested. When Claude Code can’t reach Zero, or the ask expires, Claude Code asks in its terminal as usual.
  • zero question turns Claude Code’s own multiple-choice questions into asks, with Something else… added for your own answer.
  • zero prompt works out whether you typed a message in the terminal yourself, so the agent answers you there instead of through Zero.

The Claude Code plugin

Zero’s plugin connects Claude Code to Zero. Turn it on in Settings › Agents › Setup › Zero plugin. Zero installs it with Claude Code’s own plugin commands, so the claude command must work in your terminal. Zero updates the plugin when Zero itself updates.

The plugin has three parts.

Hooks. They apply to Claude Code that Zero starts in its own terminal. They also apply to agents that work beside a drop folder. They don’t apply to Claude Code that you start in a terminal yourself.

Hook What it does
Session start Tells Claude Code that you aren’t watching its terminal, and that it reaches you only through zero.
Permission requests Sends Claude Code’s permission prompts to your inbox, with zero permission.
Questions Sends Claude Code’s own questions to your inbox, with zero question, unless you typed in the terminal this turn.
Your messages Notices when you type in the terminal yourself, with zero prompt.
End of a turn Sends the agent back once when it ends a turn without an ending line, or with a question to you left in its text. The agent then asks you properly.

Tasks that Zero runs in its own window don’t need these hooks: Zero handles their permission prompts and questions itself.

Skills.

  • zero: how to reach you, with every command.
  • merge-risk: grades the risk of merging a pull request as low, medium or high, for a “Merge risk” column in a zero table.

The MCP server. It gives Claude Code these tools:

  • Your scratchpads: read, write, search and organise them.
  • Your Chrome, through Zero for Chrome: the browser tools.
  • zero_ask, zero_run, zero_note, zero_issue, zero_done and zero_blocked, which do what the commands do, for agents in a sandbox where the zero command can’t reach Zero.

What Codex and OpenCode get

The plugin is only for Claude Code. Codex and OpenCode get Zero like this:

  • Tasks Zero runs get Zero’s MCP server and Zero’s instructions on using zero. The server gives them scratchpads, the browser and the zero_ tools. They can also run the zero command, as any agent can.
  • In your own terminal, the Zero plugin switch also adds Zero’s MCP server to Codex’s settings in ~/.codex/config.toml and OpenCode’s in ~/.config/opencode/opencode.json, when those files exist. When you turn the switch off, Zero removes the server again.

Agents outside Zero

Any agent on your Mac can run zero, even one you started in a terminal yourself. Its asks reach your inbox. While it has an open ask, it shows as a coloured dot on the control bar. When the ZERO_AGENT variable is set, Zero names the agent by it. Set it to a short, stable name, so all of the agent’s asks show under one name. See The control bar.