# Joining a team that already uses Zeus Mode

> Set up Zeus Mode for Claude Code and Codex to join an existing team, run its agents, and understand what is shared.

*You were added to a repository whose team runs on Zeus Mode for Claude Code and Codex. 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 Mode 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 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. Then open Settings (⌘,) in Zeus Mode 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 Mode see your sessions, registers Zeus Mode'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 Mode 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](/docs/getting-started/#the-zeus-rulebook) 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.

## 3. Sign in and join

```
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 Mode 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 you get a code: in an
email from Zeus Mode, or from your lead. (How a lead does this:
[If you lead the team](#if-you-lead-the-team-invite-from-the-team-page).)
You need write access to the team's repositories on GitHub; Zeus Mode'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 Mode would
use the name from your git settings (`git config user.name`) instead.

### If you lead the team: invite from the Team page

You can invite people to a team you own. Open the **Team** page (the
**Team** row in the list down the left side of the window) and press
**Invite…** at the top right. The same **Invite…** is the first item under
**Owner** in the **Team** menu, in the menu bar. On a team with only you on
it, the line under the page title reads "Only you here · Invite…", and that
**Invite…** opens the same window.

Type the person's GitHub login and their email address, then press
**Send invite**. Zeus Mode checks that they can write to every repository of the
team. If they cannot, it says which repository, and nothing is created or
sent. If they can, Zeus Mode emails them the join link and the install steps.
You may leave the email empty only for someone who has signed in to Zeus Mode
before: Zeus Mode then uses the address it already has for them. If no email
could go out, Zeus Mode gives you the code to pass on yourself.

**Invite…** is greyed out while the title bar's switch is on **Solo**: switch
it to **Team** first.

From a terminal it is:

```
zeus team invite <their GitHub login>
```

Add `--email <address>` to choose where the email goes.

If the Team page says "This repository is on no team." (or "These
repositories are on no team."), the workspace you picked is on none of your
teams yet, and the **Invite…** on that page stays off until it is. Press the **Add to …**
button that names a team you own, to add its repositories to that team, or
**Create a team…** to make a new one. A team of one is fine. Then invite.

## 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 Mode opens the runtime in the repository, with the session filed under that
agent from the start. Zeus Mode 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 four things you'll do

- **Run an agent,** as in step 4. Its session shows on the Dashboard's
  **Sessions** tab.
- **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 **For review**, on the Dashboard's
  **Documents** tab.
- **File work for an agent.** Ask an agent in its session, for example
  "file a task for hephaestus: …". The agent files it in Zeus Mode with its
  `work` tool, and the task appears on your board. When your team keeps
  its tasks on GitHub issues, Zeus Mode also opens an issue for it. See
  [File work through Zeus Mode](#file-work-through-zeus-mode).

**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, links to deliverables addressed to the
team or a named person, plans in motion (see [Planning with
metis](/docs/planning-with-metis/)), and your open ideas and those handed to metis. It does not send
transcripts or answers to those questions. The **Team** page in the app
is built from those summaries. Where the repository's tasks are kept on GitHub
issues, a teammate's task also shows on your own board, and once someone
else has taken it, in a group named **Taken elsewhere** (see [A teammate's
work](#a-teammates-work)).

Your ideas travel too. An idea is an exploration: a product idea you
think through with daedalus, Zeus Mode's product explorer, over several
sittings called rounds. The summary carries at most 10 ideas, open ones
and ones handed to metis, newest first, and one line for each:

- its id, such as `E-12`, and its title;
- its question, in one line;
- its repository;
- the path of its page in the repository, and the commit the page was last
  refreshed at;
- the path of its poster, the picture drawn for it;
- how many rounds it has had ("round 3", or "no round yet");
- when the last round began.

The team service keeps these lines and shows them to your teammates on the
**Team** page. A teammate reads the page itself from the repository, at the
commit named: Zeus Mode never copies it. The rounds, the answers, and anything
said in a sitting never leave your Mac. An idea you hand to metis is still
sent while metis makes its plan. Your teammates see it on the **Team** page,
marked "handed to Metis, plan not started". It stops being sent as an idea
when its plan is in motion; from then on it shows as a plan. An idea that
was shelved is never sent.
On the **Team** page, **What leaves this machine** lists each idea your Mac
sent.

For each task, the summary carries its title and its one summary sentence
(at most 40 words). It never carries the task's description, its "done
when" (the words that say when the task is finished), an answer, a
transcript, a prompt or a checkpoint. Two things go to one teammate only.
When a teammate takes over one of your tasks, your Mac sends them its
description and "done when". When the task is tied to a GitHub issue, it
also sends the issue's web address. A note you add to a teammate's task goes to
them too (see
[When a teammate already has your task](#when-a-teammate-already-has-your-task)).
Zeus Mode's team service keeps these words until the other Mac takes them,
for 30 days at most. With mirroring on, more leaves your
Mac: the whole task — title, summary, description and "done when" —
becomes an issue in the repository chosen to receive it, and how it ended
and what it produced are added to that issue later. Everyone who can read
that repository's issues can read it. See
[What appears on GitHub](#what-appears-on-github). When the workspace
mirrors to beads instead, the whole task goes into the repository's beads
database. Zeus Mode then runs `bd sync` itself, which sends the database to the
repository's git remote. Everyone who can read that repository can read the
task there. See [Mirroring tasks to
beads](/docs/beads/).

A plan is different from a task: the summary carries a copy of the whole
plan, while it is in motion and for 7 days after it ends. The copy includes
the plan's title, repository, goal and "done when", and for every step its
title, its agent, its state, its order, its task number, its short summary
(the brief), the words of a question only you answer, what a step that
waits for you to bring something expects, and a check's public link. A
piece of a plan's text stays on your Mac when it runs over several lines,
holds a block of code, a path on your Mac or a token count or price, or is
very long. A very large plan is cut short. A task's "done when" still never
goes to the team service unless you mirror the task. [Planning with
metis](/docs/planning-with-metis/) explains plans.

**When the summary is full.** A summary has a size limit, and a Mac with
many open tasks can fill it. Then Zeus Mode first leaves out finished tasks
older than a day. Next, before it leaves out any idea or plan, it takes room
from the tasks no session is working on.
First it leaves out the note of when and how each file was seen (a file
detail). If that is not enough, it also leaves out the file names, and sends
only how many files there are (a file list). A task a session is working on
keeps everything. **What leaves this machine**, and `zeus team status
--sent` (below), then show how many tasks lost each one, on the line that
lists what was not sent:

```
12 file details not sent: the summary was full · 5 file lists not sent: the summary was full
```

Your teammates then see a number such as "6 files" in place of the file
names.

To stop sending:

```
zeus team solo
```

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

```
zeus team status --sent
```

Something else leaves your Mac, whether or not you are on a team. Zeus Mode asks
the AI model of your own Claude or Codex account for some small jobs — for
example, to check whether a new task repeats an open one. These go to the
same company that already runs your sessions. The one that runs all the
time names your sessions. To give each session a name, Zeus Mode sends the last
part of its conversation — about 4,000 tokens of what you and the agent
wrote, and the first prompt, never tool output — to the smallest model of
the same tool, Claude or Codex, that runs the session, on your own account.
It does this at most every 5 minutes, and only when the session has grown.
(A token is a small piece of a word.) To stop naming sessions this way:

```
zeus goals off
```

The background program reads this the next time it starts (for example,
after you restart your Mac), so the calls stop from then on. Sessions keep
the names they already have. `zeus goals on` turns it back on. A
`ZEUS_GOALS` setting in the background program's environment wins over
both.

## When a teammate already has your task

Before a session files a task, Zeus Mode checks whether the same work is
already open. The check also looks at your teammates' open tasks in the
same repository. It uses the tasks your Mac already has from your
teammates' summaries, the ones the **Team** page shows, so nothing new
leaves your Mac for it.

In this section, you are John, and Mary is the teammate whose Mac has the
task.

### What the session tells you

When Mary already has the work, your task is not filed. Zeus Mode's reply
to the session starts `Not filed yet — this looks like work a teammate
already has`, lists the tasks it matched, and names who has it, like this:

```
Mary already has this: mary/T-12 (T-12 on Mary's Mac).
```

`mary/T-12` is Mary's GitHub login and her task's number on her Mac. The
session then asks you to choose one of three ways:

- **Take it over.** The task becomes yours, and Mary's closes.
- **Add a note to hers.** Your words are added to her task. The task stays
  hers.
- **File yours as separate.** Your task is filed anyway, with your reason
  why it is different work.

When a session of Mary's is working on the task, it is not taken over:
the session offers only the note, or filing yours as separate.

Starting a plan is a little different. A step that Mary already has is not
filed, and the steps after it are filed waiting on it. The session offers
the same ways for that step. After a takeover, the session points the step
at your new task and starts the plan again. A note leaves the step waiting,
until you choose to take it over or to file yours as separate.

The session acts only on your own words. Tell it which way you want, for
example "take it over", or "add a note to hers: the timeout is in the
upload client".

### When you take it over

Your task is filed at once, and you can start on it. Mary's Mac closes her
task the next time it checks in with Zeus Mode's team service. Until then,
`zeus work show` on your task prints a line under it that starts
`taken over from Mary's T-12 (mary) —`, then says how things stand:

```
  taken over from Mary's T-12 (mary) — Mary's Mac has not heard yet; the task there closes when that Mac next checks in.
```

When her Mac has heard, the end of the line reads
`Mary's Mac heard: Mary's T-12 is closed, taken over.` Mary's description and her "done when" line then
arrive on your task, under **From Mary**. Nothing else of hers travels: not
a checkpoint a session of hers saved, and not her branch. If her Mac is off
for a while, you start with your task's title and summary (see the next
paragraphs), and the rest arrives when her Mac is back.

**Your task's title and summary.** You can tell the session what to call
your task, for example "take it over, and call it Resume uploads on slow
Wi-Fi". Zeus Mode then files your task under that title. It must follow the rule for
every task's title: at most 8 words and 60 characters, with no task number,
file name or path, code, or § sign in it. If it does not, nothing is filed,
and the session is told the rule.

If you give no title, your task takes Mary's title. When her title breaks
that rule, Zeus Mode shortens it: it leaves out any task number, file name
or path, code or § sign, keeps the first words that fit, and ends the title
with "…". If fewer than two words are left, your task is called "Work taken
over from Mary".

When your task's title is not Mary's, Zeus Mode's reply to the session says
what it is. For example, if Mary's title is "Uploads time out on large files
over slow hotel Wi-Fi, and every retry starts again from zero", the reply
starts like this:

```
took over Mary's T-12 as T-40, for hephaestus. It is filed as "Uploads time out on large files over slow…".
```

You can also give your task its own short summary, for example "take it
over, with the summary: Uploads will go on from where they stopped, instead
of starting again." It must follow the rule for every task's summary: at
most 40 words and 300 characters, with no task number, file name or path,
code, or § sign in it. If it does not, nothing is filed, and the session is
told the rule. If you give no summary, your task takes Mary's. When hers is
empty or breaks that rule, your task's summary is "Work taken over from
Mary, who had it on another Mac." When Mary's name does not fit the rule
either, this summary, and the title "Work taken over from Mary" above, say
"a teammate" instead of her name.

If you take over the same task of Mary's again, you get back the task you
filed the first time, with its title and summary: a title or summary you
give the second time is not used. When you gave a different title, the reply says so. For
example, it starts: `took over Mary's T-12 as T-40, for hephaestus. It is filed as "Resume uploads on slow Wi-Fi". The title you gave was not used.`
When you gave a different summary, it adds `Its summary is "…".`

If your task's title or summary is different from Mary's, Zeus Mode keeps
her title or summary on your task at once (when she had one), even while her
Mac is off. `zeus work show` on your task lists them under `ADDED SINCE IT
WAS FILED`, in one block named "From Mary". It has a `Title:` line only when
the two titles differ, and a `Summary:` line only when the two summaries
differ. With both, it reads like this:

```
  "From Mary"
        kept on this Mac at the takeover, 1m ago
        Title: Uploads time out on large files over slow hotel Wi-Fi, and every retry starts again from zero
        Summary: Large uploads stop on slow networks, and each retry starts from zero.
```

Its second line says "kept on this Mac at the takeover" and how long ago;
the task's card in the app says the same.

Her description and "done when" line come later, when her Mac has heard and
closed her task, in another block that is also called "From Mary". That
block's second line says "sent from a teammate's Mac" instead.

**A task kept as a GitHub issue or a bead.** When your Mac keeps that
repository's tasks on GitHub issues or in beads, no second task is filed.
Your Mac's own copy of the same issue or bead becomes yours, under its own
title and summary: a title or summary you give the session is not used. At
its next check of GitHub or beads, Zeus Mode makes you the issue's only
assignee and leaves it open. Mary's copy then reads as taken by you (see [A
teammate's work](#a-teammates-work) and [Mirroring tasks to
beads](/docs/beads/)). This works while Mary's Mac is off.

**When your Mac has no copy of the issue.** Your Mac makes its own copy of
an issue when it reads the target repository, every few minutes. If it has
no copy of Mary's issue yet, but one can still come, nothing is filed, and
Zeus Mode's reply to the session says:

```
Mary's T-12 is kept as a GitHub issue or a bead, and this Mac has no copy of it yet — the mirror here has not read it. Try again after its next poll. Nothing changed.
```

Wait a few minutes, then ask the session to take it over again.

Sometimes no copy will come to your Mac, as things stand on GitHub. Then
the takeover is refused:
nothing is filed, nothing is sent to GitHub or to Mary's Mac, and the task
stays Mary's. The reply says why, after "will come to this Mac:", like this:

```
Mary's T-12 is kept as a GitHub issue, and no copy of it will come to this Mac: this Mac last read it closed. So it is not taken over here. File your own task with separate_from naming mary/T-12, or add a note. Nothing changed.
```

| The reason in the reply | What it means |
|---|---|
| `that repository is public, and Zeus keeps no issues of a public repository.` | The target repository is public, so your Mac reads none of its issues ([A public repository is never mirrored](#a-public-repository-is-never-mirrored)). Your Mac's setting still keeps that repository's issues, so the takeover is refused, and not filed as in *When your Mac does not keep that repository's issues*, below. |
| `this Mac last read it closed.` | The issue was closed on GitHub when your Mac last read it. |
| `this Mac's last read did not find it in that repository any more.` | The issue was deleted from GitHub, or moved to another repository. |
| `this Mac's copy of it, T-31, has ended.` | Your Mac had its own task for this issue (here T-31), that task has ended, and Zeus Mode will not open it again. |
| `its labels name no single agent, so this Mac makes no task of it.` | The issue has no `agent:` label, or more than one ([An issue made by hand](#an-issue-made-by-hand)). |
| `it was filed by an older Zeus that does not read claims, so this Mac makes no task of it.` | The issue was opened by a Mac with an older version of Zeus Mode, and your Mac makes no task of an issue like that. |

Instead, choose one of the other two ways in [What the session tells
you](#what-the-session-tells-you): file your own task as separate, for
example "file mine as separate from mary/T-12: her issue is closed", or add
a note to hers. If the cause changes on GitHub — the issue is opened
again, it gets one `agent:` label, or the repository is made private — a
later read by your Mac may make a copy, and a takeover then works.

One reason is different, because it can go away: `gh`, the GitHub
command-line tool, is not signed in on your Mac. Then your Mac reads none of
that repository's issues, and the reply says:

```
Mary's T-12 is kept as a GitHub issue, and this Mac has no copy of it: gh is not signed in here, so the mirror reads none of that repository's issues. Sign in (gh auth login), and within the hour the mirror reads it; then take it over again. Nothing changed.
```

Sign in with `gh auth login` in a terminal (`gh auth status` shows whether
you are signed in). Within the hour your Mac reads the issues again. Then
ask the session to take the task over again.

**When your Mac does not keep that repository's issues.** You can still take
the task over. Your task is filed at once, as for any other task. It uses
the title and summary you give, or Mary's, as *Your task's title and
summary* above says. The issue itself is not moved: it stays open,
and it still names the same people. Zeus Mode's reply to the session says
so in this sentence:

```
The issue was not moved: this Mac does not keep that repository's GitHub issues, so it still names whoever it named.
```

For a bead, the sentence says "bead" and "beads". When Mary's Mac hears,
her task closes and her words reach yours, as above. (When her Mac still
keeps the issue, it leaves her task open if, as it last read GitHub,
someone else has the issue, or it could not tell who has it: see [When Mary's task is not
closed](#when-marys-task-is-not-closed).) For a GitHub issue, the "From
Mary" block also gives the issue's web address, before her words, like
this:

```
  "From Mary"
        sent from a teammate's Mac, 2m ago
        Issue: https://github.com/acme/uploads/issues/42

        Large uploads time out at the proxy.
        Done when: a 2 GB upload finishes over a slow link.
```

**When Mary's Mac stopped keeping issues.** Her tasks that still show
under her name on the **Team** page (see [Turn it off, and what is
left](#turn-it-off-and-what-is-left)) can still be taken over. If your
Mac keeps the issues, your copy becomes yours and the issue moves to you,
as above; if it does not, the issue is not moved. Either way, her Mac
closes her task as taken over, and her words reach your task in a "From
Mary" block, with the issue's web address first for a GitHub issue.

### What Mary sees

Nothing pings Mary, and nothing is added to her **Needs you** page. The
next time she opens the **Team** page, she reads one line in the Team feed:

```
John took over your task “Uploads time out on large files”
```

Her task is closed. Its card in the app reads "Taken over by John as
T-40", and how long ago. It never reads "Failed". In a terminal,
`zeus work show T-12` prints the state `closed` and this line under it:

```
  taken over by John as T-40 — 5m ago, from a teammate's Mac
```

When the task is kept as an issue or a bead that both Macs keep, nothing
closes on her Mac: her copy reads as taken by you instead (see [A
teammate's work](#a-teammates-work)).

A step of a plan is never closed this way
([below](#when-marys-task-is-not-closed)). But when a plan's step names a
task that was already taken over, `zeus plan show` reads
`T-12 taken over by John as T-40` for that step.

### When you add a note

Your words reach Mary's task the next time her Mac checks in. A note can be
up to about 4,000 characters, about a page. The task stays hers, and a session of
hers that is working on it carries on. On her task's card, the note is
headed **Note from John**, with the line "from John's Mac" and how long
ago. She also reads one line in the Team feed:

```
John added a note to your task “Uploads time out on large files”: “the timeout is in the upload client”
```

The feed shows only the start of the note: its first line, cut at 60
characters with "…". When the task is kept as a GitHub issue or a bead, your note is written as
a comment on it, as words added to a task always are
([What appears on GitHub](#what-appears-on-github)).
If your Mac does not keep that repository's issues (or beads), no comment
is written, and your note reaches Mary's task as a note, as for any other
task. The same happens when your Mac keeps them but has no copy of the
issue for one of the reasons in *When your Mac has no copy of the issue*,
above, including `gh` not being signed in. Zeus Mode's reply to the session then starts
`your note is on its way to Mary's T-12: Mary's Mac adds it at its next check-in, and the task stays Mary's.`
and Mary's Mac adds the note to her task even when it keeps the issue.
If your Mac has no copy yet but one can still come, the note is refused
with the same "Try again after its next poll" reply as a takeover. If Mary's Mac does not keep them, the note is also added to her task,
because a comment on the issue would not reach her.

### When Mary's task is not closed

Your task still stands, and the end of the line on it (after
`taken over from Mary's T-12 (mary) —`) says why:

| The end of the line on your task | What it means |
|---|---|
| `Mary's Mac heard, and a session there was working on T-12, so it was left open; both tasks stand.` | A session of Mary's started on the task before her Mac heard. You can ask your session again once Mary's session is done: a new takeover sends a new notice. |
| `Mary's Mac heard; T-12 is a step of a plan, so it was left open; both tasks stand.` | Mary's task is a step of a plan, and a step is not closed this way. |
| `you ended T-40 before Mary's Mac heard, so nothing was sent and Mary's T-12 stays open.` | You ended your own task first, so Mary's Mac was never told. |
| `Mary left the team before that Mac heard, so the notice was deleted and Mary's T-12 was not closed.` | Mary is no longer on the team. |
| `Mary's Mac never heard; the notice was deleted after 30 days, and Mary's T-12 was not closed.` | Mary's Mac did not check in for 30 days. |
| `Mary's Mac heard; Mary's T-12 had already ended.` | Mary's task ended before her Mac heard. |
| `Mary's Mac heard; it holds no T-12 in that repository.` | Mary's Mac has no such task there any more. |
| `Mary's Mac heard; T-12 is kept as a GitHub issue or a bead there, so it was left open.` | Mary's Mac still keeps that issue or bead, and wrote nothing to GitHub. Either your Mac moved it to you and her copy follows it, or her Mac last read it as someone else's. |
| `Mary's Mac heard, but could not be sure nobody else holds the issue of T-12, so it was left open; take it over again to ask again.` | Mary's Mac still keeps that issue or bead, but could not tell who has it: for example, its GitHub sign-in had ended, or it had no copy of the issue yet. The reason may go away. Take the task over again, the same way as before: a new takeover asks her Mac again, and if it can then tell that nobody else holds the issue, her task closes as taken over (unless another row of this table applies, such as a session of hers now working on it). Neither of you reads a line about this in the Team feed. |
| `the team service would not pass the notice to Mary's Mac, so it will not hear of this and T-12 stays open there.` | The team service refused the notice, for example because that Mac is no longer Mary's. |

In the first two cases you and Mary each also read one line about it in
the [Team feed](#the-team-feed).

## The Team feed

The **Team** page shows the **Team feed** near its top: after the people
and the overview, and before **Needs you**, **Ideas** and **Plans**. It is one list, newest first, and each line
says how long ago it happened. It holds five kinds of line:

| What happened | How the line reads | How long it stays |
|---|---|---|
| A new exploration | Kai opened a new exploration, “A menu-bar only mode” | 24 hours |
| A new plan | Kai started a new plan, “Split the nightly digest job” | 24 hours |
| A plan that completed | Kai's plan “Digest email accessibility” completed | 24 hours |
| A teammate took over one of your tasks | John took over your task “Uploads time out on large files” | Until the page has shown it to you, then 24 hours more |
| A teammate added a note to one of your tasks | John added a note to your task “Uploads time out on large files”: “…” | Until the page has shown it to you, then 24 hours more |

Your own explorations and plans show too: "You opened a new exploration",
"You started a new plan", "Your plan … completed".

A takeover that did not close the task ([above](#when-marys-task-is-not-closed))
is a line about your own task too. When a session was on it, Mary reads
"John asked to take over your task “…”; a session of yours was on it, so
nothing was closed", and John reads "You asked to take over Mary's task
“…”; a session of Mary's was on it, so nothing was closed". When the task is
a step of a plan, the line ends "it is a step of a plan, so nothing was
closed".

- Tasks that were started or finished are not feed lines.
- Each task has its own line: four takeovers in one minute are four lines.
- The newest five lines show. When there are more, a line such as `3 more`
  opens the rest.
- A line about your own task counts as shown when the Team page draws it,
  in the window you are using. A line hidden under `3 more` is not shown
  yet. A line that is never shown leaves after 30 days.
- A plan you hid from the **Plans** shelf makes no feed line.
- Click a line to open the plan, the exploration or the task it names,
  when there is one to open.
- The feed pings nobody and adds nothing to any count.
- When there is nothing to show, the feed says so in one line, for example
  "Nothing new on Acme in the last 24 hours.", or, when you look at one
  workspace, "Nothing new in these repositories in the last 24 hours."

**Pick a person** near the top of the page (click their name, or, on a team
of four or more, choose them under **Person**), and the feed shows
only that person's lines: the explorations and plans they started, their
plans that completed, and their takeovers and notes on your tasks. With
nothing from them, it reads "Nothing new from Kai in the last 24 hours."
To see everyone again, press **‹ everyone**.

The team's todo list is not on the Team page. It is on the **Todo** page
([Your team's todo list](/docs/team-list/)).

## A teammate's open tasks

[Pick a person](#the-team-feed) on the **Team** page, and the page also
lists their open tasks. After **Finished**, a section headed **Their work**
(the app writes section names in capitals: THEIR WORK) shows every open task
they have, in groups:

- **working now**: a session is working on it;
- **waiting on a person**: its agent asked a question and waits for the
  answer;
- **blocked**: it waits for other work to finish;
- **ready**: nobody has started it yet. The first five show. A line such as
  "3 more ready" opens the rest.

Each row shows the task's title, its repository and number, and its agent.
Click a row to open its card: the task's **summary**, its **links**, and
**files it touched**. The agent of a task that is working now may also show
under **Running now**. When they have no open task, the section is not
there.

A card may say "6 files" under **files it touched**, and not name the files.
That teammate's summary was full (see *When the summary is full*, in [5. The
four things you'll do](#5-the-four-things-youll-do)).

The list stays on the page when the connection drops, for example when the
team service stops answering ([see
below](#the-team-page-says-the-team-service-has-not-answered)).

## If something looks wrong

The app's **Health** page (⇧⌘H) says what Zeus Mode 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.

### The Team page says the team service has not answered

The team service is the server that passes the summaries between your
team's Macs. When it stops answering, the **Team** page keeps what it last
received, and says so:

- Beside the page title, only the number of people shows, for example
  "6 people", not "connected".
- Under the title and its first sentence, a line reads, for example, "last
  status: no answer from the team service since 14:02 · this is Gladys as it
  was then".
- Under that, a card reads, for example, "This is Gladys as it was at 14:02,
  7 hours ago. The team service has not answered since then. Nothing here
  updates until it answers.", with a **Rejoin the team** button.

The line and the card stay at the top of the page, even when you look at
one person. When the team service answers again, the page updates by itself.

**Rejoin the team** sets the **Solo**/**Team** switch at the top of the
window to **Team**, the same as this command:

```
zeus team team
```

So it helps only when the switch is on **Solo**. Then there is no "last
status" line, and the card says instead, for example, "This is Gladys as it
was at 14:02, 7 hours ago. The switch says Solo, so nothing has been sent
since then. Set it to Team, and this page starts to update again." The
button makes your Mac start sending again. If the switch already says
**Team**, the button does nothing, and the page waits for the team service.

The title bar at the top of the window also shows when the team service
last answered, in the words just left of the **Solo**/**Team** switch. While
the switch is on **Team**, they show the time of the last answer, for
example "as of 14:02", instead of the usual "connected · …" line. If the
last answer was on an earlier day, the day shows too: "as of yesterday
14:02" or "as of 9 Sep 07:02". Hold the pointer over these words to see the
reason, for example "as of 14:02 · no answer from the team service since
14:02 · this is Gladys as it was then". In a narrow window the words go,
and only the small dot in front of them stays. Hold the pointer over the
dot to read them.

The **Team** row in the sidebar shows the same "as of" words, on **Solo**
too. On **Solo**, the title bar says "nothing leaves this machine" instead.

### The work board says shared work boards were removed

Zeus Mode once had a shared work board: one board that several Macs used
together. It was removed. A Mac set up with an older Zeus Mode may still carry
the setting that pointed it at that board, `ZEUS_WORK_SERVICE_URL`. Zeus Mode
never wrote that setting itself: an older guide told people to add it by
hand, in one of two places, or in both:

- the old startup file, `~/Library/LaunchAgents/ai.zeus.daemon.plist`.
  This is the file macOS read to start the daemon, Zeus Mode's background
  program, when you logged in, before Zeus.app started registering the
  daemon itself;
- a shell profile: a file your terminal reads when it opens, such as
  `~/.zshrc`, `~/.zprofile` or `~/.bash_profile`.

Where the setting is decides where you see it:

- **In the old startup file**, the daemon reads it, and this Mac's work
  board stays closed: no tasks are offered to any agent. The Dashboard's
  **Work items** tab, the **Work items** part of an agent's page and
  `zeus work`, which lists the board in a terminal, show a line saying so.
  `zeus work` prints `WORK · 0 tasks open`, then "the work service is
  unavailable:" followed by the sentence below, then "— no work is being
  offered."
- **In a shell profile**, the commands and agents you start from that
  terminal read it. `zeus work show` followed by any task number (for
  example `zeus work show T-1`) prints the sentence below and stops, and
  the agents' work tool refuses in the same way.

This is the sentence, as `zeus work show` prints it:

> zeus work show: shared work boards were removed in this version of Zeus.
> This Mac is still pointed at one (ZEUS_WORK_SERVICE_URL is set), so its
> work board stays closed. Remove ZEUS_WORK_SERVICE_URL and
> ZEUS_WORK_SERVICE_TOKEN_FILE from your shell profile (for example
> ~/.zshrc), because zeus mcp, the agents' work tool, reads it too, and
> open your terminals again. Do not edit Zeus's startup files; run zeus
> integrate autostart, which restarts the daemon without those settings.
> It will then use this Mac's own board.

The Health page has no card for it. Your tasks are not lost: they are on
this Mac's own board, which opens once the setting is gone.

To fix it, do what the sentence says:

1. Remove `ZEUS_WORK_SERVICE_URL`, `ZEUS_WORK_SERVICE_TOKEN_FILE` and
   `ZEUS_WORK_SERVICE_TOKEN` from your shell profile, if they are there.
   Then close your terminals and open them again, and start your agent
   sessions again: a session that is already running keeps the old
   setting.

2. Do not edit Zeus Mode's startup files by hand, and do not edit
   `~/Library/Application Support/Zeus/daemon-env.json`. Whatever your Mac
   looks like, run this one command:

   ```
   zeus integrate autostart
   ```

   What it does depends on how the daemon starts on your Mac:

   - If Zeus.app has registered the daemon, **System Settings → General →
     Login Items** lists it as **Zeus**. Its startup file is then inside
     the app and holds no settings of yours, and `daemon-env.json` holds
     only the PATH, which Zeus Mode writes. The setting cannot be there, and the
     command registers the daemon again through the app.
   - If the daemon still starts from the old startup file, the command
     rewrites that file in Zeus Mode's own form (the form Zeus Mode writes, with no
     settings added by hand) and restarts the daemon. When Zeus.app is
     installed, the command also prints that the old file is still in use
     and that Zeus.app moves it to Login Items the next time it opens. A
     file you edited by hand first defeats the command: a file that already
     matches Zeus Mode's form is left alone and the daemon is not restarted, so
     the old setting stays in force.

   When Zeus.app moves the daemon from the old startup file to Login Items,
   it does not carry the setting over. It renames the old file to
   `ai.zeus.daemon.plist.zeus-migrated-` followed by the date and time, so
   macOS no longer reads it. In the Zeus Mode app's menu bar, **View ▸ What Zeus
   did…** lists each setting the move left behind.

3. Check both places:
   - In a new terminal, run `zeus work show T-1`, or any other task
     number. It no longer prints the sentence: it shows the task, or says
     there is no such task.
   - Run `zeus work`. It lists the board.

## Keeping your team's tasks on GitHub issues

*Optional — set on each Mac.*

Each Mac has its own work board: the tasks your agents file stay on your
Mac. Zeus Mode can also keep those tasks on GitHub, as **issues**. A
GitHub issue is a ticket on github.com: a title, a body (its main text),
**labels** (coloured tags), comments, and a state — open or closed.

We call this **mirroring**. A **workspace** is a named group of
repositories, chosen in the picker at the top of the rail (the list down
the left side of the window). When mirroring is on, every task filed in a
workspace also becomes one issue in one repository of that workspace. We
call that repository the **target repository**. Changes made to the issue
on GitHub come back to the task on your Mac. Teammates who mirror the same
repository to the same target see each other's tasks. Work is still filed
through Zeus Mode, not on GitHub: see *File work through Zeus Mode*, below.

Each teammate sets mirroring on their own Mac, to the same target
repository. A change applies only to tasks filed after it: switching
mirroring on does not open issues for tasks that already exist.

Zeus Mode can mirror to beads, a command-line issue tracker, instead of
GitHub issues: [Mirroring tasks to beads](/docs/beads/) explains it. This section
is about GitHub issues.

### What you need

- The GitHub command-line tool, `gh`, installed on your Mac and signed in
  (`gh auth login`; `gh auth status` shows whether you are) with an account
  that can write issues in the target repository. Zeus Mode uses `gh` for
  everything it reads from and writes to GitHub.
- A **private** repository on github.com as the target. Zeus Mode never mirrors
  to a public repository (see below).
- A checkout of that repository on your Mac that declares the team's agents
  (the `.zeus/agent.toml` file from step 4).

Before you turn it on, read *What appears on GitHub* below. Everything Zeus Mode
sends to the target repository stays there: turning mirroring off later
removes nothing. Zeus Mode also creates its labels in the target repository and
sets their colour and description; if your team already has a label with
the same name, its colour and description are replaced.

### Turn it on

If the workspace picker has no workspace yet, choose **New workspace…** at
the foot of the picker first: give it a name, tick the team's repository,
and press **Save**.

In the app: open the workspace picker at the top of the rail, hover the
workspace and press **edit**. Under the list of repositories is a line that
reads **Mirror tasks to**. Choose **GitHub issues**, then choose the
repository that will receive the issues, and press **Save**.

From a terminal, with Zeus Mode running:

```
zeus mirror <workspace> --store github --target Owner/name
```

`<workspace>` is the workspace's name — put it in quotes if it has a
space, as in `"My team"` — and `Owner/name` is the target repository as
GitHub names it, for example `acme/backend`. Zeus Mode answers:

```
<workspace> mirrors to GitHub issues in Owner/name.
```

You can leave out `--target` when the workspace holds only one repository.

### Check it

To see the setting of each workspace on this Mac:

```
zeus mirror
```

It prints one line per workspace: the name and `off`, or the name, `github`
and the target:

```
<workspace>	github	remote:github.com/Owner/name
<workspace>	off
```

The app's **Health** page (⇧⌘H), or `zeus health` in a terminal, tells you
when mirroring is set on but is not working, under the headline **Issue
mirroring is off where it is set on**, with one line per repository: "gh is
not signed in.", "the repository is public." or "the repository is not on
github.com." Zeus Mode checks again every hour.

### A public repository is never mirrored

Zeus Mode accepts a public repository as the target when you set it. But within
the hour Zeus Mode checks the repository on GitHub and finds it is public. It
keeps mirroring off and sends nothing, and the Health page says "the
repository is public." Make the repository private, or choose another
target.

### What appears on GitHub

Each task filed while mirroring is on becomes one issue in the target
repository:

- The issue's title is the task's title.
- The issue's body is the task's summary, then a heading **Description**,
  then a heading **Done when**, then a line saying which agent filed it from
  which Mac: `Filed by <agent> · <Mac> · via Zeus`. A part the task does
  not have is left out.
- Labels, listed below.
- When an agent takes the task, Zeus Mode adds a comment,
  `Taken by <agent> on <Mac>.`, and assigns the issue to that Mac's GitHub
  login.
- When the task is no longer held — the agent handed it off (gave it back
  for another agent or a later session to take), its lease ran out (its
  time holding the task ended), or the task was moved to another agent —
  Zeus Mode removes the assignee and the `zeus:in-progress` or `zeus:waiting`
  label, and changes the "Taken by" comment to say "Released in Zeus —
  this task is free to take again."
- When the task ends, Zeus Mode adds a comment and closes the issue. The
  comment begins "Completed in Zeus" or "Ended in Zeus without being
  done", with the agent's note when it left one; when someone closed the
  issue on GitHub first, the comment says so ("Completed in Zeus after
  GitHub closed it"). A "Completed" comment also lists the task's outputs
  (what the agent announced): a link for each one that is on GitHub or the
  web, and for anything else its name and `kept on <Mac>, not shared`. An
  "Ended" comment lists none.
- When a task is folded into another — ended because the two are the same
  work — Zeus Mode closes the issue as a **duplicate** of the other task's
  issue when both are in the same repository. Otherwise it adds a comment,
  `Folded in Zeus into <task> — <title>`, naming the other task and its
  issue, and closes the issue as **not planned**. An issue Zeus Mode did not
  open (one made by hand) gets that comment only and stays open.
- Words added to a task later become comments.
- A body or comment longer than 64,000 bytes — fewer characters when the
  text is not plain English letters — is cut, and ends "The full words are
  in Zeus."

Nothing from a session — a transcript, a prompt, a question's words, an
answer, a checkpoint — ever goes to GitHub.

The labels Zeus Mode puts on an issue:

| Label | Meaning |
|---|---|
| `zeus` | Work tracked by Zeus. On every issue Zeus Mode opens. |
| `agent:<name>` | Work for the `<name>` agent. An issue someone made by hand becomes a task when it carries this label (see *An issue made by hand*). |
| `repo:<name>` | Work in the `<name>` repository. One target holds the issues for every repository in the workspace, so this label says which one the task belongs to. Zeus Mode sets it on the issues it opens. A `repo:` label you add to an issue made by hand is ignored: such an issue always becomes a task of the target repository. |
| `zeus:in-progress` | An agent is working on this. |
| `zeus:waiting` | Waiting on a person's answer. While the task waits, this label replaces `zeus:in-progress`; when the question is answered, `zeus:in-progress` comes back. GitHub learns only that the task is waiting; the question and its answer stay on your Mac. |

Labels you add to an issue yourself are kept.

### What GitHub does to the task

Changes on GitHub come back to the task on your Mac:

- Closing the issue ends the task. Reopening it reopens the task.
- Editing the issue's title or body changes the task's words.
- Changing the `agent:` label moves the task to another agent. Removing it
  parks the task: it is offered to nobody.

This means anyone who can edit issues in the target repository can change
what an agent is asked to do.

### File work through Zeus Mode

All work goes through Zeus Mode, whether your workspace mirrors to GitHub
issues, to beads, or to nothing. That way you see and control every task
in one place.

To file a task, ask any agent you have running, in the session you have
open, for example "file a task for hephaestus: …". The task can be for
that agent or for another one. The agent files it in Zeus Mode with its `work`
tool, the tool Zeus Mode gives every agent for tasks. When your workspace
mirrors to GitHub issues, Zeus Mode then opens the task's issue in the target
repository. Zeus Mode has no command that files a task from a terminal.

If the issue already exists on GitHub, ask the agent to file the task as
that issue, for example "file a task for hephaestus as issue #512". Zeus Mode
opens no new issue: issue #512 becomes the task's issue, and Zeus Mode adds its
`zeus` and `agent:hephaestus` labels to it. The issue must be in the
target repository, where Zeus Mode keeps the workspace's issues; for most
teams that is the repository itself. This works only while the workspace
mirrors to GitHub issues, and only for an open issue that has no `agent:`
label for another agent, no `zeus:in-progress` label, and no open task
on this Mac yet — for example one Zeus Mode made after someone labelled the
issue (see *An issue made by hand*). Zeus Mode also refuses an issue that
its daily check found gone from GitHub, deleted or moved to another
repository. Zeus Mode reads the target repository's issues
every few minutes, so a new issue may take a few minutes before an agent
can file a task as it.

Do not open a new issue on GitHub to file work. Agents do not either:
they use their `work` tool. If the issue already exists, file the task as
that issue, as above, or label it, as the next section says — one or the
other, not both.

### An issue made by hand

Zeus Mode makes a task of an issue someone opened on GitHub on its own only
when it carries exactly one `agent:<name>` label, where `<name>` is an
agent the target repository declares. To see those names, run
`zeus agent list` in the top folder of your checkout of the target
repository. Its first line
is the path of the repository's `.zeus/agent.toml` file, and the names
listed under it are the ones to use. If the first line starts with `no`,
or the line under it says the file could not be read or declares no
agent, the repository declares no agent, and no label makes a task. The
names under the line `built into Zeus` are not declared by the
repository, so a label such as `agent:metis` makes no task. If the
repository declares an agent of its own named metis, `metis` is listed
under the first line and `agent:metis` makes a task for it; Zeus Mode's own
metis is then listed as `zeus-metis`.

Each Mac that mirrors the repository decides this for itself, from the
`.zeus/agent.toml` in its own checkout of the target repository. Within a
few minutes, a Mac whose checkout declares the agent makes the task. A
teammate who has not pulled the change that declares the agent gets no
task until they do, and their Health page counts the issue as for an
agent not declared here. The task's card says
`Written on GitHub by <login> in <repository> on <day>, <age> ago.`
Nothing is written back to GitHub until an agent takes the task.

A Mac makes these tasks only if the target repository is itself in a
workspace on that Mac that mirrors to GitHub issues in that target.

If the label `agent:<name>` is not there yet — Zeus Mode creates it only the
first time it puts that label on an issue itself — create it once, on the
repository's **Labels** page on GitHub or from a terminal:

```
gh label create "agent:<name>" --repo Owner/name
```

Then add it to the issue, on the issue's page or from a terminal.
`gh issue edit` refuses a label that does not exist yet:

```
gh issue edit <number> --add-label "agent:<name>" --repo Owner/name
```

If the `agent:` label names an agent the repository does not declare, Zeus Mode
does not make a task. The Health page counts these issues on its issue
mirroring card, with a line such as "1 issue is for an agent not declared
here". When nothing else is wrong with mirroring, the card's headline is
**Some GitHub issues are not picked up on this Mac**. When something else
is wrong too, the headline names that problem instead, for example
**Issue mirroring cannot reach GitHub**, and the line sits below it. If an
issue has no `agent:` label, or two, Zeus Mode does not make a task of it on its
own either, and the Health page does not mention it.

### A teammate's work

When a teammate's Mac mirrors the same repository to the same target, their
tasks show on your board too, as tasks of their own. A task nobody has
taken yet is ready for your agents like any other. Once someone else holds
it, it moves to a group named **Taken elsewhere** with the note *not yours
to start here*. Each card there says who has it: `Taken by <login> on <Mac>, for <time>.`
If the task is on your own second Mac, the card says
`Held on your other Mac, <Mac>, for <time>.` If GitHub has not answered
for 15 minutes, the card says when GitHub last showed the task in place of
`, for <time>.`: the line ends `, as GitHub last showed at <time>.`,
`, as GitHub last showed yesterday at <time>.` or
`, as GitHub last showed on <day> at <time>.` When the card does not know
when the task was taken, the line ends with a full stop and no time, as
in `Taken by <login> on <Mac>.` An agent on your Mac that asks for work
is told the same, and does not take the task. The **Team** page is unchanged.

### When GitHub cannot be reached

Nothing is lost. Each thing Zeus Mode wants to send to GitHub — open an issue,
add a comment, change a label, close an issue — waits in a queue on your
Mac, called the **outbox**, and is tried again after 1, 2, 4, 8, 16 and
then 30 minutes. After eight failed tries Zeus Mode stops retrying, and the
Health page shows a card that says `<task> could not be sent to GitHub`.
The task itself keeps working on your Mac. In the other direction, Zeus Mode
keeps the last copy of what it read from GitHub and asks again on the next
poll; the Health page, under the headline **Issue mirroring cannot reach
GitHub**, names the repository and the error.

### Turn it off, and what is left

In the app, choose **Off** on the **Mirror tasks to** line and press
**Save**. From a terminal:

```
zeus mirror <workspace> --store off
```

Zeus Mode answers `<workspace>: mirroring off.`

On GitHub, everything already sent stays: issues, labels, comments and
assignments. Nothing is removed or closed. On your Mac:

- Tasks keep their links to their issues.
- Anything still waiting in the outbox stays unsent.
- Tasks that came from an issue filed elsewhere (a teammate's, or one a
  person labelled on GitHub) are no longer offered to your agents. Switching mirroring back on offers them again.
- Changes on GitHub are no longer read, so closing an issue no longer ends
  the task.
- Your teammates still see some of your tasks on their **Team** page: the
  ones you filed on your Mac, and the issues you wrote yourself on GitHub.
  They can still take them over ([When you take it over](#when-you-take-it-over)).
  Two kinds no longer show under your name: a task your Mac only picked up
  from someone else's issue, when nobody holds it; and a task your Mac last
  read as taken by someone else, unless a session of yours is working on
  it.

### Two sign-ins

Mirroring uses `gh`'s own sign-in, not `zeus login`. Zeus Mode assigns issues to
your `gh` login. If the two names differ, the Health page says
"Your GitHub login (…) is not your Zeus sign-in (…)".
