Help › Agents · version 29 ·

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

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.

Updated by razie · version 29