I was about an hour into what felt like a genuinely productive session. Three Claude Code instances running, each working on a different part of the codebase. It felt like having a small team.
Then I checked the git diff.
Two of the agents had been editing auth.js at the same time. One of them finished first. The other one saved over it. Two hours of work from agent one — gone. No warning, no conflict marker, nothing. Just silently overwritten.
That's the thing nobody tells you about running parallel agents. Claude Code is incredible. Running multiple instances is even better. But they have absolutely no idea what each other is doing. There's no shared brain, no "hey, I'm working on that file" signal. Each one just does its thing and assumes it has the whole codebase to itself.
So I built Switchman to fix it. This is how to use it.
Before you start
You'll need:
- Node.js 22.5+
- Git 2.5+
- Claude Code
Install Switchman:
npm install -g switchman-dev
The idea in plain English
Switchman does three things that Claude Code doesn't do on its own:
It gives your agents a shared task list. You add the work upfront, and each agent picks up one task at a time. No two agents ever get the same job.
It adds file locking. Before an agent touches a file, it checks in. If another agent already has that file, it gets told immediately and picks something else instead. The collision never happens.
It connects to Claude Code automatically via MCP. You don't write any coordination logic. You just open Claude Code in each workspace and it handles the rest.
Step 1 — Create your agent workspaces
The first thing you need is a separate workspace for each agent — its own copy of the repo, on its own branch. If two agents are working in the same folder, they'll step on each other no matter what.
Run this once from your project:
cd my-project
switchman setup --agents 3
That's it. Switchman creates three isolated workspaces and sets everything up:
✓ Switchman ready — 3 agent workspaces created
✓ /Users/you/my-project-agent1
branch: switchman/agent1
✓ /Users/you/my-project-agent2
branch: switchman/agent2
✓ /Users/you/my-project-agent3
branch: switchman/agent3
Each workspace is on its own branch. Whatever one agent does stays completely separate until you decide to merge it.
Step 2 — Tell Claude Code about Switchman
Open ~/.claude/claude_desktop_config.json and add this:
{
"mcpServers": {
"switchman": {
"command": "switchman-mcp",
"args": []
}
}
}
Restart Claude Code. Your agents can now use Switchman's coordination tools automatically — they don't need to be told how, that comes in the next step.
Step 3 — Add CLAUDE.md to your repo root
This is the file that tells your agents what to do. Without it, they won't know to coordinate.
curl -O https://raw.githubusercontent.com/switchman-dev/switchman/main/CLAUDE.md
It instructs each agent to check in with Switchman at the start of every session, claim files before editing them, and release everything when they're done. You write this once and never think about it again.
Step 4 — Add your tasks
Think about what you want to get done and break it into separate chunks. The more independent each task is, the better parallel agents work.
switchman task add "Implement OAuth login flow" --priority 9
switchman task add "Add rate limiting to API routes" --priority 7
switchman task add "Write tests for auth middleware" --priority 6
switchman task add "Update API documentation" --priority 3
Higher priority tasks get picked up first. Each agent gets one task at a time — when it finishes, it picks up the next one.
Step 5 — Open Claude Code in each workspace
Open a separate Claude Code window in each of the three folders that switchman setup created. Each agent will pick up a task, lock the files it needs, do the work, and release everything when it's done.
You just watch it happen.
Here's what it looks like when two agents try to grab the same file:
# Agent 1 locks auth.js
✓ Claimed src/middleware/auth.js
# Agent 2 tries to claim the same file
⚠ Conflict — auth.js is locked by agent1
# Agent 2 picks different files and carries on
✓ Claimed src/middleware/validate.js
✓ Claimed src/routes/tasks.js
Agent 2 doesn't stop or ask you what to do. It just adapts and keeps going. Both agents make progress and nothing gets overwritten.
Checking in
At any point you can see exactly what's happening:
switchman status
Tasks:
Pending 2
In Progress 3
Done 1
Active Tasks:
agent1 → "Implement OAuth login flow"
agent2 → "Add rate limiting to API routes"
agent3 → "Write tests for auth middleware"
Active File Claims:
agent1: src/auth/login.js, src/auth/token.js
agent2: src/middleware/rate-limit.js, src/server.js
agent3: tests/auth.test.js, tests/middleware.test.js
Three agents, all working, no overlap anywhere.
Before you merge
When everything's done, run this before merging any branches:
switchman scan
It checks for any file overlaps or branch conflicts and tells you exactly what to fix before you touch anything. Much better than finding out at merge time.
Does it actually work?
The first time I ran three agents through a real feature with Switchman, I genuinely just went and made a coffee. Came back twenty minutes later, all three were done, no conflicts, nothing to untangle. That hadn't happened before.
It won't solve everything. If your tasks aren't well scoped, agents will still get stuck. And if you're merging a lot of branches, you'll still need to think about that. But the silent overwrite problem — the one that cost me two hours that afternoon — that's gone.
Switchman is free and open source.
Install: npm install -g switchman-dev
GitHub: github.com/switchman-dev/switchman
Site: switchman.dev
SOCIAL SHARE CARD GENERATOR