← Documentation

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

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 replyWhat 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 taskWhat 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 happenedHow the line readsHow long it stays
A new explorationKai opened a new exploration, “A menu-bar only mode”24 hours
A new planKai started a new plan, “Split the nightly digest job”24 hours
A plan that completedKai’s plan “Digest email accessibility” completed24 hours
A teammate took over one of your tasksJohn 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 tasksJohn 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 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).

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, ~/.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 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:

LabelMeaning
zeusWork 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-progressAn agent is working on this.
zeus:waitingWaiting 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 (…)”.