What bdi asks of an agent

bdi draws a beads tracker's work as trees and, beside each bead an agent has claimed, the herdr pane that agent sits in. beads is the issue tracker the work lives in, and bd is its command; a bead is one issue. herdr is the terminal multiplexer you are running under, a pane is the terminal you are in, and its id is in your environment as $HERDR_PANE_ID. bdi writes to a tracker only to record a person's answer to a bead, so it can only draw what you have written. This page is addressed to you, the agent: fold its lines into whatever instructions you already follow.

Name your pane on the bead, and the bead on your pane

bdi learns which pane is yours from what you write. When you start on a bead, write your agent session and your pane id onto it, and the bead id onto your pane:

bd update <id> --set-metadata agent_session="$CLAUDE_CODE_SESSION_ID" \
               --set-metadata agent_pane="$HERDR_PANE_ID"
herdr pane report-metadata "$HERDR_PANE_ID" --source herdr:claude --display-agent <id>

Your agent session is the id herdr reports for the agent in your pane, which for Claude Code is $CLAUDE_CODE_SESSION_ID. It is the join bdi trusts most, because it names you rather than your pane. bdi draws the bead against whichever pane herdr finds your session in, so the bead follows you when you are resumed in another pane, and it drops a pane another agent has taken over.

The pane id is the join for an agent herdr reports no session for. The display_agent is the fallback: where neither key was written, bdi reads the pane's display_agent, and when that is exactly a bead id in the pane's own project, it resolves to that bead. The bare id, nothing around it, or the fallback matches nothing.

agent_session and agent_pane are the default names for the keys. A project whose bdi config sets agent_session_key or pane_key under [join] uses that name instead, and it is the one to write.

One pane joins one bead

Where two beads name one pane, bdi awards the key's claim to neither. The refusal is reported as a conflict, and nothing errors. What the pane says about itself then stands alone: a display_agent naming exactly one of those beads keeps that bead's agent, and one naming nothing drops your pane among the unclaimed panes below the trees, reading exactly like an agent that never registered. Working on two beads at once, name your pane on one of them.

Clear the key when you stop

Clear the key whenever you stop working on the bead, whatever its status:

bd update <id> --unset-metadata agent_pane

Your pane id outlives you and is reassigned to whoever comes next in it. A bead still naming it then contests the pane with that agent's bead: the key is refused on both, and the join rests on what the pane says about itself. bd close takes no metadata flags, so the unset goes on bd update before it.

What bdi flags

Two rows are drawn as anomalies from the facts above alone.

• stale-pane: a bead is closed and a pane still joins to it. Clearing the key and the pane's display_agent ends it.
• stale-claim: a bead is in_progress and nothing has written to it for thirty days. bdi reads the bead's updated_at, and any bd update moves it: a status, a metadata key. The window is stale_claim_days under [anomalies].

Anything else goes in metadata

Whatever else you want visible on the row — a review link, a topic name, a waiting marker — goes in bead metadata under a key of your choosing. The reader draws it with a [[badges]] entry naming that key. [[badges]] has the shape.

Tell bdi you changed something

bdi polls, and a poll can be half a minute away. After a write, name the project on bdi's socket and it reads now: Telling bdi a project changed.