[ FILE #001 · DOSSIER ]
BUREAU //a multi-agent shepherd for Claude Code
Linear ticket in. Merged PR out. You mostly watch.
[ FIELD REPORT · 03:00 ]
3AM. A DRAWER GLOWS.
No human triages the ticket. The bureau does. Spec-kit writes the spec. Agents implement. QA writes the missing tests. Code review flags the security bug I would have shipped. Merge when CI is green. I mostly watch.
Operations are not support for the product. They are the product.
Four merged PRs while I sleep is a good night. A private Rust CLI, a few months in.
Below: how it works, what it refuses to do, and how you install it on your own repo in the next twenty minutes.
[ FILE #002 · PIPELINE ]
SEVEN STAGES. ONE STATE MACHINE. LINEAR IS THE MEMORY.
Every ticket walks a fixed path through Linear states. Each stage is a bash script running Claude in a dedicated tmux window. State lives in Linear comments and git branches, nowhere else.
| Stage | Input state | Agent | Output artifact | → state |
|---|---|---|---|---|
| SPEC | Triage | spec | spec.md · plan.md · tasks.md | Spec Review |
| SPEC REVIEW | Spec Review | spec-review | spec-digest comment | Build |
| [DESIGN] | Design | ux | design notes | Copy / Build |
| [COPY] | Copy | copy | microcopy | Build |
| BUILD | Build | implement | feature branch · commits | QA / Review |
| [QA] | QA | qa | missing tests · green suite | Build Review |
| BUILD REVIEW | Build Review | code-review | review verdict · needs-human? | Merge |
| [MERGE] | Merge | merge | squash-merge into main | Done |
Dashed stages are opt-in — toggled per repo in .bureau.json.
[ TWO OPERATING MODES ]
./scripts/start-bureau-v2.shLaunches the whole tmux mesh. Queue-loops poll Linear every 30 min. Cron-friendly../scripts/shepherd.sh --no-tmux EXP-123Runs one ticket end-to-end, sequentially, in the current shell. For when you want to watch.[ FILE #003 · INVARIANTS ]
SIX RULES THE MAINTAINER REFUSES TO BEND.
These are the invariants in CLAUDE.md. They exist because the pipeline runs in cron, which means every bug it can silently swallow, it will.
[ RULE #01 · CLAUDE NEVER TOUCHES LINEAR ]
Claude never does Linear CRUD. Every state move goes through the helpers in bureau-config.sh.
Headless Claude cannot refresh OAuth tokens, so the model is never handed the keys.
[ RULE #02 · BRANCHES RESOLVE VIA MARKER COMMENTS ]
The pipeline finds a ticket's branch through a marker comment, not Linear's branchName field.
Linear's branchName does not match speckit's 001-* convention.
[ RULE #03 · PRECONDITIONS BEFORE STATE MUTATIONS ]
Every stage checks its preconditions before it moves state. EXIT traps re-route crashed issues back to Triage.
A stage that dies after moving state strands the ticket in a place nothing picks up.
[ RULE #04 · EXIT CODES ARE A PROTOCOL ]
Each stage exits on a documented code. Telegram alerts throttle by (issue, class) per hour.
An unthrottled cron loop turns one stuck ticket into a hundred alerts by morning.
[ RULE #05 · WORKTREES RESET BETWEEN PICKS ]
clean -fdx and reset --hard after every stage. No state leaks from one ticket into the next.
State bleeding between two tickets is the worst kind of bug to reproduce.
[ RULE #06 · THE MERGE GATE IS STRICT ]
CI-green and base-current are checked independently of GitHub's async mergeStateStatus.
Four PRs merged with red CI is what wrote this rule.
“Main goes red and nobody notices until a developer pulls.”
— the incident that wrote rule #06.
[ FILE #004 · TOKEN LEDGER ]
~80% FEWER TOKENS PER TICK. THREE FLAGS. INDEPENDENT.
[ /goal ]
Haiku evaluates goal completion after every turn. Bash is not counting commits, so there is no stuck-detector puzzle to solve.
[ caveman ]
Terse prompt discipline that keeps the model out of essay mode.
[ Headroom ]
Context compression. Long sessions do not blow the window.
Each flag is a single JSON edit in .bureau.json. Independent, flippable, one command to roll back. The ~80% figure came from real pipeline ticks against the private Rust CLI over about ten weeks. Your mileage depends on ticket complexity.
[ FIELD REPORT · THE INTENTIONAL FLAW ]
THE BUREAU STOPS ON THINGS IT SHOULDN’T FINISH.
Every ticket has a needs-human label the pipeline is allowed to apply. When code review requests architectural changes, when QA cannot fix the test itself, when the merge gate refuses three times in a row — the ticket parks and a Telegram alert fires. This is not failure. It is the design.
- Issue
- EXP-491
- Pipeline
- code-review
- Exit
- 13
- Reason
- needs-human
“That’s how I know when to open my laptop.”
[ FILE #005 · SCOPE ]
THE BUREAU IS NOT:
- —A hosted SaaS. No cloud backend. No sign-up. All local, or your own CI.
- —A Copilot replacement. No inline completions. This is batch autonomous work, not interactive pairing.
- —For greenfield. It needs a repo, a Linear workspace, and enough acceptance-criteria discipline that specs are writable.
- —Multi-repo out of the box. One .bureau.json per repo. Parallel pipelines on the same Linear project race.
- —A replacement for branch protection. It complements branch protection. It never substitutes for required reviews or status checks.
- —A test framework. It runs your tests and writes new ones where coverage is missing. It provides no test infrastructure.
- —Lock-in. JSON config, bash scripts, Linear API, GitHub API. Fork it, migrate off it — the config is text.
[ FILE #006 · INSTALL ]
THREE COMMANDS TO YOUR FIRST PIPELINE TICK.
Requires: git · tmux · jq · curl · Claude Code CLI · Linear account · GitHub CLI.
git clone https://github.com/KaiaK808/bureau.git ~/.claude/skills/bureau-initterminal · installs the skill (once per machine)
/mcpin Claude Code · then authenticate linear-server (once per machine)
cd path/to/your/repothen run /bureau-init in Claude Code — the 8-phase interactive walk-through in your repo
Then, to run continuously:
./scripts/start-bureau-v2.shstarts the tmux mesh
tmux attach -t bureau-v2-$(basename "$PWD")attach to watch it work
[ TYPICAL FIRST MERGE ]
- spec-only smoke test — 10–15 min
- end-to-end (spec → PR → merge) — 30–60 min
- varies with ticket complexity
[ FILE #007 · WHAT WE’VE SHIPPED ]
THE PROOF, SUCH AS IT IS.
| RUN AGAINST | brainhuggers-cli — a private Rust CLI (internal Claude Code fork) |
|---|---|
| PERIOD | April → June 2026 · ~10 weeks of continuous cron |
| AGENTS RUNNING | spec · spec-review · ux · copy · implement · qa · code-review · merge |
| OUTCOMES | 96 PRs merged autonomously~15 needs-human parks (~1 in 7 tickets)0 silent merges into red main |
| PUBLIC SINCE | 2026-07-03 |
Counts from the merged-PR history on brainhuggers-cli · April → June 2026.
Bureau shipped as open source last week. No one else has run it in production yet. You might be the first. That is what the SECURITY.md, the OPERATOR-CHEATSHEET, and the needs-human contract exist for.
[ FILE #008 · CLOSE ]
BUREAU IS BUILT BY KAI EBERT AT BRAINHUGGERS.
20 years shipping code inside agencies (Fork, JvM, Valtech). First open-source repo.
Bureau is one piece of a larger studio bet: the operations are not support for the product. They are the product.
Feedback welcome. Especially on the merge gate and the /goal loop.
Delegation, aber ernst gemeint.