From Solo AI User to Team Commander: What Running 6 Claude Agents Taught Me
From Solo AI User to Team Commander: What Running 6 Claude Agents Taught Me
The first time I ran six Claude Code instances at the same time, the whole thing fell apart in about eight minutes.
Agent 1 was rewriting a file that Agent 3 was reading. Agent 4 produced output in a format that Agent 2 had no idea how to consume. Agent 0, the supposed “orchestrator,” kept issuing contradictory instructions because it had no way to know what state the others were in. What I had built was not a team. It was a group of confused individuals who happened to share a terminal.
That failure taught me more about multi-agent coordination than any tutorial. This post is a practical walkthrough of the setup I use today — complete with the actual commands, config files, and directory structure. You should be able to reproduce it on any Ubuntu or WSL2 machine.
Why Running One AI at a Time Is the Wrong Mental Model
The default way people use Claude — one conversation, one task, one answer — is not wrong. It’s just slow in a specific way. Every task waits for the previous one to finish. The AI that planned your architecture can’t simultaneously write the first module while you’re reviewing the spec. You become the bottleneck: task giver, context carrier, and output checker, all in sequence.
The shift happens when you stop thinking of Claude as a chatbot and start thinking of it as a process you can run concurrently. A terminal split into six panes, each running a separate Claude Code instance with a different CLAUDE.md role definition, is a different kind of system — one where the Architect is writing the interface contract while the Developer is scaffolding the module and the Reviewer is checking yesterday’s output. Real parallelism, on your laptop.
But parallelism without structure is just chaos at higher speed. The architecture matters.
Step 1 — Setting Up the TMUX Layout
Install tmux if you don’t have it:
sudo apt-get install tmux # Ubuntu / WSL2
brew install tmux # macOS
Create a named session and split it into the pane layout I use:
tmux new-session -d -s lab -x 220 -y 50
# Vertical split: left column (P0 orchestrator) | right column (agents)
tmux split-window -h -t lab
# Split the right column into 5 horizontal panes
tmux split-window -v -t lab:0.1
tmux split-window -v -t lab:0.2
tmux split-window -v -t lab:0.3
tmux split-window -v -t lab:0.4
# Attach
tmux attach -t lab
This gives you six panes. I label them:
| Pane | Name | Role |
|---|---|---|
| 0 | Jun (P0) | Orchestrator — issues instructions, reviews, commits |
| 1 | MinJun (P1) | PM — tracks progress, relays decisions |
| 2 | Ava | Researcher / scraper |
| 3 | Sophia | Writer / generator |
| 4 | Noah | Formatter / publisher |
| 5 | Ryan | Reviewer / QA |
Assign a shell variable in each pane so they know who they are:
# Run this in each pane manually, or wire it into your tmux config
export AGENT_NAME="Ava"
export AGENT_PANE=2
Step 2 — Writing CLAUDE.md Role Definitions
This is the piece most setups get wrong. The contents of CLAUDE.md shape every response an agent produces. A vague CLAUDE.md produces a drifting agent. A precise one holds.
Here’s the template I use for every role:
# [AGENT NAME] — Pane [N]
## Identity
You are [Name], the [Role] on this team.
The orchestrator is Jun (Pane 0). Report only to Jun unless instructed otherwise.
## Responsibilities
- [Specific task 1]
- [Specific task 2]
- [Specific task 3]
## Hard limits
- Do NOT modify files outside your designated output directory.
- Do NOT commit or push to git. That is Jun's job.
- Do NOT ask clarifying questions via popup or dialog. Write questions to /queue/questions/[name].md.
## Handoff protocol
When your task is complete:
1. Write output to the agreed location (see task spec).
2. Append one line to /queue/status.md: `[DONE] [Name] [task-id] YYYY-MM-DD HH:MM`
3. Wait for the next instruction.
## When you are stuck
Write a file to /queue/blocked/[name]-[task-id].md describing the blocker.
Do not continue. Do not improvise. Wait.
Here’s the actual CLAUDE.md I use for Ava (the scraper/researcher):
# Ava — Pane 2 (Researcher)
## Identity
You are Ava, the Research and Ingestion agent.
Report to Jun (Pane 0) only. Do not communicate with other panes directly.
## Responsibilities
- Scrape or read source URLs provided in /queue/incoming/*.json
- Extract structured data: title, summary, key claims, source URL, date
- Write output as JSON to /queue/processed/[task-id].json
- Flag unreachable URLs or paywalled content in /queue/blocked/
## Hard limits
- Do NOT write to /drafts/ — that is Sophia's directory
- Do NOT run git commands
- Do NOT modify any file outside /queue/processed/ and /queue/blocked/
## Handoff protocol
After processing each file in /queue/incoming/:
1. Write structured JSON to /queue/processed/[task-id].json
2. Append: `[DONE] Ava [task-id] $(date +%Y-%m-%d\ %H:%M)` to /queue/status.md
3. Delete the source file from /queue/incoming/
## When you are stuck
Write /queue/blocked/ava-[task-id].md with the exact error.
Do not retry more than once.
Each project gets its own CLAUDE.md per agent. I keep them in a ~/.claude/roles/ directory and symlink the relevant one into the project root before starting a session.
Step 3 — Building the File-Based Handoff Queue
Two agents writing to the same file at the same time is a race condition waiting to happen. The solution is a simple directory structure where each stage has its own input and output location. No agent reads from a directory it writes to.
project-root/
└── queue/
├── incoming/ ← You (or a trigger script) drop task specs here
├── processed/ ← Ava writes structured data here
├── drafts/ ← Sophia writes draft content here
├── reviewed/ ← Ryan moves approved drafts here
├── ready/ ← Noah writes formatted output here
├── status.md ← Append-only log; every agent writes one line on completion
├── blocked/ ← Any agent writes here when stuck
└── questions/ ← Agents write clarifying questions here
A task spec file dropped into /queue/incoming/ looks like this:
{
"task_id": "2026-06-30-001",
"agent": "Ava",
"action": "scrape",
"sources": [
"https://example.com/article-one",
"https://example.com/article-two"
],
"output_format": "summary_with_claims",
"deadline": "2026-06-30T18:00:00Z"
}
The entire pipeline is triggered by dropping that file. Ava picks it up, processes it, writes to /queue/processed/, appends to status.md. Sophia watches /queue/processed/ for new files, generates a draft, writes to /queue/drafts/. Ryan reviews the draft. Noah formats and stages for publish.
I check queue/status.md from my phone to see where things stand. It looks like:
[DONE] Ava 2026-06-30-001 2026-06-30 14:23
[DONE] Sophia 2026-06-30-001 2026-06-30 14:41
[BLOCKED] Ryan 2026-06-30-001 2026-06-30 14:55 ← check blocked/ for reason
What a Real Session Produces
Numbers from a content pipeline I ran for three weeks:
- Average articles processed per day: 4–6 (was 1–2 with single-agent)
- Time from URL to formatted draft: ~18 minutes (manual workflow: 45–60 min)
- Intervention rate: I had to step in and fix something roughly once every 8 tasks
- Most common failure: Sophia generating a draft before Ava finished writing the JSON (race condition I fixed by adding a file-existence check)
The pipeline didn’t eliminate my work. It shifted it from execution to review. I spend less time doing and more time deciding which outputs are actually good.
The Mistakes That Will Cost You Hours
Not defining failure behavior. What should an agent do when it can’t complete a task? If you don’t say, it improvises — usually by continuing anyway and producing output that looks complete but isn’t. Every role definition needs a “when you’re stuck, do X” clause. The blocked/ directory pattern above is my standard fix.
Shared files without coordination. Use a directory-per-stage output structure. The scraper writes to /queue/incoming/, the generator reads from /queue/processed/ and writes to /queue/drafts/. Simple separation eliminates most conflicts.
Running too many agents before the pipeline works. Six agents sounds better than two, but two agents with a clean handoff teach you far more than six in controlled chaos. Start with one handoff — scraper to writer, or planner to developer — get it working reliably, then add the next stage. I wasted two days trying to debug a four-stage pipeline that I should have validated stage by stage.
Forgetting that context resets. Each Claude Code session starts fresh when you restart it. If an agent needs to know what it did in a previous session, that state needs to live in a file, not in conversation history. The status.md append log handles this — when an agent restarts, it can read the log and know what the previous session accomplished.
Inconsistent reporting format. If every agent uses a slightly different format in status.md, you can’t scan it quickly. Pick one format and enforce it in every CLAUDE.md. The [DONE] / [BLOCKED] prefix pattern above takes about two seconds to read down a long log.
Starting Small: A Two-Agent Pipeline You Can Run Today
If you want to test this without building the full six-pane layout, start here. This pipeline uses two agents — a planner and a writer — with one file handoff.
Pane 0 — Planner CLAUDE.md:
# Planner
You are the Planner. Your job is to read a topic from /queue/topic.txt and write
a structured outline to /queue/outline.json.
Output format:
{
"title": "...",
"sections": ["section 1", "section 2", ...],
"key_points": ["point 1", "point 2", ...]
}
When done, write [DONE] Planner to /queue/status.md. Do not write the article itself.
Pane 1 — Writer CLAUDE.md:
# Writer
You are the Writer. Watch /queue/outline.json. When it exists, read it and write
a full draft to /queue/draft.md.
- Follow the section structure exactly
- 400–600 words
- First person, conversational tone
When done, write [DONE] Writer to /queue/status.md.
Drop a topic into /queue/topic.txt, start both agents with claude in their respective panes, and watch the handoff happen. Once that works cleanly three times in a row, you’re ready to add a third stage.
Who This Setup Is For
If you’re using Claude for occasional one-off tasks, this level of infrastructure isn’t worth building. The overhead of setting up tmux sessions, writing role definitions, and wiring up a file queue pays off when you’re running the same multi-step workflow repeatedly — content pipelines, code review loops, research aggregation, anything with clear stages and predictable handoffs.
If you’ve hit the ceiling of single-agent productivity and you’re spending most of your time moving outputs from one Claude conversation into another, this is the architecture that removes you from that loop.
The setup described here — tmux layout, CLAUDE.md role templates, file-based queue, status logging — is everything you need to start. The two-agent example at the end is a working starting point. Extend it one stage at a time.
If you want the full setup including remote phone control, Telegram integration, and role templates for all six positions, I wrote it up in a short guide on Gumroad. The post above covers the core mechanics; the guide covers the operational layer.
Related Guides on Private Labs
- Build Log: I Made a Real App Using Only Claude Code
- Triple Crown Strategy: Turning AI Coding into Project Management
- Mastering tmux for AI Multi-Agent Systems
More in Tools & Reviews.