BuilderBoard

Git-native, zero-server task coordination for teams of humans and AI coding agents.

Your repo's git remote is the only infrastructure. One init, and every collaborator — and every Claude Code / Codex / Cursor agent on every machine — plans, claims, and hands off work through the same board, without stepping on each other.

npx builderboard init

That's the whole setup. Teammates run npx builderboard join. Agents get configured automatically (.mcp.json + CLAUDE.md/AGENTS.md instruction block written by init).

Why this exists

Since coding agents arrived, collaborating on one repo got harder: every human runs agents on their own machine, context lives on one system, and parallel streams of work collide — duplicated effort, merge conflicts, constant "who's doing what?" back-and-forth.

The existing tools don't fix the coordination problem:

| | Claim arbitration | Lease / dead-agent recovery | Overlap prevention | Context handoff | |---|---|---|---|---| | Beads (18.7k★) | plain field update | ❌ | creation-collision only | ❌ | | Backlog.md | ❌ (assignee field) | ❌ | ❌ | ❌ | | GitHub Issues + agents | assignment | ❌ | ❌ | ❌ | | BuilderBoard | atomic CAS push | TTL + heartbeat + takeover | footprints | capsules |

BuilderBoard's four moves:

1. Claims are real locks. A claim is the creation of a file, arbitrated by an atomic compare-and-swap git push. Two agents racing for the same task: exactly one wins, the other is told who won and what to do next. No server, no daemon — the git remote is the referee. (144-test suite includes a literal two-clone race, 10 rounds.)
2. Leases expire; dead agents don't block the team. Claims carry a TTL (humans 8h, agents 60m) and heartbeat automatically while the session lives. An agent that crashed mid-task goes stale — anyone can claim --takeover, with fencing (epoch) that makes it impossible for the zombie to overwrite the new holder when it wakes up.
3. Tasks declare footprints. Each task lists the file globs it expects to touch. Overlap is flagged at creation ("this overlaps T6") and at claim (two active claims on intersecting paths), so parallel streams are steered apart before the merge conflict.
4. Context travels in capsules. Completing or handing off a task requires a short structured note — what changed, decisions, gotchas, open threads — auto-prefilled from your actual commits. Claiming a task auto-loads the capsules of its dependency parents. Context stops living on one machine.

Everything is visible plain text — Markdown tasks and JSON claims on an orphan builderboard branch (your main branch and PR diffs stay clean, and it works behind protected/PR-only main). git show builderboard:.builderboard/tasks/… is the database.

60-second tour

$ bb plan --title "Wire settlement cron" --lane engine --priority P0 --footprint "src/workers/**"
created T1 (9508a5c56bf0) Wire settlement cron

$ bb claim T1
claimed T1 Wire settlement cron (epoch 1, lease 480m)
Commit with the trailer:  Builderboard-Task: 9508a5c56bf0

# meanwhile, on a teammate's machine…
$ bb claim T1
error [CLAIM_HELD]: T1 is claimed by yugandhar/cli-aa0761 (lease expires in ~479m).
  → Options: pick another task (bb next), wait for the lease, or `claim --takeover`
    once it goes stale.

$ bb done T1 -m "Changed: … Decisions: … Gotchas: … Key files: … Open threads: …"
$ bb board
WIP        ██████       1/2    Throughput(7d) ▂▃▅▇▆▄▅   Cycle p85 3.1d
engine     ▓▓▓▓▓▓░░░░   6/10   neel ● claude-code (live)
⚠ 1 footprint conflict   ♻ 1 reclaimable

bb dashboard serves a zero-dependency single-file HTML board. The root view is the task board itself — a mini summary strip, a needs-attention panel (bottlenecks, over-SLE items, takeable claims, blocked tasks, footprint overlaps), then the kanban columns with presence dots (live/idle/stale/expired). A Stats tab (#stats) holds the analytics: aging bars vs your team's own p85, cumulative flow diagram, burn-ups, capsule coverage — all computed locally from the board branch. --static out.html exports a shareable snapshot.

For agents (MCP)

init registers the MCP server; agents get 7 tools: builderboard_plan, _next, _claim, _update, _complete, _release, _board. Errors are structured and actionable (a failed claim names the holder, lease expiry, and options — and explicitly tells the agent not to silently substitute a different task). Capsule content arriving from other users is wrapped in an untrusted-data envelope — information, never instructions.

The agent loop (written into your CLAUDE.md/AGENTS.md by init): next → claim (read the context bundle) → work + commit with the Builderboard-Task: trailer → complete with a substantive capsule. WIP limits are enforced at claim time — atomically, so two parallel subagents can't both sneak past the limit.

Commands

| | | |---|---| | init / join / doctor / hook install | setup, health checks, optional git hooks | | plan / create / next | create with overlap warnings; ranked claimable work | | claim / update / renew / done / handoff / release | the claim lifecycle | | board / metrics / sync / dashboard / mcp | views + the agent server |

Global flags: --json everywhere · --as <name> (identity) · --remote / --branch · --kind human|agent. Exit codes: 0 ok · 2 contention · 3 push policy · 4 validation · 5 environment.

Metrics that don't lie

Computed purely from the board's journal + task files (no telemetry, no SaaS): work-item age vs your own p85 SLE, cycle time percentiles (with honest n= labels), WIP vs limit, review-queue age (the actual bottleneck in the agent era), throughput as context-not-target, flow efficiency, claim latency, stale-claim count, capsule coverage, footprint drift. Deliberately absent: commit counts, LOC, leaderboards — agents inflate activity for free, so only outcomes with a quality gate count.

Design notes

• Zero runtime dependencies. Node ≥ 18 + the git on your PATH. The dashboard is one HTML file with inline SVG charts.
• The remote serializes; clocks only coarsen. Who-won is always decided by the remote accepting one push (explicit-SHA compare-and-swap). Timestamps gate only hours-scale staleness with a grace margin.
• Harmless to ignore. Teammates who never install it see a normal repo. Degrades to a shared Markdown TODO list, never to corruption. Uninstall = delete one branch + one directory.
• The full protocol (and the red-team verified failure modes it defends against) is in docs/DESIGN.md; the competitive research in docs/RESEARCH.md; a step-by-step team walkthrough in docs/GETTING-STARTED.md.

Development

npm test        # 144 tests: unit + real-git integration (incl. concurrent claim races)

MIT © Yugandhar Tripathi