Getting started with Zeus

From nothing to your first agent running in Zeus, in ten minutes.

Zeus is a Mac app plus a small background program. 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 shows it from that moment — even before it has run once.

The work board. Agents create tasks for each other and pass them along, on a board inside Zeus. You never create a task; you watch the board and answer questions.

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 needs your review until you have looked at it. (The names in italics are sections of the Dashboard.)

Receipts. Every claim on screen points at the tool call that proves it. What Zeus 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 — only if you will join a team or want standing rules (step 5).

1. Install

With Homebrew:

brew install zeus-mode/tap/zeus

This installs the Zeus app 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, but it is not on your PATH yet: open Settings (⌘,) in Zeus and let it put one link in /usr/local/bin (choose ~/bin only if that folder is already on your PATH). The rest of this guide uses that command.

2. Set up

Open Zeus. On a Mac where Zeus has never run, it says Zeus is not set up on this Mac yet. Press Set Zeus up. That runs the setup for you and asks nothing.

The same setup, from a terminal:

zeus integrate install

This one also asks two things the button does not: which repositories Zeus may write in, and whether to draw an icon and a flow chart for each agent. Drawing runs your coding runtime once per picture, so it uses a little of your usage allowance.

Either way, setup 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 sees your sessions;
a tool server named zeus, so agents get seven tools they can call (identify, announce, step, verdict, reply, flowchart, work);
a marked block of guidance in ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, so agents learn to tell Zeus what they produce;
a LaunchAgent (macOS’s way of starting a program at login) that runs the background program;
the Zeus rulebook, a plugin named zeus-protocol@zeus that gives agents the rules for working with Zeus;
for each repository you ticked, a short pointer to that rulebook in each agent’s charter — its instructions file under .claude/agents/.

Setup backs up files before changing them. 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.

Pressed the button? Then no repository is ticked yet. Step 4 does not need one — zeus agent new writes the rulebook pointer into the charter it creates. Tick a repository whose charters already exist with:

zeus repos add <path>

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 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 installs separately for Codex. Those hooks check certain agent actions; zeus integrate uninstall removes them along with the rest of Zeus’s integration.

Updates and older charters. After an app update, 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 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. Open a session

Open any Claude Code or Codex session, in any folder. It appears in Zeus within seconds. From a terminal, this shows the same thing:

zeus sessions

4. Your first agent

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 and declares the agent in .zeus/agent.toml. Then it offers to draw a flow chart and an icon (each is one short run of your coding runtime).

Start the agent:

zeus run <name> --runtime claude

or, with Codex:

zeus run <name> --runtime codex

Zeus opens the runtime in the agent’s repository, with the session filed under the agent’s name from the start. Look at the rail, the list down the left side of the window: the agent 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 under running now.

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.

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 tells that session your answer arrived.

Anything the agent produces and announces — a document, a report, a pull request — lands under needs your review, on the Dashboard and on the Needs you page.

Once you have signed in with GitHub (see Working with a team), answering the same kind of question the same way three times makes Zeus 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 offers again only after three more such answers.

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.
One section per repository in the workspace: its Agent map and its agents. Press ⌘K to find an agent by name and repository.
Health (⇧⌘H) and Usage (⌘U) at the bottom.

The Dashboard: waiting on you · needs your review · pull requests · work queue · running now.

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

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

Working with a team

zeus login gives you a verified name — a GitHub sign-in, so teammates see who you are. For the repositories your team shares, Zeus sends 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. It does not send transcripts or answers to those questions. See Joining a team.

Next steps

If you have access to the Zeus 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.