Joining a team that already uses Zeus

You were added to a repository whose team runs on Zeus. The repository already declares its agents, and your team lead runs a team. This gets you from cloning the repository to seeing your work in the app, in about five minutes.

An agent is a named worker with its own instructions. Zeus is the Mac app, plus a small background program, that shows what every agent on your machine is doing.

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. Then open Settings (⌘,) in Zeus and let it put a link to the zeus command in /usr/local/bin (choose ~/bin only if that folder is already on your PATH).

2. Set up

Clone the team’s repository if you have not yet, go into it, and run:

zeus integrate install

This writes the hooks that let Zeus see your sessions, registers Zeus’s tools with Claude Code and Codex, installs the Zeus rulebook plugin, and starts the background program at login. It backs up files before changing them. zeus integrate uninstall removes the integration and the rulebook. Keep a separate copy of settings you edited: after a reinstall, uninstall can restore an older backup.

It asks two things. First, which repositories Zeus may write in: tick the team’s repository — the folder you are in is offered, and a row marked [+] lets you type another path. That is what lets Zeus write its short pointer to the rulebook into the team’s agent charters (their instructions files) on your machine. Second, 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. If you skip the first question, tick the repository later:

zeus repos add <path>

The rulebook controls explain how to inspect it, turn one policy or the whole plugin off, and update older charter blocks. An app update refreshes the rulebook, but does not rewrite your team’s committed charters.

zeus login

A code appears. Press return and Zeus opens github.com, where you type the code in. Your machine then holds a key for you; Zeus never sees your password and never holds your GitHub token. From now on your name is verified, and your teammates see it.

Your lead invites you by your GitHub login and sends you a code. (On their machine that is zeus team invite <your GitHub login>.) You need write access to the team’s repositories on GitHub; Zeus’s team service checks this when you join:

zeus team join <code>

Without zeus login you cannot join a team; on your own machine Zeus would use the name from your git settings (git config user.name) instead.

4. Pull, and the team’s agents appear

If you cloned before the agents were added, pull first:

git pull

The agents your team declared arrive with the repository, in .zeus/agent.toml; zeus agent list prints their names. In that repository, start one:

zeus run <agent> --runtime claude

Or use Codex:

zeus run <agent> --runtime codex

Zeus opens the runtime in the repository, with the session filed under that agent from the start. Zeus reads a repository’s agents the first time a session runs in it on your Mac, so after this one every agent the team declared is on screen — even the ones that have never run here.

5. The three things you’ll do

Run an agent, as in step 4. Its session shows on the Dashboard under running now.
Answer its questions. When an agent needs a person, its question waits on the Needs you page (top of the list down the left side of the window), with the options it offered. Answer there, or from a terminal with zeus work answer <id> "your words". The task goes back to the agent that asked.
Review what it announced. Documents, reports and pull requests an agent announces land under needs your review.

What your teammates see. Periodically, and sooner when work changes, your machine sends a summary for the repositories your team shares. It includes 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. The Team page in the app shows one entry per person, built from those summaries.

To stop sending:

zeus team solo

To see the last summary your machine sent, word for word:

zeus team status --sent

If something looks wrong

The app’s Health page (⇧⌘H) says what Zeus can and cannot see, with the fix on each card. From a terminal:

zeus health
zeus sessions
zeus team

zeus health prints health checks for this machine. zeus sessions lists the sessions on this machine. zeus team shows your teams and what each one sees of this machine.

Optional — for the person who sets the team up.

By default each machine has its own work board: the tasks your agents create stay on your Mac. Zeus can serve one board to a whole team. The zeus work serve command provides that service, but it needs additional settings, including the database to use; that name alone is not a setup command.

A shared board currently requires administrator configuration. Each teammate’s background program needs the service address and its own token, registered to a person. Zeus’s normal setup does not put those settings in the LaunchAgent that starts the background program, so your administrator must configure it on each machine.

Reach the board over a private network or tunnel — for example, Tailscale or an SSH tunnel — never plain HTTP on the internet. Standing rules do not answer questions on a shared board.