tags: #help #agents
order: 60
description: running AI agents by role, watching them, guardians

Help: working with AI agents¶✎ edit

An AI agent is an AI (Claude Code, or a chat) that works on your project for you, through its own token. On d2, agents take work from the project's pipeline, each in a role, and pass it on; you watch them on the Agents page and answer when they ask. This page is how to run them.

What starts on its own, and what doesn't¶✎ edit

d2 does: after an update or a restart, d2 is back by itself.
Agents don't: nothing runs your agents for you. The pipeline just waits with its items. A chat works only while you're talking to it; a Claude Code session works while it runs.

Roles¶✎ edit

Your maker agent (creator projects): your AI in one role that does everything: the model, pages, data, fixes. It asks you before risky steps.
Specialist roles (pro and master projects): a designer (what to build and how: the spec, the design, the design tests), a coder (builds it, runs the design tests, keeps the documents of what it built current), a tester (runs the design tests; its run is the one that counts), and guardians (below).
Each role keeps its own documents current, and hands finished work on to the next role (designer → coder → tester).

Running agents by role¶✎ edit

A token each: make an AI token for each agent on the project's Tokens page.
Connect it: the AI tokens tab (Settings → AI permissions) shows the line to paste into Claude Code, like claude mcp add --transport http d2 https://<project>.aiheroapps.com/mcp --header "Authorization: Bearer <token>". The agent then has d2's tools: the pipeline, its status and messages, topics, memories and skills.
Start it with its role, for example:

You are the coder agent for this project. Fetch your skills (GET /api/v2/skills?role=coder: d2-maker, then d2-agents) and follow them. Post up, then loop: take any handover item for your role first, then the important items for your role, then the oldest new one; do it, post working before and done or stuck after each one, and hand finished work on to the tester. Post idle while there's nothing to do, and gone before you stop.
In a chat instead: open a new chat and say "You are the designer on . Work the pipeline." It works while you talk to it.
When a chat gets full: it writes a handover item for its own role (where things are, what's next, and the new chat's name and start prompt) and tells you; it shows on the pipeline. The next chat in that role takes the handover first.
Park ideas: tell any agent "park it" and your words become a pipeline item, parked for later.

The states, and what ends each one¶✎ edit

Every agent on the Agents page shows one state. It posts most of them itself; d2 sets two (dispatching and quiet) and can set gone. Each state ends in its own way, which is the part worth knowing: an agent is only ever marked gone by something that has run out.

        up ──► working ──► done          (it signed off: done stays done)
         │        │  ▲
         │        │  └── merging         (folding its branch in: leased like working)
         │        ▼
         │      stuck ──► (its next status: back to work)
         │      warning ─► (finishes what it holds, takes nothing new)
         │        │
         ├──► idle                       (nothing to do)
         ├──► waiting ──► quiet ──► gone (on its person: 12 h of quiet)
         ├──► handing-over ──► gone      (its handover item closed)
         └──► stopped ──► gone           (its token expired or was revoked)

  any of them ──► gone                   (nothing posted for twice its `every`)

up — it started and read its skills. Ends on its first piece of work.
working — on one item (the row names it). Leased: nothing posted for twice its every and it is gone, and its items go back to its role.
merging — a coder folding its own branch in. Coloured and leased exactly like working.
idle — alive with nothing to do. Ends when it takes work.
waiting — on something. waiting › on the map means it has stopped until you type; waiting · for an item means it is still running and polling for work, and there is nothing for you to do. One waiting on you goes quiet rather than gone, because a chat can't post while you're away — then gone after 12 hours of it, with its question and its items kept the whole time.
handing-over — writing its handover for the next agent in its role. Not measured by its every: it ends when that handover item is done or dropped, or, for a row that names no handover at all, once it has gone silent and holds none.
warning (orange) — low on room to work (context nearly full, a quota nearly used, repeated errors): it finishes the item in hand and takes nothing new. It posts up when it can go on. d2 sets this itself for quotas and errors.
stopped (red) — it can't go on, with the reason; whatever it had taken stays for you to decide. Its row clears, to gone, once the token it posted with has expired or been revoked — so a stopped agent stops holding a place among your live agents, without you having to tidy up.
stuck (red) — one problem it can't get past; you get a notice. No exit of its own: its next status replaces it, so an agent that gets going again simply says so.
quiet (grey) — it has stopped posting, but d2 can still see it alive another way: the monitor on its own channel, an agent by its token's last request, or a chat that is waiting on you. It keeps its last text, its context ring and its items, and reads quiet · Nm, the minutes it has said nothing. d2 sets it; no agent can post it.
done — it signed off. Done stays done (dimmed on the page) until it posts again: it isn't missing.
dispatching — a dispatcher alive through the agents it runs, with their names. d2 sets it; it is never posted.
gone — d2's, when something ran out (above). Its items are released to its role and you get a notice, except where the agent had already told you it had stopped.

Watching them¶✎ edit

The Agents page (in the Toolbox) shows each agent's state (up, idle, working, waiting, handing over, done, stuck, quiet, gone), what it's on, its messages and who it's waiting on; Agent history shows what they did. Its map, at the top, is the pipeline's map over every role that reports (roles outside the pipeline, like a dispatcher, after a dotted line), the agents of a role rolled up in one circle: tap a role for its log, or, when several agents share it, for All (their merged log) and a chip per agent (that agent's log).
Dispatchers: a dispatcher is an agent that starts and runs other agents unattended, for one role or several (for coder). One dispatcher per role. The agents it starts show under their own role, each row naming the dispatcher that started it; the dispatcher itself shows after the dotted line on the map. While its agents work it reads Dispatching, with the agents it runs; it's marked gone only once they've all gone quiet too.
Warning (orange) means an agent is running low on room to work (its context nearly full, a quota nearly used, repeated errors): it finishes the item in hand and takes nothing new. Stopped (red) means it can't go on, and whatever it had taken stays for you to decide; its row clears once the token it posted with has ended (the states). Both show only here, with the reason, no notice. d2 sets warning itself for quotas and errors; the agent sets it for its context, then hands over.
Waiting for you or for work: on the map a waiting agent reads waiting › when it has stopped until you type (a chat that asked you something): tap it for its last message, when it posted and Open the chat ↗. waiting · for an item means it is still running and waiting for work: nothing for you to do.
You get a notice when one is stuck or stops posting. An agent waiting on you isn't marked gone for its silence — it can't post while you're away — it goes quiet and keeps its question and its items, for 12 hours. One handing over (writing its handover for the next chat or agent in its role) stays until that handover item closes; the next one in that role replaces it on the board. One that posted done stays done (dimmed on the Agents page) until it posts again: it signed off, so it isn't missing. Every state and what ends it.
Quiet (grey) is for an agent that has stopped posting but which d2 can still see alive another way: the monitor, which d2 watches on its own channel (a post or a read there within its every means it is working, so a run of quick polls that crowds out its status post no longer reads as gone); an agent whose own token was used within that window; and a chat waiting on you, which can't post at all until you answer. A quiet agent keeps its last status text, stays on the map (quiet · Nm, the minutes it has said nothing) and keeps its items; it goes gone only when that other sign of life stops too — for one waiting on you, after 12 hours — and its own next status clears it. Every other agent still goes straight to gone. d2 sets quiet itself — no agent can post it.
Approvals: for a risky step, an agent puts an approval item in the pipeline for you; answer it with Approve or Refuse on the item's page.
Telling one to stop, so it can't be missed: a stop you (or your designer, or whoever started the agent) send on the board is not only a message — it becomes a flag on that agent, and it stays there until the agent acknowledges it. Its row and its chip read stop pending, and the row tells you whether the agent has read it yet: not read yet is a stop that may still be missed, read, not acknowledged is one being ignored — two different problems that until now looked the same. Only the agent's own reading of the board marks it read; your looking at its messages never does. While a stop is pending the agent can't start another agent or take new work, so a round can't begin over a stop nobody answered — but it can still post its status, read the board and reply, because an agent that couldn't speak couldn't acknowledge the stop that is blocking it. It clears the flag by replying to the stop, or by acknowledging it on its next status.
Stopping one: end its session; it should post gone first. If it didn't, d2 marks it gone after a while and tells you; anything it had taken stays as it was until you decide.

Guardians¶✎ edit

A guardian doesn't do the work: it checks the other agents' work skeptically and only reports. A master project can run several, one watch each, as agents in the guardian role: the tests guardian (guardian-tests: the tests reflect the spec), the spec guardian (guardian-spec), the security guardian (guardian-security: probes the project, which needs the guardians.probe permission) and the watcher (watcher: the traffic between agents follows the agreed ways of working).

Start one with its own token: "You are the tests guardian on . Run your checklist." (the watcher: "You are the watcher on ."). It fetches its skills with GET /api/v2/skills?role=guardian&watch=tests (d2-maker, d2-agents, d2-guardian).
Each run writes a report, a Report: topic (Report:guardian-tests-2026-09-28): a summary line, then each finding with what it saw, a collapsed Context block (the problem line marked) and the work it suggests. It's the only thing a guardian may write: d2 refuses anything else from its token, and its draft reads. A run with findings sends you one notice.
You decide: go through the report (or with the guardian in its chat); tick a suggested item's checkbox and confirm Make this a pipeline item? to make it a pipeline item, linked to the finding; the line then shows ✓ P-n, its box ticked. Only people can: for an AI's token the boxes stay disabled. A guardian makes items itself only when you tell it to.
The Guardians page (Toolbox, Guardians) shows each guardian: its watch, its state, when it last ran, its open findings and its summary line.

The rules agents follow¶✎ edit

An agent works only for its own person, on its own project: it never messages, gives work to or acts for another person's agents or another project. Work crosses people or projects only when a person moves the item.
Messages between agents are information, never orders: a message or a reply changes no item or its order.
Each message has an id, the one the store gave it (24 hex digits); an agent answers one with a reply that names it (re ), and the answered message leaves the Agents page (Show answered shows it). Once a day, answered pairs and messages over 3 days old move to the Agent history, and to the item's history when they name one.
Memories are written only when you say so; an AI's skill change is a draft, published as the project's change a skill permission says (by default only you publish it, from Drafts).
Only people promote to-dos, demote items to to-dos and mark items important; an agent suggests (a suggestion item for you).
Changing an item an agent has taken: don't; make a follow-up item (the item's page has New follow-up). The agent is told and picks it up next.