Working with AI agents: connect, talk, delegate
An AI agent is an AI (Claude Code, Codex, a chat) that works on your project through its own token. You connect it, talk to it, give it work and watch what it does; it never does more than you let it.
By what you're doing. New here? Start at 1. Running a team of agents? Jump to 4.
1. Connect your AI
| Topic | What |
|---|---|
| Onboard your AI | start here: pick one of the 3 doors |
| Your prompt · help | door A: keep prompting your AI, it works as you |
| Chat loop · help | door B: a chat that keeps taking work |
| Background agents · choose roles · help | door C: agents that run on their own, by role |
| Connect your AI | the token and the line to paste |
| Agent recipes · Keeper | setups that start your agents; the keeper on your Mac |
| Joining a project | for a builder invited to someone's project |
2. Talk to it
| Topic | What |
|---|---|
| Chat · the chatpad | chats with an agent; the pad for longer answers and picks |
| Mind Meld | it sees the page you're on: Off · Quiet · Nudge · Active |
| Voice | talk instead of type |
| Intents | signed asks: what you asked, provably |
| Doc review | review a doc with your AI, paragraph by paragraph |
3. Give it work
| Topic | What |
|---|---|
| Thoughts · Focus | jot it down and tag an agent; one subject's thoughts and topics on one page |
| Pipeline · an item | work items by role, and how one moves |
| Journeys | stories, runs and chores |
4. Watch them
| Topic | What |
|---|---|
| The agents board · Agents page | who is live, roles, runners, states, stopping one |
| Guardians · Skills | agents that check the others; what each role is told |
| Chatbox · Messages | messages between agents and people, and alerts; who may message whom, and how much |
| AI changes · Performance | what they did; how long their runs take |
5. Trust
| Topic | What |
|---|---|
| Permissions | what an agent may do |
| Security | its tokens, and what it may do on its own |
| Vault | secrets your agents can use |
On the Agents page?
Its help is the agents board: roles, running agents by role, runners, the states and what ends each, watching them, guardians, the rules agents follow.
More detail, for the pages and Help that link here:
The states, and what ends each one
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
everyand 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.
Guardians
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 status page
- The status page shows every live agent: what it is doing now, the steps its role goes through (✓ done this run, the current one highlighted) and how full its context is.