Joining a team that already uses Zeus Mode
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 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.) 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
worktool, 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.
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), 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).
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).
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. 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.
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 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 and Mirroring tasks to 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). 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). |
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: 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.) 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) 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 step of a plan is never closed this way
(below). 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).
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 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) 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 moreopens 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 moreis 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).
A teammate’s open tasks
Pick a person 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).
The list stays on the page when the connection drops, for example when the team service stops answering (see below).
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,~/.zprofileor~/.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 workprintsWORK · 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 showfollowed by any task number (for examplezeus 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:
Remove
ZEUS_WORK_SERVICE_URL,ZEUS_WORK_SERVICE_TOKEN_FILEandZEUS_WORK_SERVICE_TOKENfrom 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.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 autostartWhat 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.jsonholds 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.- 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
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.
- In a new terminal, run
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 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 statusshows whether you are) with an account that can write issues in the target repository. Zeus Mode usesghfor 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.tomlfile 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-progressorzeus:waitinglabel, 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). 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 (…)”.