Two weeks ago I said I'd write up how to actually start an agent team. I am a man of my word. Fair warning: the setup is the easy bit.
The starting point is simpler than you'd think. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 as an environment variable. That's the door.
From there, you write one markdown file - I called mine agent-roles.md - with a section for each agent type. Planner, Builder, Validator. Each section is basically a job description: trigger condition, which skills it can reach for, what it can and can't touch. Nothing fancy.
Then to actually run one, you do this:
claude --worktree feat/issue-42 -p "You are the Builder agent. Read agent-roles.md. Your ticket is #42."
The --worktree flag spins up an isolated git branch and working directory for that agent - so if you're running multiple in parallel, they're not all writing to the same place. Without it, they'd be stepping on each other immediately.
And then it just runs... immediately. I wasn't expecting it to work that quickly, to be honest, and there was a fairly embarrassing amount of excitement at that point.
So I made the classic mistake. The bash script I'd written was just a loop: poll Notion every 60 seconds, find Ready tickets, fire off that command for each one. Simple enough. Set it going, went to bed, let it crack on.
Came back to spaghetti, it was an absolute shambles.
Tickets in completely the wrong states, duplicate PRs, random failures with no context about why or when, agents fighting over the same tickets doing the same work twice - and I had no visibility into any of it. Just a bash script and a vague hope. No way to see what had actually happened, no way to replay it, nothing. Just the aftermath. I pretty much knew this would happen, but my morbid curiosity got the better of me.
That's why I started building the control room, and I've already written about that bit.
The thing I'd tell someone starting today isn't "build a control room first" - it's smaller than that. Get one agent running really well before you try to run a team. Write a proper role file. Specific job, specific tools, specific guardrails. Run it manually on a couple of tickets and watch what it does. Make sure it does what you actually want it to do. Then add another.
One agent with good instructions is useful. Four agents with sloppy instructions is just chaos with better branding.
Where are you at with agent teams - running them one at a time still, or have you already gone full team and lived to tell the tale?