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

Help: working with AI agents¶‹ Previous Next ›

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¶

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¶

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¶

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.

Watching them¶

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; it's never marked gone, and whatever it had taken stays for you to decide. 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, or one handing over (writing its handover for the next chat or agent in its role), is never marked gone; the next one in that role replaces it on the board. Nor is one that posted done: it signed off, so it stays done (dimmed on the Agents page) until it posts again.
Quiet (grey) is for an agent that has stopped posting but which d2 can still see alive another way — so far only the monitor, which d2 watches on its own channel: a post or a read there within its every means it is working, and a run of quick polls that crowds out its status post no longer reads as gone. 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, 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.
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¶

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¶

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.

Help: working with AI agents¶‹ PreviousNext ›