Agent Setup

Prerequisites

Before setting up agents, you need:

• The bd CLI installed and on PATH (Getting Started)
• At least one initialized workspace (bd init in your project directory)
• Beadbox running and connected to that workspace

Agent Identity

Each agent needs a CLAUDE.md file (or equivalent system prompt) that defines:

• What the agent owns (implementation, QA, operations)
• What the agent does not own (keeps agents from drifting into other roles)
• How to communicate (comment on beads, report to the coordinator)

Here is a minimal identity for an engineering agent:

## Identity
Engineer for MyProject. You implement features, fix bugs,
and write tests. You own implementation quality.

## Boundary with QA
QA validates your work independently. You provide QA with
executable verification steps. If your DONE comment doesn't
let QA verify without reading source code, it's incomplete.

The boundary section prevents the agent from doing QA's job. Without explicit boundaries, agents self-validate and skip independent review.

Essential Commands

These are the bd commands your agents use most:

bd create --title="Fix login bug" --type=bug --priority=2

bd show BEAD-ID

bd update BEAD-ID --claim --actor agent-name
bd update BEAD-ID --status in_progress

bd comments add BEAD-ID --author agent-name "PLAN: ..."
bd comments add BEAD-ID --author agent-name "DONE: ..."

bd list --status=open --assignee=agent-name

bd close BEAD-ID

All commands accept a --db flag to target a specific workspace database, useful when agents work across multiple projects.

The bd prime Command

The fastest way to teach a new agent the bd CLI:

bd prime

This outputs a context block designed for AI coding assistants. It covers the full command set, output formats, and common workflows. Paste it into your agent's system prompt or context window.

Run bd prime from inside your workspace directory to include workspace-specific context.

Agent Workflow

A typical agent workflow for a single bead:

1. Claim the bead
2. Comment a plan before coding
3. Implement the change
4. Run tests
5. Comment completion with verification steps
6. Push and update status to ready_for_qa

# Full workflow example
bd update proj-a1b2 --claim --actor eng1
bd comments add proj-a1b2 --author eng1 "PLAN: 1. Fix auth check 2. Add test"

# ... implement and test ...

bd comments add proj-a1b2 --author eng1 "DONE: Fixed auth. Commit: abc123"
git push
bd update proj-a1b2 --status ready_for_qa

The DONE comment should include verification steps that let another agent (or a human) confirm the work without reading source code.

Real-time Feedback

When an agent runs a bd command, Beadbox detects the database change and updates the UI within two seconds. No manual refresh needed.

This means you can watch your agents work in real time: see beads move from open to in_progress, watch plans appear as comments, and catch blockers as they surface.

For multi-agent setups, the Activity Dashboard shows which agent is working on what, where work is piling up in the pipeline, and what just happened across the fleet.