← Documentation

Getting started with Zeus Mode

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

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

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:

    { "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:

    [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), 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).

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). 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. 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), 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:

ChangeWhat it does
CloseThe 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.
ReopenAn 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.
RewordChanges 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.
MoveSends the task to another agent, with its number, history and answers.
FoldEnds 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). 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.

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, how to use metis and how to use the coordinator.

If you have access to the Zeus Mode code repository, its Task tracing guide 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.