# Introduction
What Zero is, the words its docs use, and which page to read first.
Zero is a Mac app for coding agents. It runs Claude Code, Codex and OpenCode, each signed in with your own account. You give an agent a job and a folder to work in. When it needs you, it asks in the inbox, where every agent asks and you answer.
## The parts of Zero
- **The window.** Your tasks and their conversations. The rail on its left side leads to Home, the Inbox, Later, Scratchpads, Loops, Integrations and Settings.
- **The control bar.** A small bar on the right edge of your screen. It shows the inbox and a mark for each task. It keeps your agents in view while you work in another app.
- **The inbox.** Everything your agents have asked you: questions, choices, commands to allow. It opens beside the control bar, and it's also a page in the window.
- **The iPhone app.** Your inbox and tasks on your phone, coming soon.
## Words these docs use
- **Task**: one agent that works on one job, in one folder. Each task has a conversation, like a chat.
- **Worker**: a task that another task started for part of its job. It shows under the task that started it, and it reports back to that task.
- **Ask**: something an agent needs from you, such as an answer, a choice or your go-ahead.
- **Account**: a sign-in for Claude Code, Codex or OpenCode that Zero keeps and gives to the agent.
- **Project**: a folder on your Mac that you added to Zero. Tasks start in a project.
- **Workspace**: a set of tasks kept apart from the rest, such as your own projects and your job. Each task belongs to one workspace.
## Where to start
New to Zero? Start with [Getting started](/docs/getting-started). Then:
| Page | What it covers |
|---|---|
| [Tasks and workers](/docs/tasks-and-workers) | Starting a task, talking to it while it works, and following its workers. |
| [The inbox and asks](/docs/inbox-and-asks) | Every kind of ask, and how to answer. |
| [The control bar](/docs/control-bar) | The bar on the edge of your screen. |
| [Accounts and models](/docs/accounts-and-models) | Signing in agents, and picking models. |
| [Workspaces and folders](/docs/workspaces-and-folders) | Keeping tasks apart, and telling Zero where your projects are. |
| [Later, scratchpads and loops](/docs/later-scratchpads-loops) | Saving things for later, notes agents can read, and instructions you hand agents by name. |
| [Following and integrations](/docs/following-and-integrations) | Agents watching pull requests and issues, and the services you connect. |
| [Browsers and MCP servers](/docs/browsers-and-mcp) | Letting agents use your browser, and giving them more tools. |
| [Settings](/docs/settings) | Every setting: what it does and where it is. |
| [Keyboard shortcuts](/docs/keyboard-shortcuts) | Every key Zero answers to. |
| [The iPhone app](/docs/iphone) | Zero on your phone. |
| [The zero command](/docs/cli) | How agents reach you. |
| [Troubleshooting](/docs/troubleshooting) | What to do when something doesn't work. |
## Zero's code
Zero is free and open source, under the [GNU General Public License v3 or later](https://github.com/arsenstorm/zero/blob/main/LICENSE). The code is [on GitHub](https://github.com/arsenstorm/zero). To help build Zero, read [CONTRIBUTING.md](https://github.com/arsenstorm/zero/blob/main/CONTRIBUTING.md) first.
---
# Getting started
Install Zero, sign in an agent, and start your first task.
Zero runs coding agents on your Mac: Claude Code, Codex and OpenCode. You give an agent a job in a folder and it gets to work. When it needs you, it asks in Zero's inbox.
## Check what you need
- **A Mac with macOS 26 or later.** Zero doesn't open on earlier versions.
- **At least one agent CLI.** Zero doesn't include the agents. It runs the ones you have installed:
| Agent | Command Zero runs |
|---|---|
| Claude Code | `claude` |
| Codex | `codex` |
| OpenCode | `opencode` |
## Install Zero
Download Zero from [withzero.dev/download](/download). It needs macOS 26 or later.
1. Open **Zero.dmg**. A window opens with Zero on the left and your **Applications** folder on the right.
2. Drag **Zero** onto **Applications**. Zero updates itself there, and the tools it gives your agents look for it there.
3. Open Zero from your **Applications** folder. Then eject the **Zero** disk in Finder's sidebar.
If you open Zero from somewhere else, such as the disk image or your **Downloads** folder, Zero asks to move itself first. Click **Move to Applications**. Zero copies itself to **Applications**, opens from there and puts the copy you opened in the Trash, or ejects the disk image. If a Zero is already in **Applications**, it goes to the Trash. If your account can't add apps to **Applications**, Zero goes in the **Applications** folder in your home folder instead.
Each release also has **Zero.zip**, the same app zipped. Zero's updater uses it.
Zero is a menu bar app. It shows in the Dock only while one of its windows is open.
## Make sure Zero can find your agents
Zero starts each agent with zsh as a login shell, like a new Terminal window does. A command that works in a new Terminal window works in Zero too, wherever it's installed: with Homebrew, in `~/.local/bin` or through a Node version manager.
To check, open Terminal and run:
```sh
zsh -lic 'command -v claude codex opencode'
```
Each agent you have installed prints its path. One that prints nothing isn't on the PATH that zsh sets in `~/.zprofile` or `~/.zshrc`. Add it there and run the command again. You don't need to restart Zero.
## Go through the welcome
The first time you open Zero, a welcome window walks you through five steps. Click **Continue** for the next step, or **Back** to go back.
1. **Welcome to Zero.** What the control bar and the inbox are.
2. **Your agents.** Shows whether Claude Code and Codex are installed. For Claude Code, click **Add plugin** to install the Zero plugin. The plugin lets Claude Code ask you things in Zero. Once it's installed, the button reads **Plugin added**. The Codex row is for information only.
3. **Permissions.** To dictate replies, click **Allow** beside **Microphone** and **Speech recognition**. Both permissions are optional.
4. **Make it yours.** Set the **Talk hotkey**. Turn on **Launch Zero at login**. Turn **Follow the active screen** on or off for the control bar. The Talk hotkey is ⌥Space unless you change it.
5. **Try it.** Click **Send test ask**. A sample ask opens in the inbox, just like one from an agent. Press 1 to answer it. Then click **Done**.
macOS also asks whether Zero can send notifications. Allow them so you hear when a task needs you.
To see the welcome again, open **Settings › General › Advanced › Onboarding** and click **Open**. Open Settings with ⌘, or the gear at the foot of the window's left rail.
## Sign in an agent
An agent needs an account to work. Give it one in either of two ways:
- **Use the sign-in the agent already has.** When Claude Code, Codex or OpenCode already works in your Terminal, Zero's tasks use that sign-in. You set up nothing in Zero.
- **Add accounts to Zero.** Open **Settings › Accounts** and click **Add account** beside the agent's name. Sign in with your Claude or ChatGPT subscription, or add an API key. Zero keeps the account and gives it to the agent when a task starts. With more than one account, a task that reaches one account's usage limit carries on with another.
Once you add an account for an agent in Zero, that agent's tasks use Zero's accounts. See [Accounts and models](/docs/accounts-and-models).
## Add a project folder
Each task works in a project: a folder on your Mac that you added to Zero. To add one:
1. Open **Settings › Folders**.
2. Beside **Projects**, click **Add folder**.
3. Choose one or more folders.
Until you add a folder, the new task page shows **Add a project in Settings › Folders** in place of the project chip.
## Start your first task
1. Open Zero's window: click the Zero icon in the menu bar and choose **Show Zero**.
2. Click **Home**, the house at the top of the left rail. The new task page opens, with a box that says **Do anything**.
3. Look at the chips under the box:
- **The project.** Click it to choose the folder the task works in.
- **The agent and model**, on the right of the row. Click it to choose Claude Code, Codex or OpenCode and one of its models. See [Accounts and models](/docs/accounts-and-models).
- **Permissions**, the wand icon. With **Auto**, the agent decides what's safe and asks you about the rest. With **Unrestricted**, it does anything without asking.
4. Type what you want done, such as "Fix the flaky login test", and press Return.
The task opens and the agent gets to work. When it needs you, its question shows in the inbox and on its mark in the control bar. See [Tasks and workers](/docs/tasks-and-workers).
## Find your way around
Zero has three places on your screen:
- **The window.** Your tasks and their conversations. The rail on its left side leads to **Home**, **Inbox**, **Later**, **Scratchpads**, **Loops**, **Integrations** and **Settings**. To open it, choose **Show Zero** from the menu bar icon, or open Zero again from the Applications folder.
- **The control bar.** A small bar on the right edge of your screen, halfway down. It shows the inbox and a mark for each task. Point at it to open the inbox. See [The control bar](/docs/control-bar).
- **The menu bar icon.** Zero's mark in the menu bar. Click it for:
| Item | What it does |
|---|---|
| **Show Zero** | Opens the window. |
| **Check for Updates…** | Opens **Settings › General** and checks for a new version. |
| **Settings…** | Opens Settings in the window. |
| **Quit Zero** | Quits the app. |
Closing the window with ⌘W leaves Zero in the menu bar, with the control bar on screen. Your agents keep working when the window is closed, and even when you quit Zero.
## Keep Zero up to date
Zero checks for a new version when it opens and every six hours after that. It installs one only when you say so.
- When a new version is out, the menu bar icon's menu shows **Update to Zero** and the version. Choose it to go to **Settings › General**.
- In **Settings › General**, the first row shows your version. It reads **Up to date.** with **Check now**, or names the new version with **Update and restart**.
Click **Update and restart**. Zero quits and opens again as the new version. Agents that are working pause between steps for a few seconds, then carry on.
---
# Tasks and workers
Start a task, talk to it while it works, and follow the workers it starts.
A task is one agent working on one job for you, such as "Fix the flaky login test". It runs Claude Code, Codex or OpenCode in a folder on your Mac. You start, read and steer tasks in Zero's window. A task can also start workers: tasks of its own, each taking part of the job.
To open the window, choose **Show Zero** from the menu bar icon. While that menu is open, ⌘0 does the same. The rail runs down its left edge. Next to it, the tasks sidebar lists the tasks in the workspace you're looking at.
## Start a task
1. Click **New task** at the top of the tasks sidebar, or press ⌘N. The **Home** button at the top of the rail opens the same page.
2. In the box that says **Do anything**, write what you want done. Paste or drop images into it too.
3. Check the chips under the box:
- **The project**: the folder the task starts in. Click it to pick another from **Projects**. Zero lists the folders you added in **Settings › Folders › Projects**. Until you add a folder, **Add a project in Settings › Folders** shows in place of the chips. See [Workspaces and folders](/docs/workspaces-and-folders).
- **The workspace**: shown only when you have more than one workspace. The task and every worker it starts go into the workspace you pick here. It starts as the workspace you're looking at.
- **The agent**: the model and effort, such as "Opus 5.5 · High", with the provider's mark as its icon. Click it to pick a provider from the tabs at the top, a model from the list, and an effort with the **Effort** slider. With no model picked, the task starts on the provider's first model. OpenCode starts on the model set in its own config.
- **Permissions**: an icon with no label. Point at it to see **Permissions: Auto** or **Permissions: Unrestricted**.
4. Click the paper plane, or press ↩. The task starts and opens.
The two permission modes:
| Mode | What the agent can do |
|---|---|
| **Auto** | The default. The agent's CLI decides what's safe and asks you about the rest. Its requests reach your inbox. |
| **Unrestricted** | Anything, without asking. An orange bolt marks the task wherever its permissions show. |
Zero keeps what you write on this page as a draft until you send it, and remembers the provider and project you used last. For accounts and models, see [Accounts and models](/docs/accounts-and-models).
## Find your tasks in the sidebar
The tasks sidebar shows, from the top:
- **The workspace's name.** Click it to switch workspace, make one with **New workspace…**, or open **Workspace settings…**.
- **New task** and **All tasks**. All tasks opens the board. See "See every task at once" below.
- **Tasks**, then a row for each task, with its state icon on the right.
- **Earlier**: tasks that stopped some time ago and need nothing from you.
Click a row to open the task. ⌘1 to ⌘9 open the first nine tasks in the order the sidebar shows them.
Rest the pointer on a row for half a second to see a card about the task:
- Its state, and what it's doing now.
- What it handed over to you, as **For you: …**.
- Up to three of its open asks, and messages queued for it.
- When it wakes up next, if it has scheduled a check.
Click the card to open the task.
### Sort, pause or unarchive
Click the sliders button beside the **Tasks** heading. Its tip is **Sort, pause or unarchive tasks**.
| Item | What it does |
|---|---|
| **State** | Sorts the most urgent task first, in the order of the states table below. The default. |
| **Name** | Sorts by name. |
| **Manual (drag to arrange)** | Keeps the order you drag the rows into. Dragging a row switches to this sort. |
| **Pause all tasks** | Puts every running task in this workspace on hold. Shown when a task is running. |
| **Resume paused tasks** | Takes this workspace's paused tasks off hold. Shown when a task is paused. |
| **Archived tasks…** | Opens the tasks you archived. |
The control bar lists the tasks in the same order as the sidebar.
### Use a task's menu
Right-click a task in the sidebar:
| Item | What it does |
|---|---|
| **Rename…** | Gives the task a new name. |
| **Move to** and a workspace's name | Moves the task to that workspace. Shown only when you have more than one. |
| **Change status** | Sets the task to **Done**, **Waiting** or **Blocked**. See "What a task's state means" below. |
| **Pause** / **Resume** | Puts the task and its workers on hold, or takes them off hold. |
| **Work with another task…** | Pick another task, then click **Work together**. Each of the two hears about the other and how to reach it, so they can settle things between them. |
| **Save for later** | Asks the agent to save what it has to Later, after its current turn. The task stays where it is. See [Later, scratchpads and loops](/docs/later-scratchpads-loops). |
| **Move to Later** | Puts the whole task in Later. It leaves the sidebar and is paused with its workers, but isn't archived. Also in the **⋯** menu in the window's title bar. See [Later, scratchpads and loops](/docs/later-scratchpads-loops). |
| **Archive…** | Archives the task. See "Archive a task" below. |
A worker's menu has **Rename…**, **Change status**, **Pause** or **Resume**, and **Archive…**. While the worker is working or waiting, it also has **Stop**.
## What a task's state means
The sidebar and the control bar show each task's state as an icon. The board and the details pane show it as a pill. A task's state includes its workers': when a worker needs you or is in trouble, so does its task.
| Icon | State | What it means |
|---|---|---|
| Blue hand | Needs you | The task, or one of its workers, asked you something and is waiting for your answer. |
| Orange triangle | In trouble | The task failed, got stuck or ran out of usage. |
| Red minus | Blocked | The task can't go on until something outside you and the agent changes, such as an outage or another team's access. The agent has to confirm it, so it's rare. A worker is also blocked when it needs a decision only its task or you can make. Zero tells you the same way as for In trouble. |
| Blue spinner | Working | The agent is working. |
| Teal box | Over to you | The task is finished, and there's a step only you can take, such as a merge or a check. It stays until you write to the task. |
| Indigo speech bubble | Replied | The task answered you and isn't waiting on anything. It turns grey once you've read it. |
| Grey hourglass | Waiting | The task is waiting on someone or something other than you, such as a review or a build, or a command it started in the background. |
| Grey pause | Paused | You put the task on hold. |
| Purple badge | Done | The task is finished end to end, and the agent confirmed it. An agent that only says it's done shows Replied. |
| Grey moon | Idle | The agent is between turns with nothing to report. |
| Grey power button | Offline | The agent isn't running. |
When a task is done, waiting or blocked and its agent can't know, such as when you did the last of it yourself, right-click it in the sidebar and choose **Change status**, then **Done**, **Waiting** or **Blocked**. A tick marks the state it's in now. Zero takes your word as it would the agent's confirmation. A question or approval still open keeps the task at **Needs you**. When you next write to the task, it's the agent's to settle again.
Zero archives done tasks after a while. Choose when in **Settings › Agents › Tasks › Archive done tasks**: **Once you've read it**, **After an hour**, **After a day**, **After a week** or **Never**. **After a day** is the default. An archived done task comes back when something it follows changes.
## Read the conversation
A task's page shows its conversation: your messages, the agent's answers, and the work in between.
- **Steps.** Each turn has a heading. It reads **Working for 12s** while the agent works, then **Worked for 2m 37s** or **Thought for 8s**. While the agent works, its latest step shows under the heading. Once its answer starts, the steps fold away.
- **Folded steps.** What the agent said between steps stays in place. Each run of steps between two of its messages becomes one line, such as "Ran 3 commands, edited 2 files". A failed step adds a red count, such as "· 1 failed". Click the line to open those steps, or click the heading to see every step of the turn.
- **Commands.** Each command shows what it does, in the agent's words when it gives them, then the command. A running command shows how long it has run, and after a few seconds the last line it printed. A command that fails shows its exit code. Click a command to see it whole with its output, and **Copy the output** or **Copy the command**.
- **Quiet updates.** Turns that Zero started and that needed nothing from you fold into one row. The row says who sent them, such as "Reviewer reported back · nothing needed" or "3 updates · nothing needed". Click the row to read them.
- **Messages from others.** A worker's report, a message from another task, or a note from Zero shows as one line. Click it to read the whole message. Click the sender's name to open that task.
- **Everything the last turn changed.** Shows below the last answer while the agent is idle. Open it to see the turn's changes as a diff.
- **Trouble.** A task that's stuck, or that hit its provider's usage limit, shows a callout at the end. When it's out of usage, click **Continue with Claude Code** or **Continue with Codex** to hand the task, conversation and all, to the other provider.
Zero plays the conversation back in order, the agent's words at a steady pace. An ask's card shows once the conversation reaches the step that asked it.
To move around a long conversation, use the ticks down the left edge, one for each of your messages. Point at one to preview it, and click to go there. The down arrow, **Go to the latest**, takes you to the end.
Point at a message to see a copy button, a **⋯** menu and the time it was sent. The menu has:
| Item | What it does |
|---|---|
| **Copy** | Copies the message. |
| **Quote in reply** | Adds the message to your reply as a quote. |
| **Save to a scratchpad** | Saves the message as a new scratchpad in the **Saved** folder, named after its first line. |
| **Save for later** | On the agent's answers: asks the agent to save that answer to Later. |
| **Rewind…** | On your messages: takes the task back to before that message. See "Rewind a task" below. |
## Write to a task
Write in the composer at the foot of the page:
| You want to | Do this |
|---|---|
| Send a message | Press ↩, ⌘↩, or click the paper plane. |
| Steer the agent while it works | Press ⌘↩. The message reaches the agent in the middle of its turn. The box says **Steer it while it works**. |
| Queue a message for after this turn | Press ↩ while the agent works. |
| Stop the agent's turn | Click the square that replaces the paper plane, or press ⌘.. |
| Start a new line | Press ⇧↩ or ⌥↩. |
Start typing, or press ⌘V, anywhere on the page, and it goes into the composer without a click. Zero keeps an unsent message as a draft for each task, and puts your words back in the box if a message can't be sent.
OpenCode takes one message at a time, so you can't steer it. Its box says **OpenCode answers one message at a time**.
### Edit, drop or send queued messages
Queued messages wait above the composer under **Queued**. For each one:
- Click it, or its pen, to take it back into the composer. The pen's tip is **Edit in the composer**.
- Click its bin to drop it. Its tip is **Delete**.
- Click **Steer** to send it now. Its tip is **Send it now, mid-turn**.
When the agent's turn ends, Zero sends it the next queued message. Until that message shows in the conversation, it stays in the queue with **Next** in place of its buttons.
Stopping the agent holds the queue. The heading says **Held**, and nothing goes out until you click **Send** beside it or send something new.
### Attach files, folders and scratchpads
- **Images and videos**: paste them, drop them on the composer, or use the **+** button. Each shows as a pill in your words, such as **Image 1** or **Video 1**, and as a thumbnail above. Click a pill to open the image. A video goes to the agent as up to six stills.
- **Other files and folders**: click **+** › **Files and folders**. Images you pick go with the message. For anything else, Zero puts its path in your message, and the agent reads it from there.
- **A scratchpad**: click **+** › **Scratchpad**, then find and pick one. Zero puts a link to it in your message.
### Use / and @
- Type / for Claude Code's commands and skills, eight at a time. Turn this off in **Settings › Composer and inbox › Composer › Suggest skills after /**.
- Type @ for your loops. See [Later, scratchpads and loops](/docs/later-scratchpads-loops). To also list files from the task's folder, turn on **Settings › Composer and inbox › Composer › Suggest files after @**. It's off by default.
In the suggestions, ↑ and ↓ move, Tab or ↩ takes one, and Esc closes them.
### Change the model or permissions
The composer's chips show the task's model and permissions.
- **The agent chip** changes the model and effort from your next message. It also lists the other provider: Claude Code for a Codex task, or Codex for a Claude Code task. Pick one of its models and the task carries on there, with the whole conversation.
- **The permissions chip** shows **Auto** or **Unrestricted**, and changes what the agent can do without asking.
Change either while the agent is working, and the change applies from its next turn. The chip shows a clock, and its tip says **From the next turn**.
### Answer the task's questions
When a task asks you something, the question shows as a card above the composer and in your inbox. When the composer is empty, press 1 to 9 to pick an answer. See [The inbox and asks](/docs/inbox-and-asks).
## See a task's details
The details pane floats at the top right of the task's page. Show or hide it with the sidebar button at the right of the title bar. Its tip reads **Show details** or **Hide details**. It's shown by default.
| Row | What it shows |
|---|---|
| **Agent** | The provider and the model, such as "Opus 5.5 · High". An orange bolt means the task is **Unrestricted**. Change the model in the composer, not here. |
| **Where** | The project folder. Click it to show the folder in Finder. When **Settings › Agents › Tasks › Where tasks run** has a command, it shows the place that command names instead. |
| **Status** | The task's state. Point at it for a card with more about where the task stands. Click the card to keep it open. Press Esc or click outside to close it. |
| **Branch** | The Git branch it's on, when there is one. |
| **Ticket** | The issue the task is on, as a link, when it has one. |
| Others | Anything else the agent recorded about the task, such as its pull request, as links. |
| **Issues** | For a task that works through several issues: each issue's state, its ticket as a link, and where it stands. An issue waiting on you shows for how long. **Open**, beside an issue with a worker of its own, opens that worker. |
| **Workers** | The task's workers, the most urgent first. Click one to open it. **All N** shows every worker, **Fewer** goes back. |
## Follow a task's workers
A task can hand parts of its job to workers: other agents it starts, each with a conversation of its own. Ask a task for one, such as "Have a worker review the change".
By default, agents use Zero's workers rather than their CLI's own subagents, so you can see, steer and stop every one of them. To let Claude Code and Codex also use their own subagents, turn on **Settings › Agents › Tasks › Agents' own subagents**. It applies from each task's next start.
Workers show in several places:
- **In the sidebar**, under their task on a dotted branch. To fold them away, click the chevron beside the task. Its tip reads **Hide its workers** or **Show its workers**. When a task works through several issues, each issue gets a row of its own, with how long it's been waiting on you.
- **On the task's page.** Click a worker to open its conversation in the task's page. The sidebar keeps the task selected. Write to the worker as you would to any task.
- **In the details pane**, under **Workers**.
- **On the board**, as "1 worker" or "N workers" under the task's name.
- **In the task's conversation.** When a worker finishes, fails or gets stuck, its report arrives as a line that starts with "Worker". Click it to read the report.
When a worker needs you or is in trouble, its task shows that state too. The task's card in the sidebar says so, for example "1 worker needs you".
A worker that ends its turn while a command it started in the background still runs shows **Waiting**. Its task hears that it's waiting on the command, and the worker carries on when the command finishes.
Zero archives a finished worker an hour after its task has its report, so finished workers don't pile up under a task. A worker that's waiting, asking or in the middle of its work stays, and so does one with an ask, a follow, a watch or a wake-up still open. Zero doesn't archive workers when **Archive done tasks** is **Never**. A message to an archived worker, from you or its task, brings it back.
## Pause, end or resume a task
| Action | Where | What it does |
|---|---|---|
| **Stop** | The square in the composer, or ⌘. | Stops the turn the agent is on. The task stays where it is, and you can write to it again. |
| **Pause** | A task's menu in the sidebar, the **⋯** menu in the title bar called **More**, or the **⋯** menu on the board called **Actions** | Puts the task and its workers on hold. Zero asks a working agent to finish the step it's on and end its turn, then stops it. Messages for it wait until you resume it. |
| **Resume** a paused task | The same menus | Takes the task and its workers off hold. Any with messages waiting start again for them. |
| **End session** | The **⋯** in the title bar, or the **⋯** on the board | Stops the agent's process. |
| **Resume** an offline task | The **⋯** in the title bar, or the **⋯** on the board | Starts the agent again on the same conversation. |
To pause every task in a workspace, use **Pause all tasks** in the sliders menu beside the sidebar's **Tasks** heading.
When an agent has been idle for three minutes with nothing open, Zero stops it to free memory. You don't need to resume it by hand: write to it and it starts again. Its box says **Message to resume it**.
## Archive a task
Archive a task to take it out of the sidebar and the board.
1. Choose **Archive…** from the task's menu in the sidebar, the **⋯** in the title bar, or the **⋯** on the board.
2. A dialog asks you to confirm, such as **Archive "Fix the flaky login test" and its 2 workers?**. Click **Archive**, or press ↩. **Cancel** or Esc keeps the task.
Archiving stops the task and its workers. To bring one back, click the sliders button beside **Tasks** › **Archived tasks…**. Find it with **Search** and click **Unarchive**. Its workers come back with it.
## Rewind a task
Rewinding takes a task back to before one of your messages: its conversation, the files in its folder, or both.
1. Press Esc twice quickly on the task's page, or choose **Rewind…** from the **⋯** menu on one of your messages.
2. In **Rewind to**, pick the message with ↑↓ and ↩.
3. The card says what's changed in the folder since then, such as "Since this message: 3 files changed, +40 −12." Choose what to do:
| Choice | What it does |
|---|---|
| **Restore conversation and code** | Back to before this message, files and all. |
| **Restore conversation** | The conversation goes back. The files stay as they are now. |
| **Restore code** | The files go back. The conversation carries on as it is. |
| **Branch from here** | Starts a new task from before this message. This one stays as it is. |
| **Never mind** | Closes the card. |
When the conversation goes back, your message returns to the composer, so you can change it and send it again.
When the folder is in a Git repository, Zero keeps a copy of it each time you send a message. When there's no copy for that message, the card says **Zero didn't keep the folder for this message, so only the conversation can go back.** Zero also keeps a copy before it restores the files, so you can rewind the restore too.
## See every task at once
Click **All tasks** in the tasks sidebar. The board lists the workspace's tasks in two tables:
- **Running**: agents at work now, the most urgent first.
- **Offline**: tasks that aren't running. Each shows the state it was last in. A message resumes it.
| Column | What it shows |
|---|---|
| **Task** | The task's name, and how many workers it has. |
| **Where** | Where the task runs. Shown only when the tasks are in more than one place. |
| **State** | The state, and what the task needs from you: its first open ask, or the step it handed over. |
| **Now** | What the task is doing now, in its own words. |
Click a row to open the task. Its **⋯** menu, called **Actions**, has **Ask for a status update**, **Open**, **End session** or **Resume**, **Pause** or **Resume**, **Copy task id** and **Archive…**. With **Ask for a status update**, the agent answers in a few lines and posts where it stands.
## Use the agent's own terminal
Some things only a provider's own terminal app can do. Click the terminal button in the title bar to swap the conversation for that terminal. The terminal picks up the same conversation. The button's tip names the provider, such as **Open in Codex's own terminal, for what only it has**. The details pane stays beside it.
In the terminal, ⌘C, ⌘V and ⌘A copy, paste and select all. Files you paste or drop go in as their paths. The terminal uses the font from your Ghostty config, when you have one.
To go back, click the button again. Its tip then reads **Back to Zero, with what happened in the terminal**. A terminal left untouched for 15 minutes closes, and the task comes back to Zero. The terminal won't open while the agent is working, and Zero's composer, steering and queue aren't there while it's open.
---
# The inbox and asks
Everything your agents ask you, in one place, and how to answer.
When an agent needs something from you, it sends an ask: a question, a choice, an approval or a command to run on your Mac. Every ask lands in the inbox, from tasks in Zero and from agents outside Zero, such as Claude Code in a terminal. You answer it once, wherever you see it first.
## Open the inbox
Your asks show in two places:
- **The inbox panel**, beside the control bar on the right edge of your screen. Point at the tray icon at the top of the bar to peek at the panel, or click the icon to keep it open. A red dot on the icon means at least one ask is waiting. See [The control bar](/docs/control-bar).
- **The Inbox page** in Zero's window. Click the tray icon in the window's left rail. Its tip reads **Inbox**. A red badge on the icon shows how many asks are waiting on you.
The **Talk hotkey** works from any app: ⌥Space unless you've changed it. It opens the inbox panel on the oldest waiting ask and starts dictation, so you can answer by speaking. See [Answer by speaking](#answer-by-speaking).
When **Bar in the window** puts the control bar in Zero's window, clicking the bar's inbox icon opens the Inbox page instead of the panel. Pointing at it still peeks at the panel.
## Read the inbox panel
The panel lists the asks waiting on you as cards, oldest at the top. Answers you've given since you opened the panel stay in the list until you open it again. When nothing waits, the panel shows **Inbox empty**.
Each card has:
- **The question** in bold. For a command, it reads **Allow this command?**
- **Who asked** under it: the agent's name, and the title it gave the ask.
- **Why**, in the agent's words. Zero folds long text to three lines. Click it to read it all, and click again to fold it.
- **A command box**, when the ask is about a command. **Copy** copies the command. A long command shows **Show all** and **Show less**. When the command runs a script, the script shows under the command, with **Show the whole script** for a long one. When the command runs in a folder other than the agent's own, that folder shows under it.
- **The answers** as numbered rows, or a box for your reply.
Pull requests, commits, issues and Slack channels named in the question or the why are links, as they are in a conversation. See [Following and integrations](/docs/following-and-integrations).
Point at a card or click it to select it. When more than one ask is waiting, Zero dims the cards you haven't selected, so you can see which one your keys answer.
Pointing at an agent's mark on the bar instead shows just that agent. See [Read one agent's history](#read-one-agents-history).
## Answer an ask
Click an answer's row, or type its number.
- **Number keys.** In the panel, 1, 2 and 3 pick the first three answers of the selected card. Every row shows its number, but only the first three answer from the keyboard. Click any row after the third.
- **Arrows.** ↑ and ↓ select the card above or below.
- **Typing.** Start typing and your words go into the selected card's reply box. When the card has an answer that ends in "…", such as **Suggest something else…**, that answer opens into a box and takes your words. When the card has neither, your words go into the message box of the agent you're looking at. Return puts the cursor in that box without typing anything.
- **Sending.** Press Return in a reply box to send, or click the paper plane at its right. Paste an image with ⌘V and its file path goes into your reply, for the agent to open.
Once you pick an answer:
1. The row turns orange with a spinner. For a moment, you can take it back. See [Take an answer back](#take-an-answer-back).
2. The row turns green with a tick once the agent has it. The other rows fade.
3. When Zero can't reach the agent, the row turns red with a cross. Point at it to read **Couldn't reach the agent. Click to try again.**, and click it to send the answer again.
Three seconds after your answer lands, the panel selects the next waiting ask. To stay on the card you answered, turn off **Move to the next ask** in **Settings › Composer and inbox › Inbox**.
Press Delete to remove a finished card from the panel.
## Answer by speaking
1. Press the **Talk hotkey**, ⌥Space unless you've changed it. The panel opens on the oldest waiting ask and starts listening.
2. Speak your answer. Your words show in the card's reply box, or in the box of its answer that ends in "…". A red waveform in place of the microphone shows that Zero is listening.
3. Press the Talk hotkey again to stop listening, then press Return to send.
In the panel, Space starts and stops dictation too, and so does the microphone button in a reply box.
Dictation needs a box to type into. On a card with only fixed answers, such as **Yes** and **No**, and no message box for the agent, click an answer or press its number instead.
To change the hotkey, go to **Settings › General › Zero › Talk hotkey**. Click the button and press the new keys. It needs at least one of ⌘, ⌥, ⌃ or ⇧. Esc cancels. To choose the microphone, go to **Settings › Composer and inbox › Dictation › Microphone**. It's **System default** unless you pick one.
## Take an answer back
Picked the wrong answer? Press Esc in the inbox panel while the row is still orange. The card goes back to waiting, with nothing chosen, and you can answer again.
You have 2 seconds unless you change it. Set the time in **Settings › Composer and inbox › Inbox › Take-back window**, from 0 to 5 seconds in half-second steps. At 0, every answer goes at once.
Taking back works only in the inbox panel. Once the row turns green, the agent has your answer.
## The kinds of ask
### A question
The agent asks something and waits for your words. The card shows the question and a box that reads **Reply to** and the agent's name. Type or dictate your answer and press Return.
### A choice
The agent asks a question with answers to pick from, each a numbered row. Picking an answer that ends in "…" opens a box so you can say more, and the agent gets the answer and your words together.
One choice has its own look: **Is this task done?**, in purple, with **Done** and **Not yet…**. An agent asks it when it isn't sure its work is finished. **Done** marks the task done. **Not yet…** opens a box to say what's left.
### An approval
The agent asks whether it can do something, such as "Delete the old build folder?". The answers are **Yes**, **No** and **Suggest something else…**. Both **No** and **Suggest something else…** count as declining.
### A command to run
The agent wants to run a command on your Mac and see its output. The card reads **Allow this command?**, with the command in a box and why the agent needs it above. The answers are:
| Answer | What it does |
|---|---|
| **Run** | Runs the command on your Mac. |
| **Run, and allow the same for this task** | Shows only when the agent offers it. Runs the command, and later commands of the same kind from the same task, in the same folder, run without asking. "The same kind" means the same command with a different file path after it. |
| **Reject** | The command doesn't run. |
| **Suggest something else…** | Opens a box to tell the agent what to do instead. The command doesn't run. |
While the command runs, the card reads **Running command…** and its output scrolls in the box. **Stop**, in red, stops it. When the command has a terminal of its own, **Terminal** shows it in place of the output, and **Output** switches back.
Then the card reads **Ran command**, **Command failed (exit** and its exit code **)**, or **Command rejected**. When Zero lost track of the command while it ran, the card reads **Lost track of the command**, with **Lost: check what it did before running it again** under it.
When several agents ask for the same command in the same folder, they share one card. Its byline reads, for example, "and 2 other agents". One answer goes to all of them.
### A command for you to run yourself
Sometimes the agent can't run a command itself, for example because it has to run on another machine. The card then shows two steps:
1. **Run this**, with the command. Click **Copy**, run it where it needs to run, and copy what it printed.
2. **Then tell** and the agent's name. Click **Paste output** to put what you copied into the reply, then press Return to send.
### A note
A note tells you where an agent stands. It needs no answer and never shows in the inbox's list. Notes show in the agent's view in the panel. A note that says the agent is blocked has a red **Blocked** label.
### A permission
Before a tool acts, the agent's CLI can ask for your permission. Zero turns the request into an ask.
Claude Code can run in a terminal that Zero starts. It can also work beside a drop folder, a synced folder that agents on other machines use to reach your inbox. In both cases, the question says what Claude Code wants to do, such as **Run a command?**, **Edit a file?**, **Write a file?** or **Fetch a page?**. The box shows the command, file or address.
The answers are **Allow**, **Always allow**, **Deny**, and **Deny, and say why…**. **Always allow** shows only when Claude Code suggests a rule to remember. Only the **Deny** answers count as declining.
From a task in Zero, the question reads **Allow this command?** or **Allow these changes?**, and the answers are the agent's own:
| Agent | Answers |
|---|---|
| Claude Code | **Allow**, **Deny** and **Deny and stop**. When Claude Code offers one, also **Always allow** and the rule, or **Allow all edits this session**. |
| Codex | **Allow**, **Allow for this session**, **Deny** and **Deny and stop**. When Codex offers it, also **Always allow** and the command. |
| OpenCode | OpenCode's own answers |
## Answer in a task's conversation
When a task in Zero asks you something, its ask also shows in the task's conversation, docked above the composer. It's the same ask: answer it here or in the inbox, and it's answered in both.
The strip at the top of the docked card says what it is:
- **Question**, or **Questions** when the agent asks several at once. When the agent gave a question a heading, the strip shows that instead.
- **Approval**, with a shield, when the agent's CLI asks permission.
- **Run on your Mac**, **Approval** or **Question** for asks the agent sent through Zero.
One card shows at a time. When several are waiting, the strip shows where you are, such as **1 of 3**, with arrows to step between them.
To answer from the keyboard:
- When the composer is empty, type 1 to 9 to pick that answer of the first ask the agent sent through Zero. This doesn't work while the CLI's own question or permission request is docked.
- On a permission request, Return picks the first answer when you're not typing in the composer.
A permission request folds a long command after eight lines. To read the rest, click **Show all** and the number of lines.
Some questions ask for a secret, such as a password. The agent asks these only in the task's conversation, never in the inbox, as a form with a **Secret** box and an **Answer** button. The form also shows for a question before it reaches the inbox, with the answers as buttons and a box that reads **Your answer** or **Or say something else**.
In the conversation itself, each ask the agent sent through Zero is a step that reads **Asked**, or **Asked to run** for a command, then what it asked. At its right is what became of it: **Waiting on you**, **Running**, **Ran**, **Failed (exit** and the code **)**, **Declined**, **Expired**, or the answer you picked.
## Find answered asks on the Inbox page
The Inbox page in Zero's window lists every ask in a table. To open it, click the tray icon in the window's left rail. It always opens on **Waiting on you**.
Its sidebar has:
- **Waiting on you**, with how many: the asks waiting, oldest first.
- **Answered**: the last 50 asks you've answered, newest first.
- **Agents**: one row for each agent that has asked you something. An orange dot and a count mean that agent has asks waiting, and a grey dot means none. Click an agent to see its waiting asks, then its answered ones.
The table's columns are:
| Column | What it shows |
|---|---|
| **Ask** | The ask's title. |
| **Agent** | The agent that asked. |
| **Kind** | **Question** for questions and choices, **Approval** for approvals and permissions, **Command** for commands to run. |
| **When** | When it was asked, in orange while it waits, then when it was answered once it's done. A declined ask adds **· declined**. |
Click a row to open its card under it, and answer it there as in the panel. The oldest waiting ask opens on its own. Click the × at the card's right to close it. Its tip reads **Fold it back**. The number keys, and Esc to take an answer back, work in the inbox panel, not on this page.
## Read one agent's history
Point at an agent's mark on the control bar, or click it, to see just that agent in the panel. From the top:
- **Earlier**: a short list of what came before, newest at the bottom. It shows six rows at a time and scrolls. Each row has how long ago it was, an icon for its kind, and one line. The line is **You:** and your message, the agent's name and its note, or an ask with what became of it: **· rejected**, **· ran, exit 0**, or the answer. **Closed** marks where the agent was removed or went offline.
- **The latest exchange**: your last message, and what the agent has said since. While it works on your message, a row reads the agent's name and **is working…**.
- **The latest answer**, for a task in Zero, when it's newer than the task's last ask or note. The card shows the task's name, how long ago it answered, and the first part of the answer. **Open task** opens it in Zero's window.
- **The asks still waiting** from this agent.
- **A message box**, **Message** and the agent's name, when Zero can reach the agent.
Click a row in **Earlier** to read it in full under the list: the whole message, or the ask with its answer and, for a command, its output. Click it again to close it. To start a message that quotes a row, point at it and click the arrow at its right. The arrow's tip reads **Reply to this**.
When nothing has come from the agent yet, the panel reads **Nothing from this agent yet**.
## When an ask expires
An ask you don't answer in time expires and leaves the inbox and the Inbox page. In a task's conversation, its step reads **Expired**.
| Ask | Expires after |
|---|---|
| Asks where the agent set no time | 60 minutes unless you change **Ask expiry** |
| Asks where the agent set its own time | The agent's time |
| Permission requests from a task in Zero | 24 hours |
To change the default, go to **Settings › Composer and inbox › Inbox › Ask expiry**. It takes 5 to 1,440 minutes, in steps of 5.
An agent can also withdraw an ask it no longer needs, and it leaves the inbox the same way. When the ask was a command that's running, the command stops.
## Get told when an ask arrives
How you hear about a new ask depends on where you are:
- **In Zero**, with Zero in front and you at the Mac: a sound plays and the control bar shows the ask.
- **Away from Zero**, in another app, away from the Mac or with the screen locked: a macOS notification. For an agent outside Zero, it's titled with the agent's name and shows the question, **Wants to run:** and the command, or **Wants your approval:** and what it wants.
An ask from a task in Zero counts as the task's notification. The task's state turns to **Needs you**, and you hear the sound for that state. Clicking a task's notification opens the task in Zero's window. While you're in Zero, a task that needs you plays its sound. When it still needs you five minutes later and you haven't used the Mac since the sound, the notification goes too.
A notification goes away by itself when you answer or the ask expires or is withdrawn. It also goes when you look at the task, the inbox or the agent.
While Zero's window is open, Zero's icon in the Dock shows how many tasks need you.
These settings are in **Settings › General**. Open Settings with ⌘, or the gear at the foot of the window's left rail.
| Setting | Where | What it does |
|---|---|---|
| Needs you | Settings › General › Notifications | Tells you when a task, one of its workers, or an agent outside Zero asks you something. On by default. |
| Sounds | Settings › General › Notifications | Plays a sound with each notification, and a sound instead of one while you're in Zero. On by default. |
| Needs you | Settings › General › Sounds | The sound for a task that needs you. **Blow** by default. Asks from agents outside Zero play **Glass** while you're in Zero. |
macOS's own settings for Zero, and Focus, can quiet its notifications as they do for any app.
## Settings for the inbox
Most are in **Settings › Composer and inbox**.
| Setting | Where | What it does |
|---|---|---|
| Take-back window | Settings › Composer and inbox › Inbox | How long Esc can take an answer back: 0 to 5 seconds. 2 seconds by default. |
| Move to the next ask | Settings › Composer and inbox › Inbox | On: 3 seconds after an answer lands, the panel selects the next waiting ask. On by default. |
| Ask expiry | Settings › Composer and inbox › Inbox | How long an ask waits when the agent set no time: 5 to 1,440 minutes. 60 minutes by default. |
| Microphone | Settings › Composer and inbox › Dictation | The microphone dictation uses. **System default** by default. When the one you picked isn't connected, it reads **Not connected; the system default is used.** |
| Talk hotkey | Settings › General › Zero | The keys that open the inbox and start dictation, from any app. ⌥Space by default. |
Zero records every ask and answer in `~/.zero/asks.jsonl`. To open it, right-click the control bar and choose **Open Log**.
The iPhone app, coming soon, shows the same asks and has a **Take back** button on an answer you've just picked. See [The iPhone app](/docs/iphone).
---
# The control bar
The small bar on the edge of your screen that keeps your agents in view.
The control bar is a small bar on the right edge of your screen, halfway down. It stays on top of other apps, so your agents stay in view while you work in another app. Point at the bar and the inbox opens beside it.
## What the bar shows
From the top:
- **The inbox.** A tray icon. A red dot on it means at least one ask is waiting for you.
- **The workspace.** Its icon shows only when you have more than one workspace. Click it to see your workspaces and switch to another one.
- **A line**, then **one mark for each task** in the workspace, workers included. They're in the same order as the window's sidebar. Each mark is the task's state icon, the same one the sidebar shows. A blue spinner means the task is working.
- **Agents outside Zero**, such as Claude Code in a terminal. When one asks you something, it shows as a coloured dot after the tasks.
The task states:
| Icon colour | State | What it means |
|---|---|---|
| Blue hand | Needs you | The task, or one of its workers, asked you something. |
| Orange triangle | In trouble | The task failed, got stuck or ran out of usage. |
| Red minus | Blocked | The task can't go on until something outside you and the agent changes, such as an outage. |
| Blue spinner | Working | The task is working. |
| Teal box | Over to you | The task is done, and there's a step left for you. |
| Indigo speech bubble | Replied | The task answered you. It turns grey once you've read it. |
| Grey hourglass | Waiting | The task is waiting on someone else, such as a review. |
| Purple badge | Done | Nothing is left to do. |
## Open the inbox from the bar
- **Point** at the inbox icon or at a task's mark. The inbox opens beside the bar and shows the asks, or that task. A task's view shows its latest answer, with **Open task** to open it in Zero's window.
- **Click** to keep the inbox open. To close it, click the same icon or mark again, or press Esc.
- **Click a task's mark.** When the task has asked you something, its asks open in the inbox. Otherwise the task opens in Zero's window.
While the inbox is open, 1, 2 and 3 pick an answer. See [The inbox and asks](/docs/inbox-and-asks).
## Change the order
Drag a mark up or down the bar. The window's sidebar takes the same order.
## Use a mark's menu
Right-click a task's mark for its menu, beside the bar:
| Item | What it does |
|---|---|
| **Open** | Opens the task in Zero's window. |
| **Pause** / **Resume** | Puts the task and its workers on hold, or takes them off hold. |
| **Move to Later** | Puts the whole task in Later. See [Later, scratchpads and loops](/docs/later-scratchpads-loops). |
| **Archive…** | Opens the task and asks you to confirm archiving it. See [Tasks and workers](/docs/tasks-and-workers). |
Right-click the mark of an agent outside Zero:
- **Open in Terminal** shows the terminal the agent runs in, when Zero started that terminal.
- **Remove** closes the agent in the inbox. Its open asks expire, and a **Closed** note stays in its history.
- **Remove and stop** does the same and also stops the agent. It shows in place of **Remove** when Zero can stop the agent.
## Use the bar's menu
Right-click the bar for:
- **Open Log**: opens `~/.zero/asks.jsonl`, the file where Zero records every ask and answer.
- **Settings…**: opens Zero's settings.
- **Quit Zero**: quits the app.
## Settings for the bar
These are in **Settings › Control bar**. Open Settings with ⌘, or the gear at the foot of the window's left rail.
| Setting | Where | What it does |
|---|---|---|
| Follow the active screen | Settings › Control bar › Placement | On: the bar moves to the screen you're using. Off: it stays on the screen where it first appeared. |
| Bar in the window | Settings › Control bar › Placement | Puts the bar in Zero's window, not on the screen's edge: **When it fills the screen**, **Always** or **Never**. **When it fills the screen** is the default. |
| Agents in the bar | Settings › Control bar › Agents in the bar | The agents outside Zero that the bar shows. Rename or remove one, or drag them into a new order. A removed agent comes back when it next asks you something. |
The **Talk hotkey** opens the inbox and starts dictation, so you can answer by speaking. It's ⌥Space unless you change it in **Settings › General › Zero › Talk hotkey**.
---
# Accounts and models
Sign in Claude Code, Codex and OpenCode, and pick the model for a task.
Zero keeps accounts for Claude Code, Codex and OpenCode. Each time a task starts, Zero gives one account to the agent. The agents talk to their providers themselves; Zero never does. Your keys and tokens stay in your Keychain.
Accounts in Zero are optional. When Zero has no account for an agent, the agent's tasks use the sign-in that the agent already has, the one it uses in Terminal. After you add an account for an agent, its tasks use Zero's accounts.
## Open the Accounts page
Open **Settings › Accounts**. To open Settings, press ⌘, or click the gear at the foot of the window's left rail.
The page has a section for each agent: **Claude Code**, **Codex** and **OpenCode**. Each section lists its accounts. A section with no accounts shows **None yet**. **Add model** and **Add account** are beside the agent's name.
## Add an account
Click **Add account** beside the agent's name and choose how to sign in:
| Agent | Choice | What happens |
|---|---|---|
| Claude Code | **Sign in with Claude** | Claude's sign-in page opens in your browser. Sign in there. If the page shows a code, paste it into **Its code, if Claude shows one** and click **Send**. The account's tasks get a token that lasts a year. Zero keeps it in your Keychain. |
| Claude Code | **Anthropic API key** | Type **A name for it** and **Its API key**, then click **Save**. You pay for each use. |
| Codex | **Sign in with ChatGPT** | ChatGPT's sign-in page opens in your browser. Until you finish the sign-in, the account shows on the page with **Signing in… finish in your browser**. |
| Codex | **OpenAI API key** | Type a name and the key, then click **Save**. You pay for each use. Codex keeps the key in a separate folder for this account. |
| OpenCode | **OpenCode Go key**, **Anthropic key**, **OpenAI key** or **OpenRouter key** | Type a name and the key, then click **Save**. Zero gives the key to OpenCode in the variable of that provider, such as `OPENCODE_API_KEY`. |
- If Claude doesn't say whose account it is, the new row asks **Whose account is this? (its email, or a name)**. Type one and press Return.
- A ChatGPT sign-in goes away when you refuse it, or when you don't finish it within 15 minutes. To try again, add it again.
- If a Claude sign-in fails, the dialog says why and shows **Try again**.
Under each account's name, its row says what it is:
- Its plan, as the agent reports it: a Claude plan, or ChatGPT and its plan.
- **Subscription**, when Claude doesn't say which plan.
- **API key**. For OpenCode, the name of the key's variable comes after it.
## Rename or remove an account
Click **⋯** at the end of the account's row to open its menu:
- **Rename**: type a new name and press Return. Esc cancels.
- **Switch to a token**: shows for a Claude account whose row says **its own folder: your MCP sign-ins aren't shared**. It opens Claude's sign-in again. With the token it gets, the account shares your MCP sign-ins.
- **Remove…**: the row asks again. Click **Remove** to confirm, or **Cancel**. The tasks of a removed account can't restart with it. To get the account back, sign in again.
## See how much usage is left
Click an account's row to open it in place. It shows a tile for each allowance its plan has:
- **Last 5 hours**: how much of the five-hour allowance is used.
- **This week**: how much of the weekly allowance is used.
Each tile shows the share used, a bar and when the allowance resets. The bar turns orange at 90% and red at 100%. An account at a limit shows **At its limit** on its row. Click the row again to close it.
Under the tiles, **Activity** has a square for each day, darker the more turns the account's tasks finished that day. The count starts on the day Zero began to keep it.
While the page is open, Zero asks each agent for its accounts' usage every two minutes. API keys have no allowance, so they show no tiles.
The foot of the tasks sidebar also shows the accounts your tasks used in the last day, with a **5h** and a **Week** bar each. Point at a bar to see when it resets. Click the card to open **Settings › Accounts**.
## Which account a task uses
You don't pick a task's account. Zero picks one when the task starts:
- A worker of the same agent uses the same account as the task that started it.
- For other tasks, Zero leaves out accounts that are at a limit, and accounts that can't use the task's model. From the rest, it picks the account with the least weekly allowance left. So Zero uses up one account before it goes to the next, and the other accounts keep their allowance. When two accounts are equal, the one that resets sooner goes first.
- When every account is at a limit, Zero uses the first account in the agent's list.
## When a task changes account
A task keeps its account until one of these happens:
- **The account reaches a usage limit.** The task continues on another account of the same agent, with its conversation. Zero tells the agent, and the agent continues from where it stopped.
- **The account can't use the task's model.** Zero records that the account can't use that model, and the task continues on an account that can. Zero doesn't pick that account for that model again.
When no other account can take over, the task stops. For a usage limit, the task shows **Usage limit** at the end of the conversation, with the time when the limit resets. After the reset, the task continues by itself. To continue sooner, click **Continue with Codex** or **Continue with Claude Code** there. The other agent then takes over the task and its whole conversation.
When an account's key is missing from your Keychain, the task doesn't start. It shows "isn't in the Keychain any more: sign in again". Remove the account and add it again.
## Pick a model and effort for a new task
To open the **New task** page, click **Home**, the house at the top of the window's left rail. On the right of the row under the box, a chip shows the agent's icon, the model and the effort, such as "Model · High".
1. Click the chip. It has a tab for each agent: **Claude Code**, **Codex** and **OpenCode**. To switch agent, click a tab or press ← and →.
2. Point at a model, or move to it with ↑ and ↓. The pane beside the list describes the model. For models that have levels, the pane also shows an **Effort** slider.
3. Click the model, or press Return. Or move the **Effort** slider. The slider picks the model at that level and keeps the list open. Esc closes the list.
When you pick no model, the task uses the agent's first model. OpenCode uses the default from its own configuration. The effort levels are different for each model. On the chip, Zero shows **Extra High** as "XHigh".
Zero remembers the agent you picked last and uses it for the next new task.
## Change the model during a task
In a task, the same chip is in the composer, at the foot of the conversation.
- **Between turns**, the model and effort you pick apply from your next message.
- **While the agent works**, your choice waits for the next turn. The chip shows a mark. When you point at it, it shows **From the next turn**.
The list also shows the models of the other agents. When you pick one, the task moves to that agent with its whole conversation. Claude Code and Codex can take over a task. OpenCode can't.
## Add a model the list doesn't show
Sometimes a new model is available before an agent lists it. To add it to Zero:
1. Open **Settings › Accounts**.
2. Click **Add model** beside the agent's name.
3. In **Add a Claude Code model**, or the Codex or OpenCode form, type the model's id in the form that the agent accepts. For example, `claude-mythos-5-2`, `gpt-5.5-codex`, or `provider/model` for OpenCode.
4. Optionally, type a name for the list, such as "Mythos 5.2". Without one, the list shows the id.
5. Click **Add**.
The model shows under the agent's accounts and in every model list for that agent. All of the agent's accounts offer it.
When an account turns out not to have the model, its tasks on that model run on your other accounts. The model's row then says **Not on** and that account. When none of your accounts can use the model, the row says **None of your accounts can use it**. To take a model out, click **Remove**.
## Where the lists come from
- **Claude Code**: **Fable**, **Opus**, **Sonnet** and **Haiku**, which Claude Code resolves to the latest model of each. Then the models that Claude Code has offered your account, such as the 1M-context versions, and the models you added. Zero reads these from Claude Code's own files and never calls Anthropic.
- **Codex**: the models that Codex offers your account, as Codex lists them, plus the models you added.
- **OpenCode**: its own list, which Zero reads when you open the chip. The rows fill in after Zero reads the list.
---
# Workspaces and folders
Keep tasks apart by workspace, and tell Zero which folders your projects are in.
Workspaces keep your tasks apart by who they're for, such as your own projects and your job. Projects are the folders your tasks start in. **Settings › Git** sets how agents commit in them.
Open Settings with ⌘, or the gear at the foot of the window's left rail.
## What a workspace is for
Each task belongs to one workspace. The window's tasks sidebar, the board, **All tasks**, and the control bar show only the tasks of the workspace you're looking at.
Switching changes only what you see. Tasks in every workspace keep running, and their asks still reach your inbox.
Zero always has a workspace called **Zero**, which you can't rename or delete. A task is in the Zero workspace unless it started in another workspace or you moved it.
These things act on the workspace you're looking at:
- **New task** starts tasks there, unless you pick another in its workspace chip.
- The workers a task starts go into its workspace.
- ⌘1 to ⌘9 open that workspace's first nine tasks.
- **Pause all tasks** and **Resume paused tasks**, in the sliders menu beside the sidebar's **Tasks** heading, act on that workspace's tasks only.
A workspace can also have MCP servers for its own tasks only. See [Browsers and MCP servers](/docs/browsers-and-mcp).
## Create a workspace
From the window:
1. Click the workspace's name at the top of the tasks sidebar.
2. Choose **New workspace…**.
3. Type a name and click **Create**.
From Settings:
1. Go to **Settings › Workspaces** and click **Add workspace**.
2. Type a **Name** and pick an **Icon**.
3. Click **Save**.
A new workspace gets the first icon in the grid until you pick another.
## Switch workspace
- **In the window**: click the workspace's name at the top of the tasks sidebar, then click another workspace. A tick marks the one you're looking at. **Workspace settings…**, in the same menu, opens **Settings › Workspaces**.
- **In the control bar**: click the workspace's icon, below the inbox. The icon shows only when you have more than one workspace.
Each workspace reopens the task you last had open in it. When you open a task from another workspace, for example from the inbox or a notification, the window goes to that task's workspace.
## Change a workspace's name, icon or servers
1. Go to **Settings › Workspaces**. The workspace you're looking at has a **Shown** pill.
2. Point at a workspace and click the pen, **Edit**, or double-click its row.
3. Change its **Name**, pick an **Icon** from the grid, or tick the **MCP servers** its tasks get. Servers that every workspace gets show as "(every workspace)", and you can't untick them here. Add and change servers in **Settings › MCP servers**.
4. Click **Save**.
The icon shows beside the workspace's name in the tasks sidebar, in the control bar and in Settings. Zero's own workspace shows Zero's mark until you pick an icon for it.
## Delete a workspace
In **Settings › Workspaces**, point at the workspace and click the bin, **Delete: its tasks are Zero's again**. Zero doesn't delete its tasks: they move to the Zero workspace.
## Move a task to another workspace
Right-click the task in the tasks sidebar and choose **Move to** and the workspace's name (**Move to Zero** puts it back in the Zero workspace). These show only when you have more than one workspace. The task's workers go with it.
## Add your projects
Tasks start in a project: a folder on your Mac that you added to Zero. Every workspace shares the same projects.
1. Go to **Settings › Folders**.
2. Next to **Projects**, click **Add folder**.
3. Choose one or more folders and click **Open**.
Your projects then show in the project chip on the **New task** page. Until you add one, that page says **Add a project in Settings › Folders** in place of its chips.
Each project shows with its folder's name. Point at a row to see the folder's full path. Click a row for its menu:
| Item | What it does |
|---|---|
| **Rename…** | Gives the project a name of its own in Zero, used in the project chip and a task's **Where**. Zero doesn't rename the folder. Clear the name to go back to the folder's own. |
| **Show in Finder** | Shows the folder in Finder. |
| **Remove** | Takes the folder off the list. The folder and its files stay on your Mac, and tasks that already run there continue. |
**Drop folders**, on the same page, are synced folders that agents on other machines use to reach your inbox. To add one:
1. Click **Add drop folder**.
2. Type a pattern such as `~/projects/*/.zero`, or click **Choose…**.
3. Click **Add**.
To take a drop folder off, click its row and choose **Remove**.
## Set how agents commit
**Settings › Git** gives your agents a Git identity of their own. When it's on, you stay the author of their commits, but the identity you set here commits and signs them. Pushes use the GitHub CLI's sign-in.
So nothing waits on your own signing key: agents commit and push while your key is locked or you're away. Only the agents' processes get this identity. Your own Git settings and your own terminal keep yours.
| Setting | Where | What it does |
|---|---|---|
| Sign with the agents' own key | Settings › Git › Agents' commits | Turns the agents' identity on. Off by default. |
| Account | Settings › Git › Agents' commits | The GitHub account that commits and signs. Click **Choose…** or **Change…**, type the account's login and click **Use**. Its name and GitHub's noreply email become the committer. |
| Signing key | Settings › Git › Agents' commits | The private key the agents sign with. It must have no passphrase. Click **Choose…** or **Replace…** and pick the key file. A pill shows **On** and the login when the key is one of the account's signing keys on GitHub, so commits show as Verified. **Not on** means you still need to add it to the account as a signing key. |
| Push over HTTPS | Settings › Git › Agents' commits | Pushes to GitHub over HTTPS with the GitHub CLI's sign-in, instead of SSH, which can wait on your own key. On by default. |
| Folders | Settings › Git › Folders | Keeps the agents' identity to these folders and the folders inside them. Click **Add folder** to add one, and **Remove** to take one off. With no folders added, it reads **Every folder**, and agents in all folders commit this way. |
The identity applies only when it's on and both an account and a signing key are set. Push over HTTPS also applies only then.
---
# Later, scratchpads and loops
Save work for later, keep notes your agents can read, and keep instructions you give agents by name.
Three places in Zero's window keep things that you and your agents come back to:
- **Later**: work to pick up another time. Each item has a short note and everything behind it.
- **Scratchpads**: Markdown notes that you and every agent can read and write.
- **Loops**: named instructions that you give an agent when you type `@name`.
Each has a button on the window's left rail, below **Inbox**, in this order. Point at a button to see its name. To open the window, choose **Show Zero**, ⌘0, in the menu bar icon's menu.
## Save something for later
A Later item has two parts. The note says in one sentence what to do. The artifact holds everything behind it in full, such as an agent's findings or a plan.
Items come to Later in four ways.
**Write one yourself.**
1. Click **Later** on the rail.
2. At the top of its list, click the compose button, **Write one**.
3. Fill in **What's to be done, in a sentence**.
4. Fill in **Anything behind it, in Markdown (optional)**, or leave it empty.
5. Click **Save**.
**Ask a task to save one.** The agent writes the note and the artifact from what it has learned. There are two ways:
- Right-click the task in the tasks sidebar and choose **Save for later**.
- To save one of the agent's answers, point at the answer, click its **⋯** and choose **Save for later**.
The agent saves the item after its current turn.
**Move a whole task there.** Right-click a task in the tasks sidebar or its dot in the control bar, or open the **⋯** menu in the window's title bar. Then choose **Move to Later**. The task leaves the sidebar, and it and its workers pause. Zero doesn't archive the task. In Later, it shows with a **Task** pill.
**Agents suggest them.** An agent can save an item unasked when it expects you'll want to come back to it. These items go under **Suggested by agents** at the foot of the Later list. The heading shows how many there are. Click the heading to show them. Zero deletes a suggestion a week after it was saved, unless you click **Keep**.
## Use a Later item
Click an item in the Later list to open it. The item shows its note, the task it came from, when it was saved, the links and files that came with it, and its artifact. Click the task's name to open that task.
| Button | What it does |
|---|---|
| **Resume task** | For a task you moved to Later. Puts the task back in the sidebar, takes it and its workers off hold, and marks the item done. |
| **Start a task from this** | Opens **New task** with the item in its box, ready to send. |
| **Send to a task** | Pick a task in this workspace. Zero sends the item to that task and opens the task. |
| **Copy** | Copies the note and the artifact. |
| **Keep** | For suggestions. Keeps the item in Later. Without it, Zero deletes the item a week after it was saved. |
| **Done** / **Not done** | Marks the item done, or open again. Done items stay in the list, struck through and faded. |
| **Version N** | Shows when an agent changed the item. Pick an earlier version to read it. |
| **Delete** / **Dismiss** | Deletes the item. Suggestions say **Dismiss**. When you delete a task that you moved to Later, the task goes back in the sidebar and stays paused. |
Right-click an item in the list for **Copy link**, **Done** or **Not done**, and **Delete** or **Dismiss**. For a task you moved there, the menu also has **Resume task**. For a suggestion, it also has **Keep**.
An item's link looks like `zero://later/`. To point an agent at the item, paste the link in a message.
### How agents use Later
Agents save, list, read and change Later items with the `zero later` command, for example:
```sh
zero later save "Retry the flaky login test with a longer timeout" --file notes.md
```
A task keeps at most three suggestions open at a time. See [The zero command](/docs/cli).
Zero keeps Later items in `~/.zero/later`.
## Keep notes in a scratchpad
Scratchpads are Markdown notes in folders that you and your agents share. Use them for plans, checklists, findings, or anything else for an agent to read.
Click **Scratchpads** on the rail. At the top of the list:
- **Search** finds pads by their title or folder. The ×, **Clear**, empties the search.
- **New scratchpad** makes a pad.
- **New folder** makes a folder.
Right-click a folder for **New scratchpad here**, **New folder inside** and **Show in Finder**.
Right-click a pad for:
| Item | What it does |
|---|---|
| **Copy link** | Copies the pad's link. |
| **Copy Markdown link** | Copies the link as Markdown, with the pad's title. |
| **Rename…** | Renames the pad. |
| **Move to** and a folder's name | Moves the pad to that folder. Each folder has its own item. **Move to Scratchpads (top)** moves it out of its folder. |
| **Show in Finder** | Shows the pad's file. |
| **Move to Trash** | Deletes the pad. |
Zero keeps each pad as a Markdown file in `~/.zero/scratchpads`. Each of your scratchpad folders is a folder there.
## Write in a scratchpad
Click a pad to open it. Type its title over **Untitled** at the top. Write the text below it, in Markdown. Zero saves as you type. Under the title, the pad shows its folder and the time of the last edit.
The formatting buttons and their keys:
| Button | Keys |
|---|---|
| **Bold** | ⌘B |
| **Italic** | ⌘I |
| **Strikethrough** | ⇧⌘X |
| **Code** | ⌘E |
| **Link** | ⌘K |
| **Heading** | ⌥⌘1 |
| **Subheading** | ⌥⌘2 |
| **Small heading** | ⌥⌘3 |
| **Bulleted list** | ⇧⌘8 |
| **Numbered list** | ⇧⌘7 |
| **Checklist** | ⇧⌘9 |
| **Quote**, **Code block**, **Table**, **Divider** | No keys |
In a table, right-click a cell for **Add row below**, **Add column after**, **Delete row** and **Delete column**. The **Add row** and **Add column** buttons also add rows and columns.
When an agent changes the pad while you type, Zero says **Changed elsewhere while you were typing.** Click **Keep mine** to save your version. Click **Take theirs** to load the agent's version.
## Hand a scratchpad to an agent
Every pad has a link, `zero://pad/`. Every heading in a pad has a link too. When a message has one of these links, the agent reads that pad, or that part of it.
- **The whole pad**: click **Copy link** beside the pad's title, or right-click the pad in the list. The arrow beside **Copy link** has **Copy Markdown link**. It also has a link for each heading, under **Link to a section**.
- **One section**: right-click in the pad's text and choose **Copy link to ""**. **Copy link to scratchpad** in the same menu copies the link for the whole pad.
- **From the composer**: in a task's composer, click **+** › **Scratchpad** and pick the pad. Zero puts its link in your message.
- **By dragging**: drag a pad from the list into a message.
Agents in Zero read, write, search and organise pads with Zero's scratchpad tools. They give you links to what they wrote. To keep one of an agent's messages as a pad, point at the message, click its **⋯** and choose **Save to a scratchpad**. The pad goes into the **Saved** folder, named after the first line of the message.
## Give an agent a loop
A loop is an instruction for an agent, kept under a name. For example, `@review` can hold how you like changes reviewed. When you type `@review` in a message, the agent gets the loop's words with the message. Your message still shows `@review`.
A loop can name other loops in its text, such as `@tests`. Zero doesn't add those loops' words: the names tell the agent which loops to start workers on. The lead follows `@review`, and its workers follow `@tests`.
### Make a loop
1. Click **Loops** on the rail. At the top of the list, click the compose button, **New loop**. When no loop is open, the page also has a **New loop** button.
2. Type a name and click **Create**. Zero writes the name in lower case, with hyphens for spaces.
3. Under the loop's name, write **What this loop is for, in a line**. This line shows in the list and when you type `@`.
4. Write the instruction below it, in Markdown. Zero saves as you type.
At the foot of a loop:
- **Names** lists the loops that it names. Click one to open it.
- **Ran by** lists the tasks that used it, as a lead or as a worker, with their state and the time. Click a task to open it. A new loop says **No session has run it yet.**
**Copy name** is beside the loop's name. It copies `@name`, ready to paste into a message. Right-click a loop in the list for **Copy name** and **Delete**.
Zero keeps each loop as a Markdown file in `~/.zero/loops`.
### Use a loop
- **In a message**: type @ in a task's composer. Zero suggests your loops first, each with what it's for. Pick one with ↑↓ and Tab or Return.
- **From an agent**: an agent lists your loops with `zero loops`, reads one with `zero loop `, and starts a worker on one with `zero spawn --loop `. See [The zero command](/docs/cli) and [Tasks and workers](/docs/tasks-and-workers).
---
# Following and integrations
Let agents watch pull requests and issues, and connect the services you use.
An agent can follow a pull request, an issue or a Slack thread. Zero reads it and tells the agent what changed, so the agent learns of a review or a reply without your help.
Integrations connect Zero to GitHub, Linear and Slack, so agents can follow things there. GitHub and Linear also show your pull requests and issues in Zero's window.
## What following does
Zero reads each thing that an agent follows about once a minute. It reads a Slack thread or channel every 30 seconds. When agents follow many things, Zero reads less often.
When something changes, Zero tells the agent between its turns. The message starts with the number of new events. When the agent's turn has ended, the message wakes the agent and it continues.
An agent can follow:
| What | What the agent hears of |
|---|---|
| A GitHub pull request | Reviews, comments, review threads resolved, checks failing and the overall result, pushes, conflicts, merges, and changes to its state, title, description, labels, assignees and reviewers. |
| A Linear issue | Changes to its status, assignee, priority, project, cycle, labels, estimate, due date, parent, title and description, and every comment. |
| One comment thread in a Linear issue | Only the comments in that thread. |
| A Slack thread | Replies, edits, deletions and reactions. |
| A Slack channel | New messages, and new replies in its recently active threads. |
Following needs a connected integration: see [Connect GitHub, Linear and Slack](#connect-github-linear-and-slack).
A task that's done and archived still follows its things. When one of them changes, the task comes back. When Zero fails to read something three times in a row, it tells the agent. It tells the agent again when reading works.
## How agents follow things
To make an agent follow something, give it the link. Agents start each follow themselves with the `zero` command, usually when they open a pull request or pick up an issue. Zero has no button to start a follow.
| Command | What it does |
|---|---|
| `zero follow ` | Follows a pull request, an issue, a Slack thread or channel, or a Linear comment thread. The link to a Linear comment thread ends in `#comment-…`. |
| `zero follow --mine` | For a busy channel. Delivers only messages that name a pull request that the task follows. |
| `zero follow --about "word,other words"` | Delivers only events that contain one of these words. |
| `zero following` | Lists what the task follows, and whether Zero can read each one. |
| `zero unfollow ` | Stops one follow. `--all` stops all of them. |
See [The zero command](/docs/cli) for every command.
## See and stop what agents follow
Open **Settings › Following**. To open Settings, press ⌘, or click the gear at the foot of the window's left rail.
The page groups the follows by **GitHub**, **Linear** and **Slack**. Until an agent follows something, the page shows **No agent follows anything yet.** Each row shows:
- The thing's title, such as the pull request's name.
- Below the title, the topic that Zero reads, such as `github/acme/app/42`. Next comes the filter, if the follow has one: **only your pull requests**, or **about** and the words. Last comes the time of Zero's last read.
- **Can't read it:** and the reason, in red, when Zero fails to read it.
- On the right, the name of the task that follows it. Click the name to open the task.
To stop a follow, point at its row and click **×**, **Unfollow**. Double-click a row to open the thing in your browser. Right-click a row for **Open**, **Copy topic** and **Unfollow**.
Each integration's page in **Integrations** also lists the follows that Zero reads through it, under **Following**.
## Open Integrations
Click **Integrations**, the puzzle piece near the foot of the window's left rail. The page lists **GitHub**, **Linear** and **Slack** on its left. Pick one to connect it, to see what agents follow through it, and to make its views.
## Connect GitHub, Linear and Slack
An integration that isn't connected says so at the top of its page, as **Connect GitHub**, **Connect Linear** or **Connect Slack**, with the steps below it.
**GitHub.** Zero uses the GitHub CLI and the account that the CLI is already signed in to.
1. If the GitHub CLI isn't installed, install it first:
```sh
brew install gh
```
2. In a terminal, run this command. In Zero, the copy button beside the command copies it.
```sh
gh auth login
```
3. Go back to Zero and click **Check again**.
The page then shows **Connected as** and your GitHub login. To disconnect, sign out of the GitHub CLI.
**Linear.** Click **Connect Linear**, then allow Zero on the Linear page that opens in your browser. Zero reads Linear and never writes to it. It keeps the connection on this Mac. To disconnect, click **Disconnect** on the page.
**Slack.** Zero reads channels, messages and names. It posts nothing. Each Slack workspace gets Zero's own Slack app:
1. Click **Create Zero's Slack app**. Slack opens with the app filled in.
2. In Slack, click **Create**, then **Install to Workspace**.
3. Copy the **User OAuth Token** that Slack shows.
4. Paste the token in the `xoxp-…` box in Zero and click **Connect**.
**Settings › Links › Slack › Connect Slack** goes through the same steps. To connect more than one Slack workspace, do the same steps for each one.
A Slack connection made before agents could follow Slack needs new scopes. Add the scopes from the app's manifest to your Slack app, reinstall the app and paste the new token.
The page then shows **Connected to** and the workspace's name. When one Slack workspace is connected, **Disconnect** is on the Integrations page. When more than one is connected, disconnect each one in **Settings › Links › Slack**.
## Keep your pull requests and issues in the rail
With GitHub or Linear connected, turn on **Show in the sidebar** on its page in Integrations. The integration then gets its own place in the window's left rail, under Loops. The switch is off by default.
Click the integration's icon in the rail. Its views show down the left, and the items of the open view show on the right. While the list is on screen, it refreshes every minute. The refresh button fetches it again at once.
- **GitHub** shows a table of pull requests: **#**, **Pull request**, **Repository**, **State**, **Checks** and **Author**. Click a row to open the pull request.
- **Linear** shows issues grouped by state, as Linear does. Click a state's heading to fold its issues away. Each row shows the priority, key, state, title, labels, assignee and when the issue was made. Click a row to open the issue. Right-click a row for **Open in Linear**, **Copy link**, and **Start task** or **Open task**.
Right-click an integration's icon in the rail for **Move up**, **Move down**, **Edit views** and **Hide from the sidebar**. To move an icon, hold ⌘ and drag it. **Edit views** at the foot of an integration's views opens its page in Integrations.
## Set up views
A view is a saved list of pull requests or issues. To make one, click **Add a view** under **Views** on GitHub's or Linear's page in **Integrations**.
To change a view, point at it and click the pen, **Edit**, or double-click the view. The **…** button beside the pen has **Move up**, **Move down** and **Delete**. The view's right-click menu has the same items, and **Edit**.
GitHub starts with **My pull requests** and **Review requests**. Linear starts with **My issues**: issues assigned to you that are in the backlog, to do or in progress.
A **GitHub view** has:
- **Name**.
- **Search**: a search in GitHub's own syntax, as on github.com. Click a chip under the box, such as `author:@me`, `review-requested:@me` or `org:`, to add it to the search. To show only the repositories of one organisation, add `org:` and the organisation's name.
A **Linear view** has:
- **Name**.
- **Assigned to**: **Me**, **Anyone** or **No one**.
- **Teams**: **Every team**, or the teams you pick.
- **States**: the states to show. When you pick none, the view shows every state.
## Start a task from an issue
A Linear view can start a task for any of its issues. In the view's form, turn on **Start a task from each issue** and fill in:
- **Folder**: where the task works. Type a path or click **Choose…**.
- **Agent**: **Claude**, **Codex** or **OpenCode**, with a model and an effort. To use the agent's default model, leave the model empty.
- **Prompt**: what Zero tells the task. Zero fills in `{key}`, `{title}` and `{url}` from the issue. The default is `Work on {key}: {title} ({url}).`
Then, in the view, point at an issue and click **Start**, or right-click the issue and choose **Start task**. The task gets the issue's key and title as its name.
The task also gets its own scratchpad, State, where it records where it stands. The prompt tells the task where that scratchpad is, unless you put `{state}` in the prompt yourself.
When an issue already has a task, the issue shows the task's state instead of **Start**. Click the state to open the task. For scratchpads, see [Later, scratchpads and loops](/docs/later-scratchpads-loops).
## Make references in messages open where you want
When an agent's message names a pull request, a commit, an issue or a Slack channel, Zero makes the name a link. Choose where those links go in **Settings › Links**:
| Setting | Where | What it does |
|---|---|---|
| Link pull requests and commits | Settings › Links › GitHub | `repo#123`, `#123` and commit hashes open on GitHub. On by default. |
| Link issues | Settings › Links › Linear | Issue keys such as `ABC-123` open the issue. On by default. |
| Open issues in the Linear app | Settings › Links › Linear | Opens issues in Linear's app, not in the browser. On by default. Greyed out when Linear's app isn't installed. The Linear page in Integrations has the same switch. |
| Slack | Settings › Links › Slack | The Slack workspaces that Zero is connected to. Their #channels and message links open in Slack. **Connect Slack** adds a workspace. **Disconnect** removes it. |
---
# Browsers and MCP servers
Let agents use your browser, and give them more tools.
Agents can use your own Chrome, signed in as you, and each task gets its own tabs. Agents can also use Firefox Developer Edition, and compare a page across Chrome, Firefox and Safari.
MCP servers give agents more tools. Add a server once in Zero, and every task gets it.
## Let agents use Chrome
Agents use Chrome through Zero for Chrome, an extension that you add to Chrome once.
1. Open **Settings › Browsers**. To open Settings, press ⌘, or click the gear at the foot of the window's left rail.
2. Under **Chrome**, click **Set up** on the **Zero for Chrome** row. Finder shows the extension's folder, and Chrome opens its Extensions page.
3. On Chrome's Extensions page, turn on **Developer mode**.
4. Click **Load unpacked** and pick the folder that Finder shows. Its path is also under the row in Settings.
Zero for Chrome connects by itself. The row then reads **Connected · each task works in tabs of its own**, and the button reads **Set up again**. Before that, the row reads **Not connected · set it up so agents can use Chrome**.
You set it up once. When a new version of Zero brings a newer extension, the extension reloads itself.
Each Chrome profile that has the extension connects as a separate browser.
## What you see while an agent uses Chrome
- **A tab group for each task.** A task's tabs open in a group in the Chrome window that you used last. They open in the background, so the tab you're looking at stays in front. The group's title is Zero and the task's name, after a symbol for the task's state: working, needs you, waiting on something else, or done.
- **A border and a pill on the page.** While a task uses a tab, the page has an orange border. A pill at the bottom shows which task uses the tab. To interrupt the task, click **Stop** on the pill.
- **A window of its own.** An agent with many tabs or a long run can ask for its own window, which opens behind yours. It can also ask for a private window, with none of your sign-ins. For a private window, turn on **Allow in Incognito** on Zero for Chrome's card, on Chrome's Extensions page.
Zero tells agents to close the tabs they opened when they're done.
## What agents can do in the browser
In a task's own tabs, an agent can:
- Open pages, and go back and forward.
- Read a page's elements and text, and take screenshots.
- Click, type, scroll, fill in forms and answer the page's alerts.
- Upload files to a page, up to 10 MB in all.
- Read the console and the page's requests.
- Lay the page out at a phone's or laptop's width.
- Run JavaScript in the page.
- Record a video of the tab while it works, to show you a bug or a feature.
An agent can act only on its own task's tabs and on tabs that you give it.
## Give an agent one of your tabs
1. In Chrome, open the page for the agent.
2. Click Zero in Chrome's toolbar. The popup shows **Connected**, and **Give this tab to a task** with the tasks open in Zero.
3. Click the task.
Zero tells the task that it can use the tab. To take the tab back, open the popup and click the task again, the one with a tick beside it. When the agent is done with a tab that you gave it, the agent gives the tab back and doesn't close it.
## Keep agents off some sites
Open **Settings › Browsers › Blocked sites**. Type a site in **Add a site (bank.com)** and press Return. Zero also blocks the site's subdomains.
Agents can't open a blocked site or act on a tab that shows one, in Chrome or in Firefox. When an agent compares a page across browsers, Safari's automation window refuses a blocked site too. In Safari, Zero checks the address that each step opens.
To unblock a site, point at it and click the bin, **Unblock it**.
When a task in **Auto** permissions first opens a site, Zero has the task's own agent check that the site fits the task. If the agent advises against the site, it can ask you to allow it. The ask, such as "Open example.com in Chrome", comes to your inbox like any other ask. See [The inbox and asks](/docs/inbox-and-asks).
## Use Firefox
To let agents use Firefox, install Firefox Developer Edition. Agents that ask for Firefox then use it, with your sign-ins. Zero opens it with remote control on and adds its own extension.
In **Settings › Browsers › Firefox**, the **Firefox Developer Edition** row shows **Connected** while Zero controls Firefox. **Open** opens it now.
## Compare a page across browsers
An agent that checks a change to a web page can run one step in Chrome, Firefox and Safari at the same time. It then sees the page in each browser, side by side. Chrome and Firefox are yours, and you're signed in. Safari is an automation window that's signed out of everything and keeps nothing.
To make sure that Safari's automation windows work, open **Settings › Browsers › Safari**. Then click **Try it** on the **Safari's automation windows** row. If Safari refuses remote control, turn on **Allow remote automation** in Safari's own settings, under **Developer**.
## Add an MCP server
An MCP server gives agents more tools, such as a lookup in a database that you use. When a task starts, Zero gives the servers you add to the task's agent: Claude Code, Codex or OpenCode. Servers already set up in the agent's own configuration keep working alongside them.
1. Open **Settings › MCP servers**.
2. Click **Add a server**. The **Add an MCP server** form opens.
3. Fill in the form and click **Save**.
| Field | What it's for |
|---|---|
| Name | The server's name, such as "CVE lookup". |
| **Runs a command** or **At a URL** | How the server runs: a command on your Mac, or a server at an address. A new server starts on **Runs a command**. |
| Command | For **Runs a command**: the program, such as `npx`, `uvx` or a path. |
| Arguments | For **Runs a command**: its arguments, separated by spaces. |
| URL | For **At a URL**: the server's address, such as `https://…/mcp`. A server that signs in with OAuth needs no headers. |
| Environment | For **Runs a command**: values that the server gets, each with a **NAME**. **Add** adds another value. |
| Headers | For **At a URL**: headers sent with each request, each with a **NAME**. |
| Workspaces | **Every workspace**, the default, or the workspaces whose tasks get the server. |
For each value in Environment or Headers, choose where Zero keeps it:
- **Keychain**, the default: in your Mac's Keychain. After you save, the box reads **Kept (type to change)**. To keep the value, leave the box empty.
- **Zero's file**: in Zero's own settings file on this Mac.
- **Its command**: Zero keeps nothing, and the server gets the value itself.
## Sign in to a server
Some servers at a URL sign in with OAuth. This applies to the servers you add in Zero and to the servers in Claude Code's or Codex's own configuration, such as one added with `claude mcp add`. You don't need to open the agent in a terminal to sign in.
When a task's agent says that a server needs a sign-in, Zero asks the agent's own CLI for the server's sign-in page:
- Your inbox shows **Sign in to ?**. Click **Open the sign-in page** and sign in, on this Mac. The ask goes away when the server is signed in. **Not now** closes the ask.
- Each task that wants the server shows the same link in its conversation. When the sign-in is done, the task shows **Signed in to **. A Claude Code task connects the server then. A Codex task connects it the next time it starts.
Zero asks once for each server, however many tasks want it. If you don't sign in within 15 minutes, Zero lets the sign-in go and doesn't ask again until Zero restarts. You can still sign in from Settings.
The agent's CLI keeps the sign-in, as it does when you sign in from a terminal. Zero never connects to the server itself. Zero tells agents that it has asked you, so they don't ask again.
**Settings › MCP servers** also lists **Claude Code's servers**, from Claude Code's configuration. You can't change them there. A server that needs a sign-in shows **Needs sign-in** and a **Sign in** button. Click **Sign in** to open its sign-in page in your browser. The row shows **Waiting for sign-in…** until the sign-in is done.
OpenCode signs in to a server only in a terminal, with `opencode mcp auth `.
## Choose which workspaces get a server
In the server's form, turn off **Every workspace**. Then tick the workspaces whose tasks get the server. The server's row in **Settings › MCP servers** shows **Every workspace**, or the names of its workspaces.
Or choose from the workspace: open **Settings › Workspaces**, point at a workspace and click the pen, **Edit**. Under **MCP servers**, tick the servers for its tasks. Servers for every workspace show as ticked, and you can't change them there. When you take a server out of its last workspace, Zero turns the server off rather than give it to every workspace. See [Workspaces and folders](/docs/workspaces-and-folders).
## Turn a server off, change it or delete it
In **Settings › MCP servers**:
- The switch on a server's row turns the server on or off. When it's on, Zero gives the server to tasks as they start.
- **Edit** opens the server's form. Change the form and click **Save**. To remove the server, click **Delete**.
A running task gets a change the next time it starts.
## Zero's own tools
Agents reach your inbox, your scratchpads and the browser through Zero's own MCP server. This server isn't in the list in **Settings › MCP servers**. To turn it on or off, use **Settings › Agents › Setup › Zero plugin**. When the switch is on, Zero installs its plugin in Claude Code and adds its server to Codex and OpenCode.
---
# Settings
Every setting in Zero: what it does, where it is and what it's set to by default.
Settings is part of Zero's window. Its left column lists the pages: **General** first, then three groups. **App** has Control bar, Composer and inbox, and Phone. **Agents** has Agents, Accounts, MCP servers and Browsers. **Work** has Workspaces, Folders, Git, Links and Following.
## Open Settings
- Press ⌘,.
- Click the gear at the foot of the window's left rail.
- Click Zero's icon in the menu bar and choose **Settings…**.
- Right-click the control bar and choose **Settings…**.
Settings opens on **General**. Each change takes effect at once, so the pages have no Save button.
## General
| Setting | Where | What it does |
|---|---|---|
| Zero and its version | Settings › General › Zero | Shows the version you have and whether it's up to date. **Check now** looks for an update. When an update is out, the row reads **Zero**, the new version's number and **is available**. Click **Update and restart** to install it. Zero quits and opens again as the new version. Running agents pause for a few seconds, then continue. Zero never updates without your click. |
| Icons | Settings › General › Zero | Which icons this copy of Zero draws. **Icons: Nucleo** in official builds. **Icons: Lucide** in a build from source, which differs in nothing else. |
| Launch Zero at login | Settings › General › Zero | Opens Zero when you log in to your Mac, so agents can always reach you. |
| Talk hotkey | Settings › General › Zero | The keys that open the inbox and start dictation, from any app. Click the button, then press a combination that includes ⌘, ⌥, ⌃ or ⇧. Esc cancels. Default: ⌥Space. |
| Needs you | Settings › General › Notifications | A notification when a task, one of its workers, or an agent outside Zero asks you something. On by default. |
| In trouble | Settings › General › Notifications | A notification when a task fails, gets stuck, runs out of usage, or is blocked. On by default. |
| Finished | Settings › General › Notifications | A notification when a task is done, replied, waiting, or over to you. On by default. |
| Sounds | Settings › General › Notifications | Plays a sound with each notification. While you're in Zero, you hear the sound and get no notification. On by default. Turning it off hides the Sounds section. |
| Needs you, In trouble, Over to you, Replied, Waiting, Done | Settings › General › Sounds | The sound for each task state. Pick one of the Mac's alert sounds, or **None**. You hear it as you pick it. Defaults: Blow for Needs you, Bottle for In trouble, Hero for the rest. The list marks each default with **(default)**. |
| Log | Settings › General › Advanced | **View log** opens the file where Zero records what it did and when. The row shows its path. |
| Onboarding | Settings › General › Advanced | **Open** shows the welcome screens again. |
[Tasks and workers](/docs/tasks-and-workers) explains the task states.
## Control bar
| Setting | Where | What it does |
|---|---|---|
| Follow the active screen | Settings › Control bar › Placement | On: the bar moves to the screen you're using. Off by default. |
| Bar in the window | Settings › Control bar › Placement | Puts the bar inside Zero's window instead of on the screen's edge: **When it fills the screen**, **Always** or **Never**. Default: **When it fills the screen**. |
| Agents in the bar | Settings › Control bar › Agents in the bar | The agents outside Zero that the bar shows. Point at one for the pen, **Rename**, and the bin, **Remove**. The bin is **Remove and stop** when Zero can stop the agent. Drag rows to change the order. A removed agent comes back the next time it asks you something. The list is empty until an agent first asks you something. |
[The control bar](/docs/control-bar) explains the bar itself.
## Composer and inbox
| Setting | Where | What it does |
|---|---|---|
| Suggest skills after / | Settings › Composer and inbox › Composer | Typing / in a message box lists Claude Code's commands and skills. On by default. |
| Suggest files after @ | Settings › Composer and inbox › Composer | Typing @ also lists files from the task's folder, after your loops. Off by default. |
| Take-back window | Settings › Composer and inbox › Inbox | How long you can press Esc to take an answer back after you give it: 0 to 5 seconds, in half seconds. Default: 2 seconds. |
| Move to the next ask | Settings › Composer and inbox › Inbox | After you answer, the inbox moves on to the next waiting ask 3 seconds later. On by default. |
| Ask expiry | Settings › Composer and inbox › Inbox | How long an ask waits before it expires, unless the agent sets its own time: 5 to 1,440 minutes, in steps of 5. Default: 60 minutes. |
| Microphone | Settings › Composer and inbox › Dictation | The microphone used when you dictate a reply. **System default** follows the Mac's input, and is the default. When the one you picked isn't connected, the row says so and Zero uses the system default. |
See [The inbox and asks](/docs/inbox-and-asks) for answering asks, and [Tasks and workers](/docs/tasks-and-workers) for the message box.
## Phone
| Setting | Where | What it does |
|---|---|---|
| Relay | Settings › Phone › Relay | The relay that passes messages between your phone and this Mac. The messages are encrypted, and the relay can't read them. Default: **Zero's relay**. To use your own, choose **Your own relay…**, type its `wss://` address and click **Use it**. **Change address…** changes it later. Phones paired before must pair again. The row shows the status under its name: **Off**, **Connecting…**, **Connected: your phones can reach this Mac**, **Can't reach it:** and the reason, or **It has closed:** and the relay's message. When the day's 2 GB through the relay are used, it says so. |
| Pair phone | Settings › Phone › Phones | Opens the steps to pair a phone and shows a QR code to scan with Zero on your phone. The code lasts five minutes. **New code** makes another. **Copy link** copies the same code as a link. |
| Each paired phone | Settings › Phone › Phones | The phone's name and when it was paired. **Remove** unpairs it. **None yet** until you pair one. |
The iPhone app, coming soon, calls this Mac **Your Mac** and unpairs with **Unpair this phone**. See [The iPhone app](/docs/iphone).
## Agents
| Setting | Where | What it does |
|---|---|---|
| Zero plugin | Settings › Agents › Setup | Lets your agents reach your inbox and use your scratchpads. On: Zero installs its plugin in Claude Code and adds its MCP server to Codex and OpenCode. Off: it takes them out again. When something goes wrong, the reason shows under the row. |
| Archive done tasks | Settings › Agents › Tasks | When Zero archives a done task: **Once you've read it**, **After an hour**, **After a day**, **After a week** or **Never**. Default: **After a day**. An archived task comes back when something it follows changes. |
| Agents' own subagents | Settings › Agents › Tasks | Off, the default: agents hand work to Zero workers, which you can see, steer and stop in Zero. On: Claude Code and Codex can also use their own subagents, which you can't see. The change takes effect the next time each task starts. |
| Where tasks run | Settings › Agents › Tasks | A command that prints, as JSON, the place where each piece of work runs: `[{"ticket": "…", "place": "…"}]`. Zero runs it in your login shell every five minutes. A task filed under one of those tickets shows that place as its Where, instead of its folder. Empty by default. Zero saves it when you press Return or leave the field. |
See [Tasks and workers](/docs/tasks-and-workers) for workers and archiving.
## Accounts
The page has a section for each agent, **Claude Code**, **Codex** and **OpenCode**, with the accounts it runs as and two buttons:
- **Add account**: sign in with Claude or ChatGPT in your browser, or add an API key. For OpenCode, pick the provider of the key: OpenCode Go, Anthropic, OpenAI or OpenRouter.
- **Add model**: add a model that the agent doesn't list yet, by its id and the name to show in the model picker.
Click an account to open it in place: how much it has used of each usage window, when each resets, and its activity by day. Its **⋯** menu has **Rename** and **Remove…**. Some Claude accounts also have **Switch to a token**. [Accounts and models](/docs/accounts-and-models) covers all of this in detail.
## MCP servers
Set up an MCP server here once, and Zero gives it to your tasks as they start, in every agent. **Add a server** opens the form. Each server's row has a switch and **Edit**. [Browsers and MCP servers](/docs/browsers-and-mcp) explains every field.
## Browsers
| Setting | Where | What it does |
|---|---|---|
| Zero for Chrome | Settings › Browsers › Chrome | Lets agents use Chrome, each task in tabs of its own. **Set up** installs the extension's files, shows them in Finder and opens Chrome's Extensions page. The row shows whether it's connected. |
| Firefox Developer Edition | Settings › Browsers › Firefox | Zero opens it under remote control when an agent asks for Firefox. **Open** opens it now. Shows **Connected** while it's under Zero's control. |
| Safari's automation windows | Settings › Browsers › Safari | A signed-out Safari window, for comparing how a page looks in each browser. **Try it** checks that it works. |
| Blocked sites | Settings › Browsers › Blocked sites | Sites that no task can use. Type one in **Add a site (bank.com)** and press Return. To take a site off, point at it and click the bin, **Unblock it**. Empty by default. |
[Browsers and MCP servers](/docs/browsers-and-mcp) explains each browser and how agents use it.
## Workspaces
Each row has a workspace's icon and name. **Shown** marks the one the window shows. Point at a row for the pen, **Edit**, and the bin, **Delete: its tasks are Zero's again**. The **Zero** workspace is always there: it can't be deleted or renamed.
**Add workspace** opens **New workspace**: a **Name** and an **Icon**. Editing a workspace also lists the **MCP servers** its tasks get. See [Workspaces and folders](/docs/workspaces-and-folders).
## Folders
| Setting | Where | What it does |
|---|---|---|
| Projects | Settings › Folders › Projects | The folders tasks start in. **Add folder** adds one or more. Click a folder for **Rename…**, **Show in Finder** and **Remove**. **Rename…** changes the name Zero shows for it. Empty by default. |
| Drop folders | Settings › Folders › Drop folders | Folders where agents on other machines leave their asks as files, synced to this Mac. **Add drop folder** takes a pattern such as `~/projects/*/.zero`, typed or picked with **Choose…**. Click one to **Remove** it. Empty by default. |
See [Workspaces and folders](/docs/workspaces-and-folders).
## Git
These settings change how agents commit: only the agents' Git, not your own terminal's.
| Setting | Where | What it does |
|---|---|---|
| Sign with the agents' own key | Settings › Git › Agents' commits | On: the account below commits and signs the agents' commits, and you stay the author. Off by default. |
| Account | Settings › Git › Agents' commits | The GitHub account that commits and signs. **Choose…** asks for its GitHub login. Zero uses the account's name and noreply email. The row then shows the login, name and email, and the button reads **Change…**. |
| Signing key | Settings › Git › Agents' commits | The private key agents sign with. It must have no passphrase. **Choose…** picks the file. **Replace…** picks another. A pill shows **On** and the login when the key is one of the account's signing keys on GitHub, so commits show as Verified. It shows **Not on** and the login when you still need to add it there. |
| Push over HTTPS | Settings › Git › Agents' commits | Agents push to GitHub with the GitHub CLI's sign-in instead of SSH, so a push doesn't wait on your own key. On by default. |
| Folders | Settings › Git › Folders | Keeps the agents' Git identity to these folders. An empty list means **Every folder**, the default. **Add folder** adds one. **Remove** takes it off. |
## Links
These settings decide what opens when you click a reference in a message.
| Setting | Where | What it does |
|---|---|---|
| Link pull requests and commits | Settings › Links › GitHub | `repo#123`, `#123` and commit hashes in messages open on GitHub. On by default. |
| Link issues | Settings › Links › Linear | Issue keys such as `ABC-123` in messages open the issue. On by default. |
| Open issues in the Linear app | Settings › Links › Linear | Opens issues in Linear's app instead of the browser. On by default. Turned off and greyed out when Linear's app isn't installed or **Link issues** is off. |
| Slack | Settings › Links › Slack | The Slack workspaces Zero is connected to. Their channels and message links open in Slack. **Connect Slack** adds one. **Disconnect** removes it. **No workspace connected** until you add one. |
[Following and integrations](/docs/following-and-integrations) explains connecting Slack.
## Following
Everything your agents follow, grouped by GitHub, Linear and Slack. To stop following one, point at its row and click **×**, **Unfollow**. Click the task's name to open the task. [Following and integrations](/docs/following-and-integrations) explains the rows.
## Remembered without a setting
Zero also remembers these as you use it:
- How wide you dragged the sidebars. One width counts for all of them.
- The agent and project you last picked for a new task.
- How the tasks sidebar is sorted, the order you dragged tasks into, and which tasks have their workers folded.
- The workspace the window shows, and whether a task's details pane is open.
- The order of the integrations in the rail, and which states are folded in each Linear view.
- Your unsent drafts, and where you scrolled to in each conversation.
- The names you gave agents and their order in the control bar.
---
# Keyboard shortcuts
Every key Zero answers to: in the window, the inbox, the control bar and the composer.
Some keys, such as the number keys in the inbox, work only when you aren't typing in a box.
## From any app
| Keys | What it does |
|---|---|
| ⌥Space | The **Talk hotkey**. Opens the inbox panel on the oldest waiting ask and starts dictation. Press it again to stop dictation. |
To change the Talk hotkey:
1. Open **Settings › General › Zero › Talk hotkey**. To open Settings, press ⌘, or click the gear at the foot of the window's left rail.
2. Click the button. While it waits for keys, the button reads **Press keys…**.
3. Press the new keys. They must include at least one of ⌘, ⌥, ⌃ or ⇧. Esc cancels.
The new keys work at once. You can't change any other key in Zero.
## In the menu bar icon's menu
Click Zero's icon in the menu bar. These keys work while its menu is open.
| Keys | Item | What it does |
|---|---|---|
| ⌘0 | **Show Zero** | Opens Zero's window. |
| ⌘, | **Settings…** | Opens Settings in Zero's window. |
| ⌘Q | **Quit Zero** | Quits Zero. |
## In the inbox panel
The inbox panel opens beside the control bar, on the right edge of your screen. These keys work while the panel has the keyboard focus. The panel gets the focus when you click the bar or press the Talk hotkey. See [The inbox and asks](/docs/inbox-and-asks).
| Keys | What it does |
|---|---|
| ↑↓ | Selects the card above or below. |
| 123 | Picks the first, second or third answer on the selected card. To pick a later answer, click it. |
| Return | Puts the cursor in the selected card's reply box, or in the agent's message box. |
| Any letter | Starts to type that letter into the selected card's reply box, or into the agent's message box. |
| Return, in a reply box | Sends your reply. |
| ⌘V, in a reply box | Pastes. A pasted image goes in as its file path. |
| Space | Starts or stops dictation. |
| Delete | Removes the selected card from the panel, once you've answered it. |
| Esc | Steps back one thing at a time, in the order below. |
Each Esc does the first of these that applies:
1. Closes the suggestions list in the message box.
2. Closes an open model or project list.
3. Closes the agent's screen in the panel.
4. Stops dictation.
5. Closes the open text box of an answer.
6. Takes back the answer you picked last, while its row is still orange: 2 seconds by default. To change the time, go to **Settings › Composer and inbox › Inbox › Take-back window**.
7. Leaves the box you're typing in.
8. Leaves the agent's view and goes back to the inbox.
9. Hides the panel.
An agent's screen, such as a command's picker, can open in the panel. While it's open, the arrows, Return, Delete and letters go to that screen.
## In Zero's window
| Keys | What it does |
|---|---|
| ⌘N | Opens **New task**. |
| ⌘1 to ⌘9 | Opens the first nine tasks, in the order of the sidebar. |
| ⌘, | Opens Settings. |
| ⌘[ | Goes back. |
| ⌘] | Goes forward. |
| Mouse side buttons, or a swipe | Go back and forward, as in a browser. |
| ⌘W | Closes the window. Zero stays in the menu bar and your agents keep running. |
| ⌘Q | Quits Zero. Your agents keep running. |
| ⌘Z | Undo. |
| ⇧⌘Z | Redo. |
| ⌘X, ⌘C, ⌘V, ⌘A | Cut, copy, paste, select all. |
| ⌘ and drag | Moves an integration's icon up or down the left rail. |
In dialogs, Return presses the main button. Esc presses **Cancel**. When you rename something, Return saves and Esc cancels.
## In a task's composer
The composer is the box at the foot of a task's conversation. See [Tasks and workers](/docs/tasks-and-workers).
| Keys | What it does |
|---|---|
| Return | Sends your message. While the agent works, the message waits in a queue until the agent's turn ends. |
| ⌘Return | Sends now. While the agent works, the message goes in at once and steers the agent. |
| ⇧Return or ⌥Return | Starts a new line. |
| ⌘. | Stops the agent's turn. |
| ⌘V | Pastes. A pasted image or video goes with the message. |
| 1 to 9, with the composer empty | Picks that answer on the first ask that the agent sent you through Zero. |
| Any letter, with nothing else to type in | Starts to type that letter into the composer, wherever the window's focus is. ⌘V pastes into the composer the same way. |
| Esc | Closes the **+** menu. |
When you type `/` or `@`, a list of suggestions opens:
| Keys | What it does |
|---|---|
| ↑↓ | Moves through the suggestions. |
| Tab or Return | Takes the highlighted suggestion. |
| Esc | Closes the list. |
## In a task's conversation
| Keys | What it does |
|---|---|
| EscEsc, within half a second | Opens the rewind list of your messages. |
| ↑↓, in the rewind list | Moves through your messages. |
| Return, in the rewind list | Picks the message to rewind to. |
| Esc, in the rewind list | Closes the list. On the rewind card, Esc is **Never mind**. |
| Return, on a permission request docked above the composer | Picks the first answer of the request. This works only when you aren't typing in the composer. |
| Esc | Closes the task's details card after you click into it. |
The image viewer opens when you click an image. In the viewer:
| Keys | What it does |
|---|---|
| ← or ↑ | Shows the previous image. |
| → or ↓ | Shows the next image. |
| Esc | Closes the viewer. |
## In a model or project list
These lists open from the chips in the composer, such as the model chip.
| Keys | What it does |
|---|---|
| ↑↓ | Moves through the list. |
| ←→ | Switches between the provider tabs in the model list. |
| Return | Picks the highlighted row. |
| Esc | Closes the list. A second click on its chip also closes it. |
## In a menu
Zero's menus, such as a task's right-click menu, take these keys:
| Keys | What it does |
|---|---|
| ↑↓ | Moves through the menu. |
| Return | Picks the highlighted item. |
| Esc | Closes the menu. |
An item with an arrow, such as **Change status**, has its own menu. Point at the item to open it beside the menu.
## In a scratchpad
| Keys | What it does |
|---|---|
| ⌘B | Bold. |
| ⌘I | Italic. |
| ⌘E | Code. |
| ⌘K | Link. |
| ⇧⌘X | Strikethrough. |
| ⌥⌘1, 2 or 3 | Heading 1, 2 or 3. |
| ⇧⌘7 | Numbered list. |
| ⇧⌘8 | Bulleted list. |
| ⇧⌘9 | Checklist. |
See [Later, scratchpads and loops](/docs/later-scratchpads-loops).
## In a terminal
In a task's terminal, all keys go to the terminal except these:
| Keys | What it does |
|---|---|
| ⌘C | Copies the selection. |
| ⌘V | Pastes. |
| ⌘A | Selects all. |
---
# The iPhone app
Answer your agents and follow your tasks from your phone, while they run on your Mac.
The iPhone app, coming soon, puts Zero's inbox and tasks on your phone. You answer asks, write to your tasks, start new tasks and save work for later. Your agents keep running on your Mac, so Zero must be open there and the Mac must be online.
## How your phone reaches your Mac
Your phone reaches your Mac through a relay: a server on the internet that passes messages between the two. Zero's own relay works out of the box, with nothing to set up.
To run your own relay, deploy `apps/relay` from Zero's source code. Its README shows how. Then, on your Mac:
1. Go to **Settings › Phone › Relay**.
2. Click the **Relay** chip and choose **Your own relay…**.
3. Type the relay's `wss://` address and click **Use it**.
Phones you paired before must pair again. To go back, choose **Zero's relay** in the same chip.
Open Settings with ⌘, or the gear at the foot of the window's left rail. The **Relay** row shows the state of the connection under its name:
| Status | What it means |
|---|---|
| Off: no relay set | There's no relay address. |
| Off | There's an address, but Zero isn't connected to it. |
| Connecting… | Zero is connecting to the relay. |
| Connected: your phones can reach this Mac | The relay works. |
| Can't reach it: … | Zero couldn't connect. The reason follows. |
| Today's 2 GB through the relay are used: … | Your phones and this Mac passed more through the relay today than it allows. Your phones reach the Mac again after midnight UTC. To have no limit, run your own relay. |
| It has closed: … | The relay no longer runs. The message says what to do instead, such as where to run your own. Zero stops connecting to it. |
## Pair your iPhone
You pair once. After that, the phone finds your Mac by itself.
1. On your iPhone, open Zero. It shows the **Pair with your Mac** screen.
2. On your Mac, go to **Settings › Phone** and click **Pair phone**, beside the **Phones** heading.
3. Click **Next**. The Mac shows a QR code.
4. On the phone, tap **Scan the code** and point the camera at the QR code.
The code lasts five minutes, and the Mac counts down the time left. When it expires, click **New code**. **Copy link** copies the same code as a link, for a phone that can't scan it. Copy the link to your phone and tap **Paste a pairing link**. A wrong link shows **That isn't a Zero pairing link.**
When the phone has paired, the Mac says so with the phone's name. Click **Done**. The phone then shows in **Settings › Phone › Phones**, with the date you paired it.
## How your messages stay private
Messages between your phone and your Mac are encrypted end to end. The relay passes them on but can't read them. When you pair, the phone gets your Mac's key from the QR code, and the Mac keeps the phone's key. Each side uses these keys to check that it's talking to the other.
Notifications are encrypted too. Your Mac sends each one through the relay to Apple's push service. Both carry only "Zero: A task has news". When the notification arrives, your phone decrypts the real text.
A relay of your own sends notifications only when it has an Apple push key. Its README shows how to add one.
## When the phone can't reach your Mac
While the phone connects, it shows **Connecting to** and your Mac's name. When it can't connect, it shows **Can't reach**, your Mac's name and when it last connected. It also says that Zero must be open on your Mac and the Mac must be online. The phone keeps trying by itself. To try at once, tap **Try again**.
While the phone isn't connected, a line at the top of the app says **Reconnecting to your Mac** or **Can't reach your Mac**. What the app already loaded stays on screen. To reconnect, pull down on a list.
## Get around the app
The bar at the foot of the screen has three icons and a menu:
- **Inbox**: asks, steps for you and unread replies. A blue dot means something is waiting.
- **Tasks**: all your tasks.
- **Later**: work saved for later.
- **⌃⌄** opens the menu. It shows your workspace's name at the top, then **Inbox**, **Tasks**, **Later**, **Record your screen** and **Settings**. **Inbox** shows the number of things waiting.
When you have more than one workspace, tap the workspace's name in the menu to switch. The phone keeps its own choice of workspace, separate from the Mac's.
The round **+** button beside the bar starts a new task.
## Answer asks in the inbox
The inbox lists what needs you, in this order:
1. Asks from your agents, which you answer in place.
2. Tasks marked **Over to you**: they're done, and a step is left for you.
3. Tasks with a reply you haven't read.
When the inbox is empty, it says **Nothing for you**.
Each ask shows under its task's name, with how long ago it came. Long details show three lines: tap them to read all of it. The option the agent recommends has a blue **Recommended** tag.
To answer an ask, tap one of its options. An option ending in "…" opens a box for your own words. An ask without options has **Reply…**.
To change your answer, tap **Take back** right after you answer. When an answer doesn't arrive, the card says **Not delivered · Try again**. Tap it to send the answer again.
The inbox has these cards:
| Card | What it asks |
|---|---|
| Question | A question, or a choice between options. |
| Run on your Mac | "Allow this command?": the agent wants a command run on your Mac. Its output goes back to the agent. |
| Run this yourself | A command for you to run. **Copy the command** copies it, and **Paste its output** sends what it printed back. |
| Approval | The agent wants your go-ahead before it does something. |
| Permission | An agent asks to use a tool, such as to run a command or change a file. |
See [The inbox and asks](/docs/inbox-and-asks) for every kind of ask.
## Browse your tasks
**Tasks** lists the tasks in your workspace, in the same order as the Mac's sidebar. Each row shows the agent, the task's state, its name, what it needs or does, and how long ago. A blue dot means a reply you haven't read.
The states are the same as on the Mac: **Needs you**, **In trouble**, **Working**, **Over to you**, **Waiting**, **Replied**, **Done**, **Paused**, **Idle** and **Offline**.
- **Swipe left** for **Archive** and **Pause**. On a paused task, **Pause** is **Resume**.
- **Swipe right** for **Rename**.
- **Touch and hold** for a preview and the menu. The preview shows the task's state, what it does now, what it needs from you and its asks. The menu has **Pause** or **Resume**, **Rename**, **Save for later** and **Archive**.
**Archive** asks you to confirm first. It puts the task away with all its workers. To bring an archived task back, use **Archived tasks** on your Mac.
## Read and write to a task
Tap a task to open its conversation. It shows your messages, the agent's answers, and its work folded under lines such as **Worked for …**. Tap a command to see its output. Scroll up for **Earlier messages**.
### Answer what the task is waiting on
The task's questions, approvals and asks are in its own inbox, not in the conversation. Tap the inbox button at the top right, beside the **…** menu. A blue dot on it means something is waiting.
The button opens a sheet titled **Waiting on you**, where you answer each ask. An approval from the agent itself reads **Allow this command?** or **Allow this change?**, with the agent's own choices as buttons. When nothing is left, the sheet closes by itself. To close it before that, tap **Done**. Opened with nothing waiting, it says **Nothing waiting on you**.
In the conversation, a step with an ask that is still open shows as one line with **Answer**. Tap **Answer** to open the same sheet.
Opening a task marks its reply as read on the phone and on the Mac, and clears its notification.
The **…** menu at the top right has:
- **Details**: the task's **State**, **Workers**, **Where**, **Branch**, **Ticket**, **Agent**, **Model** and **Permissions**, and any **Attributes** its agent set. Tap a link in an attribute to open it.
- **Save for later**: asks the agent to write down what's left, in Later.
Write to the task in the box at the foot, **Write to this task**. When you leave the task, Zero keeps your draft.
| Control | What it does |
|---|---|
| **+** | Adds up to 10 photos. |
| Microphone | Dictates into the box. |
| **Permissions: auto** | Switches between **Auto** and **Unrestricted** for the task. |
| The model, such as **Opus 5.5 High** | Picks the model and effort, from this agent's models, for your next message. |
| Send | Sends. While the task works, it's **Queue for after this turn**. |
| Stop | Shows while the task works and the box is empty. Stops the turn. |
Messages that wait for the end of the turn show above the box under **Queued**. Tap one to edit or delete it, or tap **Steer** to send it now. After you stop the task, these messages show as **Held**. Tap **Send** to send them.
## Start a task
Tap the round **+** button.
1. At the top, tap the folder to pick where the task works. The list has your Mac's project folders. Zero remembers the last one you used.
2. Type the job in **What should it do?**.
3. Tap the agent chip to pick **Claude Code**, **Codex** or **OpenCode** and its model. Claude Code is the default.
4. Tap the permissions chip for **Auto** or **Unrestricted**. **Auto** is the default.
5. Tap **Start**.
The task starts in the workspace your phone shows, and opens.
## Come back to saved work
**Later** holds work that your agents saved for you. **Open** and **Done** at the top switch between what's left and what you finished. Notes an agent saved without you asking show under **Suggested**.
Swipe a note to mark it **Done** or **Not done**. Tap it to read all of it, with its links and the agent's write-up. From there:
- **Send to a task** sends the note to one of your tasks, and that task's agent takes on the work.
- **Done** or **Not done** marks it.
- **Copy** copies it.
To save a task's work, choose **Save for later** from the task's menu.
## Record your screen
To show an agent something on your phone, open the menu and choose **Record your screen**.
- Tap the red button to start a screen recording. To speak while you record, turn on the microphone in the system's sheet. To stop, tap the same button or the red pill at the top of the screen.
- Or pick what you already have: up to 10 **Photos**, or **Recordings**.
Then add a line in **What should it look at?**, choose the task under **Send to**, and tap **Send**. The agent gets the recording as pictures, each with its time, and the words you said.
## Check the phone's settings
Open the menu and choose **Settings**.
| Row | Group | What it shows |
|---|---|---|
| Connection | Your Mac | **Connected**, **Connecting…**, **Can't reach it** or **Not paired**. **Reconnect** shows when the phone isn't connected. |
| Notifications | Permissions | Whether Zero can send notifications. |
| Microphone, Speech | Permissions | Whether Zero can use them, for dictation and recordings. |
| Open iOS Settings | Permissions | Opens Zero's page in the iPhone's Settings app, to change these. |
| Version | About | The app's version. |
| Unpair this phone | About | Unpairs the phone. |
## Get notifications on your phone
The first time you open **Tasks**, Zero asks to send notifications.
Your phone gets a notification when a task has news and you're away from your Mac. Zero counts you as away when one of these is true:
- Zero isn't in front on the Mac with its window open.
- The Mac's screen is locked or asleep.
- You haven't touched the keyboard or mouse for two minutes.
- You used the phone more recently than the Mac.
How notifications behave:
- Each task has one notification at a time. News replaces the old one.
- After you see the news on the Mac or the phone, the notification goes away on both.
- Tap an ask's notification to open the inbox. Tap a task's notification to open the task.
- Press and hold a task's notification for **Reply**. Type in **Reply to this task** and tap **Send**. While the task works, your reply waits until its turn ends.
- While you're in the app, notifications play their sound but don't show a banner.
## Send pictures and videos from other apps
Zero is in the iPhone's share sheet twice: as **Zero** among the apps, and as **Ask Zero** among the actions. Both do the same thing.
1. In Photos or another app, select up to 10 pictures or one video and tap **Share**.
2. Choose **Zero** or **Ask Zero**.
3. Write the agent's job in **What should it look at?**. When the box is empty, Zero sends "Have a look at this." For several pictures, it sends "Have a look at these."
4. Pick a task under **Send to a task**, or a folder under **Or start one in** to start a new Claude Code task there.
5. Tap **Send**.
A video goes as pictures taken from it. When the phone can't reach Zero on your Mac, it shows **Can't reach your Mac: Zero needs to be running there.**
## Use Siri and Shortcuts
Each action works through Siri and in the Shortcuts app. In the phrases below, Login fix stands for your task's name.
| Action | Say | What happens |
|---|---|---|
| What needs me | "What needs me in Zero", "What's waiting for me in Zero" or "Anything need me in Zero" | Siri reads out the tasks and asks that wait for you, or "Nothing needs you right now." |
| Check a task | "How is Login fix doing in Zero", "What's Login fix doing in Zero" or "Check on Login fix in Zero" | Siri says the task's state and what it does now. |
| Open a task | "Open Login fix in Zero" | Opens the task. |
| Save for later | "Save Login fix for later in Zero" | Asks the task's agent to save its work to Later. |
| Pause agents | "Pause my agents in Zero" or "Pause Zero" | After you confirm, every task and its workers finish their current step and stop. |
| Resume agents | "Resume my agents in Zero" or "Unpause Zero" | Takes your tasks off hold. Tasks with messages waiting continue. |
Ask Siri to send a message to a task by its name, or reply to a task's notification with Siri. Siri answers "Sent to" and the task's name.
When the phone can't reach Zero on your Mac, Siri says **Zero can't reach your Mac. Zero needs to be open there.**
## Unpair your iPhone
On the phone, open the menu, choose **Settings**, tap **Unpair this phone**, then **Unpair**. To unpair from the connecting screen, tap **Paired with** and your Mac's name at the foot, then **Unpair this phone**.
After that, the phone can't reach your Mac until you pair it again. Unpairing on the phone leaves it in the Mac's list.
To cut a phone off from the Mac's side, for example after you lose it, go to **Settings › Phone › Phones** on the Mac and click **Remove** next to the phone.
---
# The zero command
How agents reach you: the zero command and the Claude Code plugin.
`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](#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`:
```sh
export PATH="$HOME/.local/bin:$PATH"
```
To make the link yourself:
```sh
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 ` | `--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 ]` | **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 "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 ...` | `--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 ` | | Prints the task's last answer. |
| `zero workers` | `--session` | Lists the task's workers. |
| `zero adopt ` | `--session` | Makes another task, or a Claude Code session, a worker of this one. |
| `zero detach ` | | Lets a worker go: it becomes a task of its own. |
| `zero close ...` | | Archives a worker the lead has read. It leaves the sidebar. |
| `zero migrate ` | `--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 ` | | 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 ...` | `--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 ...` | `--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 "text"` | `--session` | The same as `zero schedule`, in minutes. |
| `zero notify "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 ` | `--version N` | Prints an item in full. |
| `zero later edit ` | `--note`, `--file`, `--link`, `--attach` | Changes an item. |
| `zero later done `, `open `, `delete ` | | Marks an item done or open again, or deletes it. |
| `zero browser ['{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](/docs/browsers-and-mcp). |
| `zero video ` | `--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 ` | | Prints an ask's state and answer. |
| `zero wait ` | | Waits for an ask's answer. If Zero restarts while it waits, it keeps waiting for up to 10 minutes. |
| `zero say "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](/docs/control-bar).
---
# Troubleshooting
What to check when Zero, an agent, the control bar or the iPhone app doesn't work.
When no section helps, [the logs](#read-the-logs) show what Zero and your agents did.
## An agent isn't found
You see one of these:
- The welcome's **Your agents** step says **Not installed** beside Claude Code or Codex.
- A task fails as soon as it starts.
Zero doesn't include the agents. It starts each one with zsh as a login shell, as a new Terminal window does, so it looks only where your shell looks. To see what Zero sees, open Terminal and run:
```sh
zsh -lic 'command -v claude codex opencode'
```
Each installed agent prints its path. For each agent that prints nothing:
1. Install the agent, or find where it's installed.
2. Add its folder to the PATH in `~/.zprofile` or `~/.zshrc`. Do this even when you use another shell every day. Zero always uses zsh.
3. Run the command again until the path prints.
New tasks get the change without a restart of Zero. The welcome checks only once, when it opens. To check again there, open **Settings › General › Advanced › Onboarding** and click **Open**.
A task's own errors, such as `command not found`, are in its `stderr.log`. See [Read the logs](#read-the-logs).
## Signing in doesn't work
Accounts are in **Settings › Accounts**. To open Settings, press ⌘, or click the gear at the foot of the window's left rail.
| What you see | What to do |
|---|---|
| **Sign in with Claude** stays on **Finish signing in on Claude's page in your browser.** | Finish signing in on the page that opened in your browser. If Claude shows a code there, paste it into **Its code, if Claude shows one** and click **Send**. |
| "Couldn't start Claude Code's sign-in." | Zero couldn't run Claude Code. Make sure that Zero finds it. See [An agent isn't found](#an-agent-isnt-found). |
| "Claude Code's sign-in ended without a token. Try again." | Click **Try again** and finish signing in. Zero waits ten minutes for a sign-in. |
| A ChatGPT account stays on **Signing in… finish in your browser**, then goes away | The sign-in was refused, or it didn't finish within 15 minutes. Click **Add account** › **Sign in with ChatGPT** again. |
| A task says an account "isn't in the Keychain any more: sign in again" | The account's token or key is no longer in your Keychain. Click the account's **⋯**, choose **Remove…**, then click **Remove** in its row. Then add the account again. |
| A task fails with a sign-in error, and Zero has no accounts for that agent | Without accounts in Zero, tasks use the agent's own sign-in. Sign the agent in again in Terminal, or add an account in **Settings › Accounts**. |
See [Accounts and models](/docs/accounts-and-models).
## A task stops at a usage limit
When an account reaches its usage limit, Zero moves the task to another account of the same agent that isn't at a limit. The task then continues by itself.
When no other account can take over, the task shows **Usage limit** at the end of its conversation, with the time when the limit resets. Choose one:
- **Wait.** When Zero knows the reset time, the task continues by itself after the limit resets.
- **Hand it to another agent.** Click **Continue with Codex** or **Continue with Claude Code** in the same place. The other agent takes over the task and its conversation.
- **Add an account.** Add another account for the agent in **Settings › Accounts**. New tasks use it.
To see how close an account is to its limits, click its row in **Settings › Accounts**. The row opens in place with **Last 5 hours** and **This week**: how much of each is used, and when it resets. A bar turns orange at 90% and red at 100%. An account at its limit says **At its limit** in red on its row.
When a task says your account "can't use" a model, Zero moves the task to an account that can, if you have one. Otherwise, pick another model in the task's composer.
## You can't see the control bar
The control bar is on the right edge of one screen, halfway down. It shows in every Space, including over apps in full screen.
- **Is Zero running?** Look for Zero's icon in the menu bar. If the icon isn't there, open Zero from your Applications folder.
- **More than one screen?** The bar stays on the screen where it showed first. To move it to the screen you're using, turn on **Settings › Control bar › Placement › Follow the active screen**.
See [The control bar](/docs/control-bar).
## Asks don't reach you
Agents reach you with the `zero` command. Do these checks in order.
**Zero is running.** An agent's `zero` command can say "Zero.app is not running" or "Zero's daemon isn't running". In that case, open Zero. Turn on **Settings › General › Zero › Launch Zero at login**, so agents can always reach you.
**The agent can find the `zero` command.** Agents use `~/.local/bin/zero`, which points at the copy inside Zero.app. Zero puts it there when it updates. To check it, run this in Terminal:
```sh
ls -l ~/.local/bin/zero
```
If the file is missing, make it:
```sh
mkdir -p ~/.local/bin && ln -sf /Applications/Zero.app/Contents/MacOS/zero-cli ~/.local/bin/zero
```
**Claude Code has the Zero plugin.** The plugin teaches Claude Code to ask you in Zero. Turn on **Settings › Agents › Setup › Zero plugin**. When Zero can't install the plugin, the reason shows under the switch. The same switch adds Zero's tools to Codex's and OpenCode's configuration.
**The ask hasn't expired.** An ask without its own expiry expires after 60 minutes and leaves **Waiting on you**. To give asks more time, change **Settings › Composer and inbox › Inbox › Ask expiry**. Answered asks are under **Answered** on the **Inbox** page, the tray in the window's left rail.
**The agent is on another machine.** Agents on other machines leave their asks as files in a folder that Zero watches. To add that folder, go to **Settings › Folders › Drop folders** and click **Add drop folder**.
**No notifications.** When asks reach the inbox but no notifications come, check that Zero may send them in macOS's **System Settings › Notifications**. Then check that the kinds you want are on in **Settings › General › Notifications**.
## Your iPhone doesn't connect
The iPhone app, coming soon, reaches your Mac through a relay. The relay is a server that passes your phone's encrypted messages without being able to read them. Notifications on your iPhone come through the relay too.
On the Mac, open **Settings › Phone**. The **Relay** row shows which relay Zero uses on its right: **Zero's relay** by default. Under the word **Relay**, the row says how the connection is:
| The **Relay** row reads | What it means |
|---|---|
| **Connecting…** | Zero is connecting to the relay. |
| **Connected: your phones can reach this Mac** | The Mac side works. |
| **Can't reach it:** and a reason | Make sure that the relay's address is correct and that the Mac is online. |
| **Today's 2 GB through the relay are used** | Your phones reach this Mac again after 00:00 UTC. To have no limit, run your own relay from `apps/relay`. |
| **It has closed:** and a message | The relay no longer runs. Follow the message, such as running your own relay from `apps/relay`. |
To use your own relay, click the relay's name on the **Relay** row and choose **Your own relay…**. Type its address, which starts with `wss://`, and click **Use it**. Phones paired before then must pair again with a new code.
To pair a phone, click **Pair phone** under **Phones**. On the **Scan the code** step, the code expires after five minutes. Click **New code** to get another. For a phone without a camera, **Copy link** copies the same code as a link.
On the iPhone, **Can't reach** and your Mac's name means that the phone can't get through. Zero must be open on your Mac, and the Mac must be online. Tap **Try again**. The iPhone's own Settings page shows the same status under **Your Mac › Connection**, with **Reconnect**.
To start again, remove the phone on the Mac: in **Settings › Phone › Phones**, click **Remove**. Or tap **Unpair this phone** in the iPhone's Settings, then **Unpair**. Then pair again.
Zero logs each phone that connects or is refused in `~/.zero/zero.log`. These lines start with `phone:` and `phones:`. Lines about notifications sent to your iPhone start with `push:`.
## Read the logs
Zero keeps its logs in the `.zero` folder in your home folder. To open this folder in Finder, press ⇧⌘G and type `~/.zero`.
| File | What it holds | How to open it |
|---|---|---|
| `~/.zero/zero.log` | What the app did and when: phone connections, notification permission, and problems it found. The previous log is beside it as `zero.log.1`. | **Settings › General › Advanced › Log › View log** |
| `~/.zero/zerod.log` | Messages from Zero's background service, which runs your tasks. For example, failed sign-ins and usage that it couldn't read. | Open it from Finder. |
| `~/.zero/asks.jsonl` | Every ask and every answer, one per line. | Right-click the control bar away from the tasks' dots, and choose **Open Log**. |
| `~/.zero/zerod/sessions/` | A folder for each task. `transcript.jsonl` holds everything that the task and its agent said to each other. `stderr.log` holds the agent's own errors. | Open it from Finder. The folder with the most recent change belongs to the task that worked last. |
The logs can hold your code and conversations. Read them before you share them.
## Updating Zero fails
Zero checks for updates when it opens and every six hours. The first row of **Settings › General** shows the result. When a check or an update fails, the row says why and shows **Check again**:
| Message | What to do |
|---|---|
| "Couldn't reach Zero's releases on GitHub" | Make sure that your internet connection works. Then click **Check again**. |
| "Couldn't download Zero" and the version | Click **Check again**, then **Update and restart**. |
| "Couldn't unzip Zero" and the version | Do the same: click **Check again**, then **Update and restart**. |
| "isn't signed as this Zero is, so it wasn't installed" | Zero installs only updates signed the same way as your Zero, so it skipped this one. Your Zero keeps working as it is. |
While the update installs, the row reads **Updating to Zero** and the version. Zero quits and opens again as the new version. Agents that are working continue after a pause of a few seconds.