Merge confidence for parallel AI coding sessions.
You're running Claude Code, Cursor, Codex, or another coding agent across multiple worktrees. Each agent finishes clean. Git says no conflicts. You merge, and something breaks in prod.
That's agentic drift. Switchman catches it before you merge.
🟢 GREEN - Safe to merge. No agentic drift detected across 3 worktrees.
🟡 AMBER - Review before merging. Interface mismatch on auth middleware.
🔴 RED - Do not merge. Ownership conflicts and unclaimed changes detected.
When Switchman cannot make a trustworthy call, it reports uncertain instead of pretending the merge is safe.
Questions or feedback? Discord · [email protected]
Requirements: Node.js 22.5+ · Git 2.5+
npm install -g switchman-devSwitchman uses the built-in
node:sqliteruntime. No extra database to install or manage.
switchman demoCreates a throwaway repo with two agents that conflict and shows Switchman catching the drift before merge — no setup required.
cd my-project
# Zero setup: review existing worktrees
switchman review --all-worktrees
# Review specific branches together
switchman review --pr-ready --from feature-auth feature-api
# Save a PR-ready handoff
switchman review --pr-ready --all-worktrees --out switchman-review.mdAdd CI protection when you want Switchman on every PR:
switchman gate install-ciDesktop board (optional): install once, then keep it in the menu bar — it stays hidden until a live file overlap appears:
git clone https://github.com/switchman-dev/switchman.git
cd switchman/desktop && npm install && npm run build
switchman board install
# Start from any project — lanes auto-register from git worktrees you already use
switchman boardSee Desktop board for details.
When you run parallel AI agents across git worktrees, they can make changes that look safe in isolation but break each other at runtime: mismatched interfaces, conflicting ownership, stale dependencies, or duplicate implementations that drift apart.
Switchman scans across active worktrees and gives you a single merge-confidence verdict before you land anything.
switchman review --pr-ready produces four things:
- A plain-English narrative of what each agent built
- Semantic flags where agents produced contradictory interfaces, duplicate implementations, or overlapping solutions
- A merge-confidence outcome:
green,amber,red, oruncertain - A PR-ready Markdown handoff with the safest next step
Use --all-worktrees for local worktree sessions, or --from <branches...> when you know the branches you want reviewed together.
Install the Stop hook once per repo. Switchman runs silently every time a Claude Code session ends.
switchman claude hooks installThis writes a hook into .claude/settings.local.json that fires switchman agent-complete automatically on session end. The first three clean runs print a short green confirmation so you know the hook is alive — after that, clean runs stay quiet and issues still print.
Poll all worktrees continuously. Switchman scans automatically when they go quiet.
# Run in the foreground
switchman watch
# Or run as a background daemon
switchman monitor start
switchman monitor status
switchman monitor stopThe --quiet-ms flag controls how long worktrees must be idle before a scan fires. The default is 5000ms.
The repo includes a local desktop app in desktop/ — a menu-bar companion for parallel agent sessions. It stays hidden until a live file overlap appears, then opens the board with agent + file + task context.
Git worktrees you already create are auto-registered — no need to route agent launches through Switchman unless you want it to create the worktree for you.
The CLI and desktop share a session registry at ~/.switchman/sessions.json. Repos you open the board from are remembered in ~/.switchman/board-roots.json.
cd desktop
npm install
npm run build
switchman board install# From any project repo — launches menu-bar app in the background
switchman board
# Your existing worktree workflow — lanes appear automatically
git worktree add ../myapp-feature-auth -b feature/auth
# Optional: let Switchman create the worktree and launch an agent
switchman board start "refactor cart total" --agent claude-code
switchman board listswitchman board done <session-id>
switchman board pause <session-id>
switchman board merge <session-id>
switchman board merge <session-id> --forceswitchman board --dev # run from source instead of ~/Applications/Switchman.app
cd desktop && npm run buildSee desktop/README.md for architecture notes.
Add merge confidence to every pull request automatically so the report lives where review already happens.
switchman gate install-ciDrops a GitHub Actions workflow into .github/workflows/switchman-gate.yml that runs on every PR and push.
switchman gate ci --github --github-comment --pr-from-envPosts or updates a PR comment like this:
🟡 Amber - Review before merging. Parallel agent changes detected.
| Signal | Value |
|---|---|
| Merge confidence | amber |
| Gate status | blocked |
| AI gate | warn |
| Non-compliant worktrees | 1 |
| Stale worktrees | 0 |
Review Signals
- Semantic conflicts: 1
- Ownership conflicts: 1
Next Step
- Review the flagged worktrees locally with
switchman review --pr-ready --all-worktreesbefore merging.
⭐ Switchman caught a risky merge? Star us on GitHub
The star prompt only appears on amber and red catches, when Switchman has earned the ask.
- File conflicts - two agents edited the same file
- Ownership conflicts - agents crossed into each other's declared scope
- Semantic conflicts - interfaces, types, or exports that diverged between worktrees
- Unclaimed changes - files edited outside any active task scope
- Stale dependencies - downstream code that depends on something an agent changed
- Boundary validations - task specs that were not fully satisfied before merge
# Run the full CI gate locally
switchman gate ci
# Run the AI-powered merge check only
switchman gate ai
# Validate changes against the active lease before committing
switchman gate commit
# Install git hooks for local protection
switchman gate install
# Install the GitHub Actions workflow
switchman gate install-ciAdd to your README to signal that your repo uses Switchman:
[](https://switchman.dev)
Want agents to coordinate before they conflict rather than catching drift after? Switchman ships an MCP server that lets agents claim files, pick tasks from a shared queue, and use guarded writes — so conflicts are prevented, not just detected.
# Initialise coordination mode
switchman init
switchman start "your goal"
# Start the MCP server
switchman mcpMore help:
Building this in public. If you hit something broken or missing, I'd love to hear about it.
MIT - switchman.dev