Docs / Getting started

Getting started

Install Switchman, run the demo, then use the newer guided flow with switchman quickcheck and switchman start to get coordinated AI work running quickly.

ℹ
Requirements: Node.js 22.5+ and Git 2.5+. Switchman uses Node's built-in node:sqlite module — no external database needed.

1. Install

Install Switchman globally via npm:

terminalnpm install -g switchman-dev

Confirm it's installed:

switchman --version

2. Run the demo

Before setting up a real repo, run the demo to see conflict prevention in action:

switchman demo

This creates a throwaway repo and shows:

✓
You should see proof: agent2 was blocked from src/auth.js and final gate: clean. If you do, Switchman is working correctly.

3. Check your repo and get the next command

From inside any git repo, start with:

cd my-project
switchman quickcheck

quickcheck gives you one readiness summary and one exact next command. On a healthy repo that is usually:

switchman start "Add authentication middleware"

4. Start the guided flow

Use start when you want the shortest path:

switchman start "Add authentication middleware"

This creates or refreshes:

✓
If editor wiring feels off later, run switchman verify-setup. If you want to regenerate the repo guide, run switchman claude refresh.

5. Open your agents

Open one Claude Code, Cursor, or Windsurf window per generated workspace.

Each agent window uses Switchman through MCP to pick work, claim files, and stay out of each other’s way.

6. Watch it run

Keep the status dashboard open while agents work:

switchman status --watch

After the first session, run:

switchman session-summary

This gives you a compact summary of what Switchman coordinated.

7. Land the work

When tasks are done, run the CI gate and then the merge queue:

switchman gate ci
switchman queue run

gate ci checks for conflicts, unclaimed changes, stale work, and policy issues. If it passes, queue run lands finished work safely.

Manual path

If you want full control instead of the guided flow, use the older explicit setup:

switchman setup --agents 5
switchman task add "Add authentication middleware" --priority 9
switchman verify-setup

What's next