- tags
- #help #agents #onboarding #wip
When your background agent needs you¶
Your background agents run on your own machine. A small script, the keeper, keeps each one going: it waits for work, starts your AI on it, and fixes most problems by itself. When it can't fix something, it tells you: a red Harness flag in your top bar, an alert in your Chatbox, and an email if your project sends them.
Tap the flag to see what failed on the Agents page. Once it's sorted, press Dismiss. The flag also goes away by itself when that agent is back up.
What failed, and what to do¶
| The flag says | What happened | What the keeper does | What you do |
|---|---|---|---|
| spend | Claude's usage limit is reached | waits an hour and tries again | nothing, or raise your Claude plan |
| token | your agent's d2 role token no longer works (revoked or expired) | waits | on Run your agents in the background, make a new setup line and give it to Claude: it reinstalls in place |
| crash | the AI keeps failing (4 tries in a row) | retries every 30 minutes; it has already run claude update |
look at the log it names, or run claude doctor in a terminal |
| other | usually: Claude Code is signed out on that machine | waits | open a terminal and run claude login; the keeper picks up by itself |
| down (on your desktop only) | d2 hasn't answered for 10 minutes | keeps trying every minute | nothing |
Things it handles without telling you¶
- Your agent's own token ran out: it makes a new one from the role token.
- The machine slept: it carries on when the machine wakes.
- A pass ran over an hour: it stops the pass, and the next one carries on.
- The chat session filled up: your agent hands over and the keeper starts a fresh session.
Install, reinstall, remove¶
- Install or reinstall: make a setup line on Run your agents in the background and paste it to Claude Code. Doing it again reinstalls in place.
- Check it: ask Claude to run
bash ~/d2/harness/<project>-<role>/keeper.sh ~/d2/harness/<project>-<role> check. - Stop it:
- on a Mac,
launchctl bootout gui/$(id -u)/com.d2.keeper.<project>-<role>; - on Linux,
systemctl --user disable --now d2-keeper-<project>-<role>.
- on a Mac,