# Getting started with Zeus Mode

> Install Zeus Mode for Claude Code and Codex, let it set up your repository, and run your first worker.

*Zeus Mode for Claude Code and Codex is a Mac app plus a small background
program. Open the app, and it walks you from your first look to a first plan
on the board, in five short screens. Once Zeus Mode and `gh` are installed,
you do not need a terminal for the rest.*

The background program watches every Claude Code and Codex session on your
machine; the app shows what is going on, with the evidence for every claim.

## What you get

**Agents.** An agent is a named worker with its own instructions. You declare
it in the repository it works on, and Zeus Mode shows it from that moment — even
before it has run once.

**Zeus Mode's own agents.** Zeus Mode brings five agents with it, ready in every
repository Zeus Mode knows. **zeus-setup** sets a repository up: it takes the
repository from no plan to a first plan, with you, in one sitting. **metis**
is the project manager: it drafts a project plan with you and files the tasks
when you say go ([Planning with metis](/docs/planning-with-metis/)). **daedalus** is the product explorer: it thinks a product
idea through with you and hands a plan to metis when you say so.
**prometheus** is the agent builder: it builds one worker agent for the
repository with you. **zeus-coordinator** runs a plan for you: it starts
the plan's workers, a few at a time, inside its own session
([Let the coordinator run the plan](#let-the-coordinator-run-the-plan)).
Of these, only zeus-coordinator starts workers for you, and only after
you start it.

**The work board.** Agents file tasks for each other and pass them along,
on a board inside Zeus Mode. You watch the board and answer questions. A team
can also keep its tasks on GitHub, as issues; then you can file work for an
agent there too — see
[Joining a team](/docs/joining-a-team/#keeping-your-teams-tasks-on-github-issues).

**Questions.** When an agent needs a person, it asks — and waits on the
board, not in a chat window you have to find. The question shows up on one
page, with the options the agent offered.

**The review queue.** What agents addressed to you — a document, a report, a
pull request — waits under **For review**, on the Dashboard's **Documents**
tab, until you have looked at it.

**Receipts.** Every claim on screen points at the tool call that proves it.
What Zeus Mode cannot prove, it shows as a gap — never as a guess.

## You need

- macOS 14 or newer.
- Claude Code or Codex, installed on the same Mac.
- A GitHub account, and a repository on GitHub that you work in. Its open
  issues are what your first plan is made from.
- `gh`, GitHub's own command-line tool, installed. Zeus Mode does not install it
  for you. With Homebrew, run `brew install gh`; without Homebrew, use
  GitHub's installer from <https://cli.github.com>. You do not need to sign
  `gh` in first: Zeus Mode signs it in for you, in the same step as Zeus Mode itself
  (step 2). If `gh` is missing when you get there, Zeus Mode says how to install
  it, and goes on by itself once it is there.

## 1. Install

With Homebrew:

```
brew install zeus-mode/tap/zeus
```

This installs the Zeus Mode app, named Zeus in your Applications folder, and puts the `zeus` command on your PATH.

Or download the DMG from <https://zeusmode.ai/download/> and drag Zeus to
your Applications folder. The app has the `zeus` command inside it. When
you set Zeus Mode up (step 2), it puts a link to that command in `~/bin`, with
no password. If your terminal does not find `zeus` afterwards, `~/bin` is
not on your PATH: open Settings (⌘,) in Zeus Mode and let it put the link in
`/usr/local/bin` instead (macOS asks for your password). The rest of this
guide uses that command.

### Keep Zeus Mode up to date

Zeus Mode updates itself, however you installed it. It checks for a new version
once a day. When it finds one, it waits until you are away: Zeus Mode is not the
app in front, and you have not touched the keyboard or mouse for five
minutes. Then it installs the new version and opens Zeus Mode again. It also
installs it when you quit Zeus Mode. When Zeus Mode opens again, a small window tells
you what is new.

To stop this, open Settings (⌘,) and, under **Updates**, turn off
**Automatically install updates**. Zeus Mode will still check every day, but it
will ask you before it installs anything. If you answered an update question
from Zeus Mode before, it keeps your answer. To check for a new version at any time, choose **Zeus ▸
Check for Updates…** in the menu bar, or click **Check for updates** in
Settings.

If you installed with Homebrew, you can also update with:

```
brew upgrade zeus
```

Homebrew stops Zeus Mode's background program while it upgrades. Open Zeus Mode
afterwards; if it asks, press **Set Zeus up** to start the background
program again.

Either way, the `zeus` command is updated too, if it is the link Zeus Mode made
to the program inside the app. Settings tells you if it is not.

## 2. Set up

Open Zeus Mode. The first time, on a Mac where Zeus Mode has never run, it shows five
steps down the left side: **See**, **Allow**, **Sign in**, **Go** and
**Done**. Each screen has one main button, and says which step you are on.

**See.** The first screen is called **Zeus already sees your work**. Zeus Mode
has read your past Claude Code and Codex sessions on this Mac, from
`~/.claude/projects` and `~/.codex/sessions`, and shows how many sessions
you had, in how many repositories, and how many agents it found in them.
Below that are your last 16 weeks of work, and the sessions arriving now:
open Claude Code or Codex in any folder, and it appears there in about a
second. Nothing is written yet. Press **Continue**.

**Allow.** The second screen, **Everything Zeus will set up**, lists every
change Zeus Mode will make. Each line names the file it touches, and you can
untick a line you do not want. The first two lines go together: untick one,
and Zeus Mode writes neither.

- Under **This Mac**: the hooks for Claude Code and Codex; the Zeus tools
  and its rulebook; **Run at login**, which starts Zeus Mode's background program
  when you log in (this one cannot be unticked); and the `zeus` command, as a
  link in `~/bin` (not shown when you installed with Homebrew, which already
  made the command). *What Allow writes*, below, explains each one.
- Under **Workspaces, by GitHub owner**: a **workspace** is a group of
  repositories that Zeus Mode shows together. Zeus Mode makes one workspace for each
  GitHub owner of the repositories you work in. You can rename a workspace
  right there.
- For each workspace, Zeus Mode tells you that it will create a new **private
  repository on GitHub for that workspace's instructions**, such as
  `github.com/<owner>/zeus-instructions`. Zeus Mode writes its instructions there,
  and only there. You are told, not asked.
- For each workspace, a line to **mirror work items to GitHub issues**: Zeus Mode
  then keeps each task as a GitHub issue too, both ways. It is ticked where
  your repositories already use GitHub issues.

On the right, **Checks Zeus ran** shows what Zeus Mode found on this Mac, one
line each. A line that says `skips` tells you what Zeus Mode will leave out and
why, and where there is a fix, it names it — for example, a Claude Code
built for Intel Macs, or Codex asking you once to trust Zeus's hooks.

Press **Set Zeus up**. One small window opens, **Confirm what Zeus mirrors
to GitHub**, with one line for each workspace: whether you want to mirror
work items from Zeus to GitHub issues, or not. Press **Confirm** (or
**Back** to change it). You can change it later in each workspace's
settings.

Every file is backed up before it is changed. Undoing all of it is one
command, shown on the last screen.

**Sign in.** The third screen, **Sign in with GitHub**, signs you in once,
for Zeus Mode and for `gh` together. Zeus Mode uses it to confirm who you are before
it puts your name on work. Press **Copy code and open GitHub**: it copies a
short code and opens GitHub in your browser. Paste the code there and
approve. There is no password anywhere in Zeus Mode. When GitHub says yes, the
screen changes by itself to **You are signed in**, and names the private
instructions repository Zeus Mode created. If `gh` was signed in already, there
is no code to copy: the screen goes straight to **You are signed in**.

To prove who you are, Zeus Mode has `gh` make a short secret gist (a small
private note) on your GitHub account, reads it once, and deletes it. Zeus Mode
never reads `gh`'s own key. If that does not work, Zeus Mode signs in by itself,
and `gh` stays as it was; the screen then says it signed in **Zeus** only.

If `gh` is not installed, the screen shows one line on how to install it in
place of the code, and starts no sign-in. Install `gh` (see *You need*), and
the sign-in starts by itself.

The same screen then asks: **Draft your first plan now, or look around
first?** Press **Draft my first plan**; the next screen, **Go**, is
described in [step 3](#3-set-up-this-repository). Press **Look around
first** to go to Zeus Mode's main window now.

**If you stop part way.** Until setup is finished, the rail on the left
side of Zeus Mode's main window shows **Finish onboarding**, with a red mark.
Press it to go back to the step where you left.

**On a Mac where Zeus Mode has run before**, you may see a different set-up
screen instead, with a **Set Zeus up** button. It sets up the same things.

### What Allow writes

- hooks for Claude Code and Codex — small commands the runtimes run when a
  session starts, stops or uses a tool, which is how Zeus Mode sees your sessions;
- a tool server named `zeus`, so agents get thirteen tools they can call
  (`identify`, `announce`, `step`, `verdict`, `reply`, `flowchart`, `work`,
  `plan`, `explore`, `todo`, `doc`, `card`, `schedule`);
- a marked block of guidance in `~/.claude/CLAUDE.md` and
  `~/.codex/AGENTS.md`, so agents learn to tell Zeus Mode what they produce;
- the background program, set to start when you log in. On a recent Zeus.app,
  macOS lists it as **Zeus** in System Settings, under **General ▸ Login
  Items**. Otherwise it is a LaunchAgent file (macOS's way of starting a
  program at login), `~/Library/LaunchAgents/ai.zeus.daemon.plist`. The
  Allow screen says which one your Mac gets;
- the **Zeus rulebook**, a plugin named `zeus-protocol@zeus` that gives
  agents the rules for working with Zeus Mode;
- the `zeus` command, as a link in `~/bin`, unless Homebrew already made it.

`zeus integrate uninstall` removes the integration, including the rulebook.
Keep a separate copy of settings you edited: after a reinstall, uninstall
can restore an older backup.

The app does not add the rulebook pointer to your repositories' agent
charters (each agent's instructions file under `.claude/agents/`). Making an
agent by hand (step 4, *Another agent, by hand*) does not need it —
`zeus agent new` writes the pointer into the charter it creates. To let Zeus Mode
write in a repository whose charters already exist, run:

```
zeus repos add <path>
```

### Setting up from a terminal instead

You can also set Zeus Mode up from a terminal. Go to your repository's folder
first, then run:

```
zeus integrate install
```

It writes the same things as Allow, and it also asks which repositories
Zeus may write in: a repository ticked here gets the rulebook pointer in
its agent charters. The keys are on the screen:

```
[↑↓] move   [space] toggle   [a] all   [n] none   [enter] confirm   [q] quit install
```

It can also draw an icon and a flow chart for each agent, and an **agent
map** — how the agents of a repository work together. Drawing runs your
coding runtime, so it uses a little of your usage allowance.
`zeus integrate install --charts --icons` draws the icons and charts later;
`--no-maps` skips the maps for one install.

At the end, when you ran it in a terminal window, inside a repository you
ticked, and every step worked, it offers to start zeus-setup in that
repository (step 3):

```
start setup now? It opens a Claude Code session that sets up this repository. [y/N]
```

Type `y` to start it there, in Claude Code. Anything else starts nothing and
prints the command for later: `zeus run setup`, or `zeus run zeus-setup` if
the repository has its own agent named `setup`.

With only Codex on your Mac, install asks too: in a plain terminal window,
and inside a Codex session where you can type an answer. The question says
"a Codex session", and `y` starts zeus-setup in Codex. Zeus Mode does not find
Claude Code, so it picks Codex. The command for later, `zeus run setup`,
picks Codex the same way.

If the repository already has its agents and a plan that was set in motion
(even one now done or stopped), install does not ask and prints nothing
about setup: zeus-setup is for a repository's first hour.

### The Zeus rulebook

The rulebook contains the shared rules agents follow, including separate
sets of rules called **policies**. To see its folder, version and whether
each runtime has it switched on, run:

```
zeus integrate list
```

**Turn one policy off for a repository.** Edit `.claude/toolkit.yml` in that
repository. For example, this turns off the policy that requires a status
file. If a `policies` section already exists, change or add the line there:

```yaml
policies:
  status-file: "off"
```

Other policies and the core rules still apply. This is the per-policy
switch for both Claude Code and Codex.

**Turn the whole rulebook plugin off.** Each runtime has its own setting:

- **Claude Code, one project:** merge this setting into the project's
  `.claude/settings.local.json`, keeping any other settings:

  ```json
  { "enabledPlugins": { "zeus-protocol@zeus": false } }
  ```

- **Codex, all projects:** in `~/.codex/config.toml`, edit the existing
  plugin table that setup added, changing `enabled = true` to `false`:

  ```toml
  [plugins."zeus-protocol@zeus"]
  enabled = false
  ```

  Do not add a second table with the same name: duplicate tables prevent
  Codex from loading its configuration. If you use a custom `CODEX_HOME`,
  edit the `config.toml` in that folder instead.

- **Codex, one project:** use the same table in the project's
  `.codex/config.toml`. This setting works only when Codex trusts the
  project; it is ignored in an untrusted project.

These settings disable the plugin in the runtime. They do not erase
instructions in agent charters. A Zeus Mode charter also tells the agent to read
the rulebook from disk if the plugin is missing from its skill list, so
disabling the plugin alone does not guarantee the agent stops following
those rules. Review the charter's instructions too if that is your intent.

The settings do not remove the guard hooks Zeus Mode installs separately for Codex.
Those hooks check certain agent actions; `zeus integrate uninstall`
removes them along with the rest of Zeus Mode's integration.

**Updates and older charters.** After an app update (how updates arrive is
in [Keep Zeus Mode up to date](#keep-zeus-mode-up-to-date)), the background program's
next start from Zeus.app refreshes the rulebook. For someone who never had
it, that first start installs it. If you removed it, Zeus Mode remembers and
leaves it removed. A switched-off Codex rulebook is left alone until you
switch it back on. Restart any open Codex session after a new rulebook
version arrives, so it can read the new files.

An app update does not rewrite your repository's charters. If
`zeus integrate list` or the app's Health page reports older Zeus blocks,
run `zeus integrate install` in a terminal. It updates untouched older
blocks and asks before replacing a block edited by hand; the default answer
is No. Review and commit any changed charters so your team gets the update.

## 3. Set up this repository

**Go.** When you press **Draft my first plan**, that press starts Zeus Mode's own agent
zeus-setup, in the background: in Claude Code if it is on your Mac,
otherwise in Codex. No Terminal window opens. zeus-setup works in the first
repository of the first workspace on the Allow screen; to set up another
repository, use `zeus run setup` in it (see *From a terminal*, below). The
screen is called **Your first plan**, and says which repository setup is
reading. If setup cannot start, the screen says why — for example, that
`gh` is not signed in, or that Zeus Mode found neither Claude Code nor Codex.

zeus-setup asks you a few things, **one question at a time**, on a card.
Where there are choices, they are lines you tick, and the main button says
what it does, such as **Take these 3**. To say something else, press
**Answer in my own words**. Beside the card, under **The plan, as it is
written**, you see the plan grow as it is written.

Here is what zeus-setup asks, in order.

**The worker.** A repository with no agents needs one worker — an agent
that can take the work. zeus-setup asks what to call it (you type the name;
it never picks one for you), what "done" looks like for its work, and which
part of the repository it works in. For the last two, it proposes an answer
from what it read. (If your repository already has agents, it fits those
instead; see *If you already have agents*, below.)

**How many workers at once.** When a plan runs, Zeus Mode can start workers side
by side. zeus-setup counts 1 worker for every 4 cores and 1 for every 8 GB of
memory, and proposes the smaller number. It also asks whether a new worker
should wait while the Mac is busy, so the Mac stays responsive (its pick),
or start anyway, to finish sooner. If your repository already has a
`.zeus/workers.toml`, it proposes what that file says instead. You can
choose 1 to 16. To see the number it will propose before you start, run
`zeus work slots --propose`. Your Mac also has one limit for all its
repositories (3 at first), and the lower of the two applies. Your answer
is written to `.zeus/workers.toml` in the setup pull request. It matters
when the coordinator runs your plan (see
[Let the coordinator run the plan](#let-the-coordinator-run-the-plan)).

**Stop one: the issues.** It proposes a first set of your open GitHub
issues for a first plan — small ones, not blocked by another issue, about
one or two weeks of work — with one reason each. Choose **Take these
\<n>**, **Change the list**, or **Stop here**. zeus-setup reads your issues;
it writes nothing to an issue. Issues labelled `zeus` are left out, because
those are Zeus Mode's own tasks.

**Stop two: the plan.** It shows the plan once: the worker, how many
workers run at once, the steps in order, who takes each, what "done" means
for each, and the gaps it found that are not in the plan. A **gap** is
something the worker needs that your repository does not have, such as a
test command or a push hook (a check that runs the tests before
`git push`). Tests that run on an outside service, such as GitHub Actions,
are not a gap. Only one gap becomes a step of the plan: if your repository
has a test command but no push hook that runs it, the first step adds that
hook. Every other gap is listed, one line each, so you can file it later.
Choose **Approve the plan**, **Change the plan**, or **Stop here**. Your
approval here is also your yes to setting the plan in motion once it is
merged. Stop here, at either stop, and nothing reaches your main branch.

**Done.** zeus-setup writes everything — the worker's files and the plan —
into **one pull request**: a proposed change to your repository, for you to
read on GitHub. Then the last screen says **Your first plan is on the
board**, with the plan's name and number of steps, and "Its pull request
merges on GitHub." Only you merge it, on GitHub. zeus-setup keeps checking
in the background: once you have merged, it puts the plan's steps on the
board as tasks for the worker and sets the plan in motion. You do not need
to tell it.

The Done screen also shows the one command that undoes the set-up,
`zeus integrate uninstall`. If you have Codex, it may also show **Your first
hour, drawn**: a comic strip Zeus Mode drew of your own work while you set up
(see [Comic strips](/docs/comic-strips/#the-first-launch-strip)). Nothing waits
for it.

Press **Meet your agents** to see **Your agents**: how an idea becomes
merged work, from your idea to daedalus, metis, the coordinator, your
agents, and back to you. For daedalus, metis and the coordinator, it shows
how each works, four things you can say to it, what it never does, a button
that starts it, and a post about it on the Zeus Mode blog. The page moves to the next agent every 15 seconds; press an
agent to stay on it. Later, **Help**, at the bottom of the rail, opens the
same page. Or press **Go to Zeus**.

From now on you can watch the plan on the **Project plans** page (its row
is under **Team** in the rail). P-n is the plan's number in Zeus Mode.

If setup stops before its pull request, the Go screen says "Setup stopped",
with the place of its log, `~/Library/Application Support/Zeus/first-plan-setup.log`,
and a **Try again** button.

### From a terminal

You can also start zeus-setup yourself, at any time, in a terminal inside
the repository:

```
zeus run setup
```

With Codex instead of Claude Code, add the runtime:

```
zeus run setup --runtime codex
```

In the app, a repository with no agents says **No agents here yet.** in the
rail, with this command and a **copy** button under it.

From a terminal, zeus-setup asks the same questions in its chat, and needs
`gh` signed in already: check with `gh auth status`, and sign in with
`gh auth login`. If `gh` is missing or signed out, zeus-setup stops before
asking anything and says "Nothing was written." Its first message is:

```
I am zeus-setup. In this sitting I will set this repository up for Zeus: a
worker that can take the work, a first set of your open issues, and a plan you
can watch in the app. I read first. You decide twice: which issues to strike,
and the plan. I ask at most four other questions, each with an answer ready.
```

When the pull request is open, it tells you:

```
Everything is in one pull request: <link>. Merging it is yours to do, not mine.
Merge #<n>, then tell me, and I set the plan in motion.
```

Merge the pull request on GitHub, then tell zeus-setup that you did. (It may
ask you to pull the merge into your copy of the repository first.) It puts
the plan's steps on the board as tasks for the worker, sets the plan in
motion, and ends with the command to run next:

```
P-n is in motion: <k> tasks are on the board for <worker>.
<Gaps not in the plan: a line each.>
What <worker> finds on a step waits for metis to sort: the app shows it as
"n items for metis", and `zeus run metis` here starts metis
(`zeus run zeus-metis` where this repository has its own agent named metis).
next: zeus run <worker>
```

If the session ends before you have merged, the plan waits as a draft, and
zeus-setup's last lines are these instead:

```
P-n waits as a draft until the setup is merged: <link>.
next: after merging #<n>, run `zeus run setup` again (`zeus run zeus-setup`
where this repository has its own agent named setup) — it finds its draft
plan and finishes.
```

### If you already have agents

zeus-setup fits them; it never rewrites them. It adds the Zeus block at the
end of an agent's charter if that is missing, and the test command in
`.claude/toolkit.yml` if that is missing. An agent Zeus Mode does not list yet is
declared, with one line saying what it is for and which kinds of plan step
it can take. Nothing else of yours changes.

If one of your agents has the same name as one of Zeus Mode's own — metis,
daedalus, prometheus, zeus-setup or zeus-coordinator — it stops before
writing anything and asks you to choose. **A:** it moves your agent into a
skill, word for word, which Zeus Mode's agent of that name loads whenever it
starts here; where yours works differently, yours wins. **B** (its pick):
your agent stays exactly as it is, and Zeus Mode's own runs here as
`zeus-<name>`. Nothing of yours changes.

With B and an agent of your own named metis, for example, once your agent
is declared (the setup pull request does that, if it is not yet),
`zeus run metis` starts yours, and Zeus Mode's runs here as `zeus-metis`.

The same goes for an agent of your own named `setup`: `zeus run setup` then
starts yours, and Zeus Mode's setup agent is `zeus run zeus-setup`.

## 4. Run the worker

Run the line zeus-setup printed, in the repository:

```
zeus run <worker>
```

`<worker>` is the name you gave it. To run it with Codex instead of Claude
Code, add the runtime:

```
zeus run <worker> --runtime codex
```

The worker takes the first step of the plan from the board and starts on
it. Zeus Mode starts no agent by itself — you run them, or you let the
coordinator run them for you (below). Watch the plan on
the **Project plans** page, and the worker in the rail, the list down the left side
of the window, where it is listed under its repository. (The rail shows one
workspace at a time; if yours shows another folder, pick the repository in
the picker at the top of the rail.) On the Dashboard, its session is on the
**Sessions** tab.

### Let the coordinator run the plan

Instead of starting each worker yourself, you can start one agent that
does it for you: **zeus-coordinator**. In the repository, run:

```
zeus run coordinator P-n
```

`P-n` is the plan's number, from the line zeus-setup printed. If only one
plan is in motion in this repository, you can leave it out. If there are
several, the coordinator asks which one. To run it with Codex, add
`--runtime codex`. (If your repository has an agent of its own named
`coordinator`, run `zeus run zeus-coordinator P-n` instead.) With Claude
Code, the coordinator starts in auto mode, so Claude Code asks you fewer
permission questions while it runs.

**What it does.** The coordinator reads the plan and starts the agent of
each step that is ready. It starts each one as a worker inside its own
session, so you do not open a window for each agent. It runs one worker per
agent at a time, and only as many workers as there are free **slots** (a
slot is one place for a worker; see below). It
says every start, every end and every stop, in its session and on its card
in the app. It can run for days, until the plan reaches its next **milestone** — a
named point in the plan, reached when every step before it has ended.

**The one question it asks you: about metis.** The plan's metis decides
which tasks one worker takes together. When no metis is serving this plan,
the coordinator asks you once:

```
No Metis serves P-n. Metis picks which tasks each worker takes together.
Shall I start Metis now, inside this session, to serve P-n? Or will you run
it yourself (`zeus run metis`)? Until then each worker takes one task. —
answer "start Metis" or "I'll run it" in For you
```

The question is also a card on the **For you** tab of the Dashboard, with
its two answers, **start Metis** and **I'll run it**. Press **Answer** on
the card, choose one, and press **Send**. Or type the answer in the
coordinator's session. With "start Metis", the
coordinator starts metis inside its own session. With "I'll run it", you
start it yourself with `zeus run metis`.

**The limit you set at setup.** All repositories on your Mac share the
same slots. Your Mac has one limit for all of them together; it starts
at 3, and `zeus work slots --limit <n>` changes it. Each repository can
also have a lower limit of its own: the number you gave zeus-setup,
written in `.zeus/workers.toml`. The lower of the two applies. To see the
slots in use, run:

```
zeus work slots
```

It prints, for example:

```
Worker slots on this Mac: 2 of 3 slots held.
  …
the Mac is busy
```

Between those lines it lists each slot in use and how busy the Mac is. The
last line says "a slot is free", "no slot is free" or "the Mac is busy".
When no slot is free, the coordinator waits and tells you so. If you
chose "responsive" at setup, it also waits while the Mac is busy.

**Where its run shows.** On the **Project plans** page, the plan's row
says what the coordinator is doing, in one line, for example:

```
run by the coordinator · 1 of 3 slots held · building T-45 (athena) · waiting: T-44 needs you
```

The line says how many slots it holds out of the limit, which tasks are
being built and by which agent, and what waits. If the repository's limit
is lower than the Mac's, the count says so: `(this repository's limit; the
Mac's is 3)`. When the coordinator stops, the line says
`coordinator stopped:` and why.

**One pull request per worker, and one for you to merge.** Each worker
opens one pull request for the tasks it took. That pull request goes to the
plan's own branch, `plan/P-n`, not to your main branch. If the
repository's tests passed when the worker pushed, and GitHub can merge it,
the coordinator merges it into that branch. Otherwise it asks you, in
Needs you, to merge it yourself. (A repository with no push hook that runs
the tests gets this question for every pull request.) When the
plan reaches its next milestone, the coordinator tests the whole branch and
opens one pull request from `plan/P-n` to main. That one is yours to merge.
Its last line says, for example:

```
done to milestone <name> — PR #k from plan/P-n to main waits for you — the
suite passed on plan/P-n at <sha12> — next: …
```

**When a question lands in Needs you.** When a metis serves the plan, a
worker's question goes to metis first. If you already decided this, for
example in the plan you approved, metis answers it. When metis cannot
answer it, the question comes to you on the **Needs you** page, already
prepared by metis:
what is being decided, why it came up, and metis's recommendation, marked
**Metis recommends**. The worker's own words are folded under it, and the
last line begins `Prepared by Metis from <agent>'s question.` With no
metis serving, the question comes to you as the worker wrote it. Answer it
as in
[When it needs you](#5-when-it-needs-you). The coordinator passes your
answer to the worker, word for word, and the work goes on.

The coordinator also posts some messages of its own on Needs you, so you
see them even when its window is closed: a step that failed, a step whose worker
stopped too many times, or a slot Zeus Mode refused. These need no answer; each
one says what you can do. It also posts a line when a task waits on the
merge of a pull request, such as `T-n waits on the merge of PR #m; I go on
when it merges`. The merge answers it by itself: within about a minute of
the coordinator's own merge, or when you merge a pull request it asked
you to merge.

### Every session shows up

Any Claude Code or Codex session you open, in any folder, appears in Zeus Mode
within seconds — not only the ones you start with `zeus run`. From a
terminal, this shows the same thing:

```
zeus sessions
```

### Another agent, by hand

You can also make an agent yourself. Go to the repository the agent will
work on and run the interview:

```
zeus agent new
```

It asks the agent's name and purpose, and which existing agent's rules to
copy, if any. It writes the agent's charter at `.claude/agents/<name>.md`,
declares the agent in `.zeus/agent.toml`, and offers to draw a flow chart
and an icon (each is one short run of your coding runtime). Then start it:

```
zeus run <name> --runtime claude
```

or, with Codex:

```
zeus run <name> --runtime codex
```

Zeus Mode opens the runtime in the agent's repository, with the session filed
under the agent's name from the start. Commit the new files with your work —
the charter, `.zeus/agent.toml`, and the chart or icon if you had them
drawn. That is how your teammates get the agent too.

Or let Zeus Mode's agent builder do the interview with you: `zeus run prometheus`
builds one worker agent for the repository, through one pull request you
merge.

## 5. When it needs you

An agent asks a person through the work board. Its question appears on the
**Needs you** page, with the options it offered. Choose one, or answer in
your own words. From a terminal, find the task with `zeus work` and answer
it:

```
zeus work answer <id> "your words"
```

The task goes back to the agent that asked, and Zeus Mode tells that session your
answer arrived.

Anything the agent produces and announces — a document, a report, a pull
request — lands under **For review**, on the Dashboard's **Documents** tab and
on the Needs you page.

Once you have signed in with GitHub (at step 2, or later with `zeus login`;
see [Working with a team](#working-with-a-team)), answering
the same kind of question the same way three times makes Zeus Mode offer a
**standing rule**: your recorded decision that this question is always
answered this way. Press **Make rule** and the next such question is
answered for you; press **Not now** and Zeus Mode offers again only after three
more such answers.

### Change a task on your word

You can change any task on the board, whichever agent it is for. Your word is
enough. These changes need the newest version of Zeus Mode: if `zeus work close`
is an unknown command, update Zeus Mode first.

There are five changes:

| Change | What it does |
|---|---|
| **Close** | The task ends without being done. It leaves the board and stays in Zeus Mode as history. **Removed** is a close that says the task should not have been there. |
| **Reopen** | An ended task goes back on the board, with the same number. A folded task is not reopened: its work goes on in the task it was folded into. |
| **Reword** | Changes the task's name, its summary, or its done-when line (the line that says how anyone will know it is finished). The old words stay in its history. |
| **Move** | Sends the task to another agent, with its number, history and answers. |
| **Fold** | Ends the task as part of another open task, when the two are the same work. Its words and files go to that task. A task with a question waiting on you cannot be folded: answer the question first. Both tasks must be in one repository. |

A draft (a task waiting on your yes or no) and a declined task take none of
these changes.

You can make each change in three ways.

**Tell any agent.** In the session of any named agent working in the task's
repository, say what you want in your own words, for example "close T-40,
another pull request already did it". The task can be another agent's. The agent
passes your words to Zeus Mode, and Zeus Mode writes them on the task with the session
that passed them on. Every agent that comes with Zeus Mode does this, and it keeps a
file for you the same way ([Keep any
file](/docs/save-from-your-chat/#keep-any-file)). Only your own repository's
instructions can make an agent say that this is not its job. Your word covers
changing a task and keeping a file; other things, such as answering a plan's
question or deleting a file, follow their own rules. Two things no agent does
on your word: start an agent, and merge a pull request. Those stay yours: the
agent says so, and gives you the command to run or the pull request to merge.
A session with no agent name, or one in another repository, is refused
and says why: use the app or a terminal instead.

**In the app.** On the Dashboard, open the **Work items** tab. Open a task and
click **Change**, or right-click its row. An open task offers **Close…**,
**Reword…**, **Move to** and **Fold into…**. **Move to** shows only when another
agent can take the task. A task waiting on a session, or held on another Mac,
offers nothing. An ended task has no row on **Work items**: open it with **Open
the task** on its change card, and it offers **Reopen…**. A folded task offers
neither, and says where it went. You can add your reason in words, but you do
not have to.

**In a terminal.** Use your own terminal, not one inside an agent's session.
`zeus work` lists the open tasks, and these make the changes, with your own task
numbers and agent names:

```
zeus work close T-40 --words "another pull request already did it"
zeus work close T-40 --removed
zeus work reopen T-40
zeus work reword T-40 --done-when "done when the send test passes on any date"
zeus work move T-40 --to athena
zeus work fold T-40 --into T-12 --instruction "same work"
```

`reword` also takes `--name` and `--summary`. Your words are optional here too:
`--words`, or `--instruction` for a fold.

If a session on another Mac is working on the task, your teammate's or your
own, the change is not made here. Zeus Mode says who holds it and how to go on.

#### When a session is working on the task

Zeus Mode asks you first, because the change could cost that session its work. The
one exception: if you tell the very agent working on the task, nothing is asked.
It makes the change itself, and for a close, a move or a fold its work on the
task ends.

```
Hephaestus is working on T-40 right now. Do you want it to stop?
Zeus tells it to save its work and stop. Then T-40 closes.
```

The agent you told asks you in its session. The app shows a dialog with **Yes,
stop it** and **No, leave it**. A terminal asks `[y/N]`; `--stop-it` on the
command says yes before you are asked.

If you say no, nothing changes. If you say yes, Zeus Mode tells that session to save
its work and stop, and the task reads `closing — waiting for hephaestus to
stop` until the session lets go. For the other changes the word is `moving`,
`folding` or `rewording`, and an Undo can wait the same way. While it waits, the task takes no other change. No
clock ends the wait. A session that has ended counts as letting go once Zeus Mode
has proof it is gone, which can take about ten minutes.

If the session does not stop, you can make the change at once. The task's card
has **Close now** (or **Move now**, **Fold now**, **Reword now**). It warns you
first that the agent may lose work it has not saved; commits it has made stay on
its branch. In a terminal, `zeus work show T-40` gives the change's number:

```
zeus work now C-41
```

Only you can do this, in the app or in your own terminal. An agent cannot do it
for you. A move or a fold cannot be made this way while that session also holds
a task that waits on this one: Zeus Mode says so, the change is dropped, and the
session keeps the task.

If the session finishes the task before it stops, the finish stands. The card
says your change was not applied, and you can reopen the task.

#### See a change, and undo it

Every change you make this way shows as a card, on the Dashboard's **For you**
tab and on the task. The card says what changed, who passed it on (an agent and
its session, **You, in the app**, or **You, at the command line**), your words,
and has an **Undo**.

Undo makes the opposite change, and has no time limit:

- Undo of a close reopens the task.
- Undo of a reopen puts the task back on how it ended.
- Undo of a reword brings the old words back.
- Undo of a move sends the task back.
- A fold has no Undo yet, and its card says so.

Undo asks you first if a session has since started working on the task, and it
says why when it cannot be done. In a terminal, `zeus work show T-40` lists each
change with its number:

```
zeus work undo C-41
```

**Dismiss** takes a card off the Dashboard. The change stays on the task, with
its Undo.

Three cases are worth knowing:

- **The task is a step of a plan.** The step reads closed. The steps after it
  can go on once what the closed step was waiting for has ended, and the plan's
  metis is told.
- **The task has a question waiting on you.** Closing it ends the question too,
  with your words on it, and the session that asked is told.
- **The task has an open pull request.** The pull request stays open, and it is
  yours to merge or close. The card says so.

## 6. Read the screen

**The rail**, down the left side:

- **Needs you** — questions waiting on you, work waiting on your review, and
  your standing rules, from every repository.
- **The workspace picker** — a workspace is a set of repositories; the rail
  shows one workspace at a time.
- **Dashboard** (⌘0) and **Team**, with **Project plans** under Team.
- **One section per repository** in the workspace: its **Agent map** and its
  agents. Press ⌘L to move into the rail, then type an agent's name to jump to
  it.
- **Finish onboarding**, with a red mark, until the first-hour setup is
  done; then **Health** (⇧⌘H), **Usage** (⌘U) and **Help** at the bottom.
  **Help** opens **Your agents**, the guide to Zeus Mode's own agents.

**The Dashboard** has five tabs: **For you** (questions waiting on you, and
changes made on your word), **Open PRs** (open pull requests), **Documents**
(work for your review, under **For review**, and reports for your information,
under **FYI**), **Sessions** (sessions running now) and **Work items** (the work
board).

**An agent's page**: its sessions, its outputs, its definition, and its
usage.

**Health**: what Zeus Mode can and cannot see right now, one card each, with the
fix on the card.

## Working with a team

Signing in with GitHub gives you a verified name, so teammates see who you
are. You did this at step 2; from a terminal, `zeus login` does the same. For the repositories your team shares, Zeus Mode sends a summary:
agent activity, task titles and short summaries, unanswered questions,
names of files touched, and links to deliverables addressed to the team or
a named person. Of a task's own text, the summary carries its title and
one summary sentence — never its description, its "done when" or an
answer, and never a transcript. If your team keeps its tasks on GitHub issues
(called *mirroring*), the whole task goes to GitHub as an issue in the
repository chosen to receive it: its title, summary, description and
"done when", the words added later, how it ended and what it produced, and
the names of the agent and the Mac that filed it and of those that took it.
Everyone who can read that repository's issues can read the issue. See
[Joining a team](/docs/joining-a-team/).

## Next steps

Three posts on the Zeus Mode blog show how to use Zeus Mode's own agents, with the
words to say to each:
[how to use daedalus](https://zeusmode.ai/blog/how-to-use-daedalus/),
[how to use metis](https://zeusmode.ai/blog/how-to-use-metis/) and
[how to use the coordinator](https://zeusmode.ai/blog/how-to-use-the-coordinator/).

If you have access to the Zeus Mode code repository, its
[Task tracing guide](https://github.com/Zeus-Mode/zeus/blob/main/docs/task-tracing.md)
explains how to send task events to a tracing service you already use.
This guide requires repository access; it is not published on this website.

When a piece of work spans several agents, see
[Planning work across agents with metis](/docs/planning-with-metis/).
