Introducing Bureau MCP

Oct 7, 2025

My agentic workflow involves subagents reading and writing report files, in a directory structure like this:

_tasks/
├── 2025-10-01-implement-feature/
│   ├── 001-user-request.md
│   ├── 002-plan.md
│   ├── 003-implementation.md
│   └── 004-tests.md
├── 2025-10-01b-fix-bug/
│   ├── 001-bug-report.md
│   └── 002-fix.md
└── 2025-10-02-refactor/
    ├── 001-analysis.md
    └── 002-plan.md

Unfortunately, Claude struggles to maintain consistent file numbering and folder organization when managing multi-step tasks.

Agents would often:

This happened so frequently that it was pretty damn annoying.

So I’ve built a tiny MCP server to help with it, bureau-mcp.

The server stores reports under _tasks. It (1) maintains which task is current (via _tasks/current symlink), (2) lists all report files for the agent to see (because they sometimes do ls | head -50 and miss later files on long tasks), and, most importantly, (3) tells the agent which report file to write to.

Install it via:

claude mcp add bureau --scope user -- npx -y bureau-mcp

then add it to your agentic instructions by asking Claude to:

/hr Update CLAUDE.md and all agents to use bureau MCP server instead of finding tasks and report files themselves.

Rules for agents:
1. When agent starts, call current_task. Planning and review agents (Don, Joel, Linus) read all reports. Implementation agents only read the latest plans and subsequent implementation reports.
2. When agent is finishing, call start_new_report_file and write the report to that file. Use short suffix representing the agent and its outcome ('don-plan', 'joel-plan', 'linus-plan-review', etc)
3. The first agent after a user request does start_new_report_file with a suffix of 'user-request', 'user-revision' or 'user-bug-report', 'user-complaint', etc, and writes out the user's message in there.
4. /do should call start_new_task. (Or, if user is asking to continue a certain task that's not current, /do and /rev can call switch_task.)
5. Agents only write files to report dir via start_new_report_file, never under any other names. Agents never list report directories, they always rely on what current_task returns.

(if you don’t have /hr command, well first you should, and second you can just skip it and ask Claude natively.)

Done and done. No more reporting woes observed. Latest agent definitions and commands are in andreyvit/claude-code-setup.

FAQ

Have you seen claude-task-master?

🤮.

I.e. it’s a weird project that seems to be solving the kinds of problems that real codebases don’t have, and doesn’t solve the problems that actually arise. And it is horribly overengineered to boot.

Do your agents really work for so long as to require triple-digit report files?

Yes, some longer tasks with a bunch of revisions get over a hundred rounds.

Do you really run agents unattended for hours?

For hours, yes. Unattended, no. I check back periodically and, if they’re doing shit, give them a /rev command with instructions.

A rule of thumb is to check back maybe 30 minutes after launching a task, and every hour after that. (I hope newer models will shrink these timelines.)

Your workflow must be horribly inefficient if it runs slower than a human

It is horribly inefficient, but that compute comes cheaply so far.

Like what you see?

Get these posts delivered to your inbox. Not every week, no; only when I have something useful to say.

Here's where I'm supposed to promise not to spam you. Seriously, does that even make any sense? Has it ever? Sometimes the way the world works is just bizarre. So lemme say, unsubscribing will be a breeze when you're finally fed up with me.

I want this to be a community, not just a newsletter, too, so you're verrrry welcome to reply to these emails.