Run a team of AI coding agents without chaos: our Claude Code playbook

Why does a multi-agent Claude Code workflow turn into chaos?

You did nothing wrong. People keep asking about this, because the pile of half-finished projects is a common place to end up.

The pattern is familiar. Code gets written, but it never reaches a live address. Nothing checks it afterwards. Broken things sit unnoticed. You may have tried one big "do everything" agent, and it either did too much or too little.

Our fix was not a smarter agent. It was a smaller job for each one, plus a board they all read.

What a good solution does

It gives every agent one sentence of purpose. A subagent in Claude Code is a markdown file with YAML frontmatter, so a job description is easy to write down1. Each subagent runs in its own context window with its own system prompt, tool access and permissions1.

It also limits what each agent can touch. The docs list "enforce constraints by limiting which tools a subagent can use" as a reason to use subagents1.

And it keeps a single to-do board, so no agent has to remember what the others did. That board is where the calm comes from.

What you need before you start

• Claude Code, installed from the official page (see /start-here/ for how).
• A GitHub account and the gh command-line tool, which signs in with gh auth login4.
• A small database, such as a hosted free tier.
• A place to put finished work, such as a static host.
• A plain, empty folder to begin in, and a private repository for it.

Set aside an afternoon for the first pass. We will not promise more than that, because your projects differ from ours.

The playbook

Here is the order we would follow again. Your AI does these with you, one at a time, and asks before it runs anything.

1. 1

   Make a safe place first.

   Commit what you have. Then create a private repository from your local folder with gh, which can do that when you give it a name and --private, plus --source for the local folder5.

2. 2

   Build the board.

   Make three things in your small database: a builds table (a key, a stage, an owner agent, a next action, a blocked reason, a repo address, a live address and a health result), an event log, and a queue view that sorts by priority and puts blocked rows last.

3. 3

   Write one agent file per role.

   Put each in your agents folder, in .claude/agents/ for one project1. Give each a one-sentence job, an input rule (it receives exactly one build key), a numbered procedure and a short list of hard rules.

4. 4

   Set tools per agent.

   Give the planner read and write on the database only. Give the deployer a shell and git. Give nobody payment or customer-messaging tools. Check first what each agent quietly relied on, so you do not remove something it needs.

5. 5

   Limit work in progress to one.

   The planner dispatches no new build while one is mid-flight.

6. psst, this step matters

   6

   Split "deployed" from "verified".

   The deployer may set a build to live. Only a different agent, or you, may set it to shipped.

7. 7

   Write the sweeper's runbook.

   Make it a separate markdown file the sweeper reads first, listing each check and the exact command for it. Make tickets repeatable: give each finding a fingerprint, so a rerun updates a ticket instead of making a copy.

8. 8

   Schedule the sweeper

   twice a day, with a hard time cap on every run.

9. 9

   Write git rules before anything pushes.

   See the next section for ours.

10. 10

    Share the settings.

    Commit .claude/settings.json so permissions and hooks travel with the project3. Permission rules (allow, ask and deny) are covered on the same docs site3.

What we got wrong the first time

We built this, we run it, and it taught us several things the slow way.

We scoped new work while something sat mid-deploy. That was the founding failure, and the one-build limit exists to stop it.

Most of our agent files had no tools line. An agent that omits the line inherits every connected tool server. That meant a routine agent could reach powerful keys. Adding the line is the cheapest safety win we found.

A port check lied to us. A local tunnel answered while the far end was dead. We switched to a real web request through the tunnel. An answer that says "sign in first" counts as healthy. A timeout is the finding.

Silence fooled us more than errors did. One connector reported "completed" for hours while a folder was empty. A queue consumer exited cleanly on an empty queue for weeks. Watching for errors cannot see that, so a liveness watcher compares what a pipeline produced with what we expect. It is still a draft, and we infer the expected rates rather than declare them.

Our scheduler skipped jobs. On a Mac, jobs set for a time the machine was off did not run later, and every job looked fine because none had started. A sweep designed to be short once ran for many hours, and the next scheduled sweep silently never started. So judge jobs by how fresh their output is, and give every run a time cap. Add a second health probe after a delay before you close a ticket. Why? Our sweeper once called a tunnel fixed after a single good probe. It was dead again within the hour.

Logins expired quietly. Several scheduled runs in a row died at a login wall. We now write a marker file and send a notification the moment a headless run hits one.

Parallel worktrees started from a stale main branch. Whoever pushed last undid the others. The cure is to fetch before building, and to use a hook that refuses to end a session while commits are unpushed. Hooks are user-defined commands that run at set points, such as when Claude finishes responding2.

Our git sweep found around a hundred commits that never left the laptop. So now the sweeper pushes only non-default or local-only branches, as plain fast-forwards. A default branch in a repo with automated checks counts as a deploy, so a person decides. Diverged repos and missing remotes are a person's call too. It never force-pushes, merges or deletes a branch.

What it costs to run

As of November 2026, agent runs use your normal Claude plan or API usage. The sweeper adds two short runs a day. The database and static hosting can sit on free tiers. We do not know the exact spend, so we will not guess one.

Keep it safe

• Agents act with your credentials. Give each the minimum tools, and keep deploys, money and customer messages behind a human gate.
• Never let an agent write a secret to a file or a log. Use names of environment variables only, and keep the values in the platform.
• A sweeper that can push or fix things needs written guardrails. Keep personal and financial repos local only, always.
• Hooks can block a tool call before it runs2. That makes them a good place for a rule such as "refuse a push to the default branch".
• Approve the first production release yourself.