Docs / Claude Code setup

Claude Code setup

Claude Code has native Switchman integration via MCP, so agents can coordinate automatically instead of relying on shell rituals or hand-managed work splits.

ℹ
Prerequisites: Complete Getting started first. The fastest path is switchman start "Your goal", but the manual switchman setup --agents N flow still works too.

1. Create your agent workspaces

cd my-project
switchman setup --agents 5
switchman verify-setup

This creates isolated workspaces, the shared Switchman database, and project-local .mcp.json files so Claude Code can discover Switchman automatically.

2. Optional global fallback

If you prefer a global fallback, add this to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "switchman": {
      "command": "switchman-mcp",
      "args": []
    }
  }
}

Project-local config is still the preferred path because it travels with the repo and generated workspaces.

3. Generate a repo-aware CLAUDE.md

switchman claude refresh

This generates a repo-aware guide in the repo root so agents know which Switchman tools and repo conventions to follow. Keep it in the repo root and do not have agents talk to .switchman/switchman.db directly.

4. Claude Code tools

Once the local MCP config is in place, Claude Code can use tools like:

ToolWhat it does
switchman_task_nextGet the next pending task from the queue
switchman_task_claimClaim files the agent will edit
switchman_task_doneMark a task complete and release claims
switchman_task_failMark a task failed and release claims
switchman_write_fileWrite a file through the governance gateway
switchman_statusGet a full system overview
switchman_scanScan for conflicts across all worktrees
switchman_lease_heartbeatRefresh the agent's active lease

CLAUDE.md typically tells Claude Code things like:

✓
Commit CLAUDE.md to your repo. Every time Claude Code opens a workspace it will read these instructions and follow the coordination protocol automatically.

5. Add your tasks

switchman task add "Fix the login bug" --priority 8
switchman task add "Add rate limiting" --priority 6
switchman task add "Update README" --priority 2

6. Open one window per workspace

Open a separate Claude Code window for each agent workspace:

# Open these folders in separate Claude Code windows:
../my-project-agent1
../my-project-agent2
../my-project-agent3
⚠
Important: Open each agent workspace as its own Claude Code project — not as a subfolder inside the main repo. Each workspace has its own .mcp.json pointing to the shared coordination database.

With CLAUDE.md in place, Claude Code will:

  1. Call switchman_task_next to claim a task
  2. Call switchman_task_claim to register the files it will edit
  3. Prefer the governed write tools when appropriate
  4. Call switchman_task_done when finished
  5. Repeat for the next task

Watching agents coordinate

Keep this running in a separate terminal while agents work:

switchman status --watch

You'll see each agent's active task, which files are claimed, and any blocked collision attempts in real time.

Troubleshooting

Claude Code isn't picking up the MCP tools

Check the .mcp.json exists in the workspace folder:

cat .mcp.json

It should point to the switchman-mcp binary. If it's missing, run switchman setup --agents 3 again from the main repo.

Agent says "no pending tasks"

Either all tasks are claimed by other agents or the queue is empty. Check:

switchman task list

File claim is blocked

Another agent already owns that file. The blocked agent should pick a different task or wait. Run switchman status to see who owns the file.