switchman-dev 0.1.0

package/CLAUDE.md

@@ -0,0 +1,98 @@
+# Switchman Agent Instructions
+
+This repository uses **Switchman** to coordinate parallel AI coding agents.
+You MUST follow these instructions every session to avoid conflicting with other agents.
+
+---
+
+## Your worktree
+
+Find your worktree name by running:
+```bash
+git worktree list
+```
+The path that matches your current directory is your worktree. Use the last path segment as your worktree name (e.g. `/projects/myapp-feature-auth` → `feature-auth`). The main repo root is always named `main`.
+
+---
+
+## Required workflow — follow this every session
+
+### 1. Start of session — get your task
+
+Call the `switchman_task_next` MCP tool with your worktree name:
+```
+switchman_task_next({ worktree: "<your-worktree-name>", agent: "claude-code" })
+```
+
+- If `task` is `null` — the queue is empty. Ask the user what to work on, or stop.
+- If you receive a task — note the `task.id`. You'll need it in the next steps.
+
+### 2. Before editing any files — claim them
+
+Call `switchman_task_claim` with every file you plan to edit **before you edit them**:
+```
+switchman_task_claim({
+  task_id: "<task-id>",
+  worktree: "<your-worktree-name>",
+  files: ["src/auth/login.js", "tests/auth.test.js"]
+})
+```
+
+- If `safe_to_proceed` is `false` — there are conflicts. Do NOT edit those files.
+  Read the `conflicts` array to see which worktrees own them, then either:
+  - Choose different files that accomplish the same goal
+  - Ask the user how to proceed
+
+- If `safe_to_proceed` is `true` — you are clear to edit.
+
+### 3. Do the work
+
+Implement the task. Make commits as normal. Other agents will avoid your claimed files.
+
+If you discover mid-task that you need to edit additional files, call `switchman_task_claim` again for those files before editing them.
+
+### 4. End of session — mark complete or failed
+
+**On success:**
+```
+switchman_task_done({ task_id: "<task-id>", release_files: true })
+```
+
+**On failure (can't complete the task):**
+```
+switchman_task_fail({ task_id: "<task-id>", reason: "Brief explanation of what blocked you" })
+```
+
+Always call one of these before ending your session. Released file claims allow other agents to proceed.
+
+---
+
+## Checking for conflicts
+
+At any time you can scan for conflicts across all worktrees:
+```
+switchman_scan()
+```
+
+Run this before merging your branch. If `safe_to_proceed` is `false`, do not merge until conflicts are resolved.
+
+---
+
+## Checking system state
+
+To see what other agents are doing:
+```
+switchman_status()
+```
+
+This shows all pending and in-progress tasks, file claims per worktree, and worktree list.
+
+---
+
+## Rules
+
+1. **Always claim files before editing them** — not after.
+2. **Always call `switchman_task_done` or `switchman_task_fail` at end of session** — never leave tasks as `in_progress` when you stop.
+3. **If `safe_to_proceed` is false, do not edit the conflicting files** — coordinate first.
+4. **Do not claim files you don't need** — over-claiming blocks other agents unnecessarily.
+5. **One task per session** — complete or fail your current task before taking another.

package/README.md

@@ -0,0 +1,243 @@
+# Switchman
+
+**Stop your AI agents from overwriting each other.**
+
+When you run multiple Claude Code instances on the same repo, they have no idea what each other is doing. One agent edits a file while another rewrites it. Hours of work disappear at merge time.
+
+Switchman gives them a shared task queue and file locking so they stay on separate tracks — and you stay in control.
+
+---
+
+## Requirements
+
+- Node.js 22.5+
+- Git 2.5+
+
+---
+
+## Install
+
+```bash
+npm install -g @switchman-dev
+```
+
+---
+
+## Pick your setup
+
+### Option A — Claude Code (recommended)
+
+Claude Code has a native Switchman integration via MCP. Your agents coordinate automatically — no manual CLI calls, no extra prompting.
+
+**Step 1 — Create your agent workspaces**
+
+```bash
+cd my-project
+switchman setup --agents 3
+```
+
+That's it. Switchman creates three isolated workspaces, one per agent, and initialises the database. You'll see the folder paths printed — you'll need them in step 4.
+
+**Step 2 — Add Switchman to Claude Code**
+
+Add this to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "switchman": {
+      "command": "switchman-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Then restart Claude Code.
+
+**Step 3 — Copy CLAUDE.md into your repo root**
+
+```bash
+curl -O https://raw.githubusercontent.com/switchman-dev/switchman/main/CLAUDE.md
+```
+
+This tells your agents how to use Switchman. Without it they won't know to coordinate.
+
+**Step 4 — Add your tasks**
+
+```bash
+switchman task add "Fix the login bug" --priority 8
+switchman task add "Add rate limiting" --priority 6
+switchman task add "Update README" --priority 2
+```
+
+**Step 5 — Open Claude Code in each workspace**
+
+Open a separate Claude Code window in each folder that `switchman setup` created. Each agent will automatically pick up a task, lock the files it needs, and release them when it's done.
+
+**Step 6 — Check before merging**
+
+```bash
+switchman scan
+```
+
+---
+
+### Option B — Any other agent (Cursor, Windsurf, Aider, etc.)
+
+Switchman works as a CLI tool with any agent that can run terminal commands. The coordination isn't automatic — you'll need to prompt your agents to use Switchman commands.
+
+**Step 1 — Create your agent workspaces**
+
+```bash
+cd my-project
+switchman setup --agents 3
+```
+
+**Step 2 — Add your tasks**
+
+```bash
+switchman task add "Fix the login bug" --priority 8
+switchman task add "Add rate limiting" --priority 6
+```
+
+**Step 3 — Give each agent this prompt**
+
+Paste this into your agent at the start of each session:
+
+```
+Before starting any work:
+1. Run `switchman task next --json` to get your assigned task
+2. Run `switchman claim <taskId> <worktreeName> <files...>` to lock the files you'll edit
+   - If a file is already claimed, pick a different approach or different files
+3. When finished, run `switchman task done <taskId>`
+
+Never edit a file you haven't claimed. If a claim fails, do not use --force.
+```
+
+**Step 4 — Check before merging**
+
+```bash
+switchman scan
+```
+
+---
+
+## What your agents will see
+
+Here's what a normal session looks like with Switchman running:
+
+```
+# Agent 1 picks up a task
+switchman task next
+✓  Assigned: "Add rate limiting to all routes"  [task-abc-123]
+
+# Agent 1 locks its files
+switchman claim task-abc-123 agent1 src/middleware/auth.js src/server.js
+✓  2 files locked — no conflicts
+
+# Agent 2 picks up a different task
+switchman task next
+✓  Assigned: "Add validation to POST /tasks"  [task-def-456]
+
+# Agent 2 tries to claim a file already locked by Agent 1
+switchman claim task-def-456 agent2 src/middleware/auth.js
+⚠  Conflict: auth.js is locked by agent1
+
+# Agent 2 claims different files instead
+switchman claim task-def-456 agent2 src/middleware/validate.js src/routes/tasks.js
+✓  2 files locked — no conflicts
+
+# Both agents working, zero collisions
+switchman status
+  agent1  →  "Add rate limiting"      editing auth.js, server.js
+  agent2  →  "Add validation"         editing validate.js, tasks.js
+```
+
+---
+
+## Commands
+
+### `switchman setup`
+One-command setup — creates agent workspaces and initialises the database.
+- `--agents 3` — number of workspaces to create (default: 3, max: 10)
+- `--prefix switchman` — branch name prefix (default: switchman)
+
+### `switchman init`
+Initialise in the current git repo without creating worktrees. Creates `.switchman/switchman.db` and auto-detects existing worktrees.
+
+### `switchman task add <title>`
+Add a task to the queue.
+- `--priority 1-10` (default: 5)
+- `--description "..."`
+
+### `switchman task list`
+List all tasks. Filter with `--status pending|in_progress|done|failed`.
+
+### `switchman task next`
+Get and assign the next pending task. Use `--json` for agent automation.
+- `--worktree <name>` — worktree to assign to (defaults to current folder name)
+- `--agent <name>` — agent identifier for logging
+
+### `switchman task done <taskId>`
+Mark a task complete and release all file claims.
+
+### `switchman task fail <taskId>`
+Mark a task failed and release all file claims.
+
+### `switchman claim <taskId> <worktree> [files...]`
+Lock files before editing. Warns immediately if any file is already claimed by another agent.
+
+### `switchman release <taskId>`
+Release all file claims for a task.
+
+### `switchman scan`
+Check all worktrees for conflicts — both uncommitted file overlaps and branch-level merge conflicts. Run this before merging.
+
+### `switchman status`
+Full overview: task counts, active tasks, locked files, and a quick conflict scan.
+
+### `switchman worktree list`
+List all git worktrees with their registered agents and status.
+
+### `switchman worktree sync`
+Re-sync git worktrees into the Switchman database (useful if you add worktrees after init).
+
+---
+
+## MCP tools (Claude Code)
+
+| Tool | What it does |
+|------|-------------|
+| `switchman_task_next` | Get + assign the next pending task |
+| `switchman_task_add` | Add a new task to the queue |
+| `switchman_task_claim` | Claim files before editing (conflict check) |
+| `switchman_task_done` | Mark task complete, release file claims |
+| `switchman_task_fail` | Mark task failed, release file claims |
+| `switchman_scan` | Scan all worktrees for conflicts |
+| `switchman_status` | Full system overview |
+
+---
+
+## Roadmap
+
+- [ ] Merge queue — serialize worktree→main merges with auto-retry
+- [ ] Agent health monitoring — reclaim tasks from dead/stalled agents
+- [ ] Cursor and Windsurf native MCP integration
+- [ ] Web dashboard
+- [ ] `brew install switchman`
+
+---
+
+## Feedback & contact
+
+Building this in public — if you're running parallel agents and hit something broken or missing, I'd love to hear about it.
+
+- **GitHub Issues** — [github.com/switchman-dev/switchman/issues](https://github.com/switchman-dev/switchman/issues)
+- **Email** — [hello@switchman.dev](mailto:hello@switchman.dev)
+
+---
+
+## License
+
+MIT — free to use, modify, and distribute.

package/examples/README.md

@@ -0,0 +1,117 @@
+# Switchman Example — taskapi
+
+A real Express REST API used to test Switchman locally.
+
+## What's in here
+
+```
+examples/
+├── taskapi/                  — A small task management REST API
+│   ├── src/
+│   │   ├── server.js         — Express entry point
+│   │   ├── db.js             — In-memory data store
+│   │   ├── middleware/
+│   │   │   ├── auth.js       — API key auth (shared by all routes)
+│   │   │   └── validate.js   — Request validation
+│   │   └── routes/
+│   │       ├── tasks.js      — CRUD endpoints for tasks
+│   │       └── users.js      — User listing
+│   └── tests/
+│       └── api.test.js       — Smoke tests (run against live server)
+├── setup.sh                  — Creates git repo, 3 worktrees, seeds Switchman tasks
+├── walkthrough.sh            — Step-by-step demo of the full agent workflow
+└── teardown.sh               — Resets everything so you can start fresh
+```
+
+## Quick start
+
+Make sure Switchman is installed globally first:
+```bash
+npm install -g .   # from the switchman repo root
+```
+
+Then from the switchman repo root:
+```bash
+bash examples/setup.sh
+bash examples/walkthrough.sh
+```
+
+## What the walkthrough shows
+
+1. **3 worktrees created** — simulating 3 parallel Claude Code instances each on their own branch
+2. **Agent 1 picks up a task** — `switchman task next` returns the highest-priority item
+3. **Agent 1 claims files** — declares which files it will edit before touching them
+4. **Agent 2 picks up a task** — takes the next item from the queue
+5. **Agent 2 tries to claim a conflicting file** — Switchman blocks it
+6. **Agent 2 adapts** — claims only the safe files instead
+7. **Agent 1 finishes** — marks task done, releases file claims
+8. **Final status** — queue updated, no lingering conflicts
+
+## The taskapi project
+
+A minimal but real Express API with:
+- API key authentication (`Authorization: Bearer dev-key-alice-123`)
+- CRUD endpoints for tasks (`GET/POST/PATCH/DELETE /tasks`)
+- User listing (`GET /users`, admin only)
+- Input validation middleware
+- In-memory data store (no database setup required)
+
+### Running the API
+
+```bash
+cd examples/taskapi
+npm install
+npm start
+```
+
+```
+taskapi running on http://localhost:3000
+  GET  /health
+  GET  /tasks   (Bearer dev-key-alice-123)
+  GET  /users   (Bearer dev-key-alice-123, admin only)
+```
+
+### Running the API tests
+
+With the server running in one terminal:
+```bash
+cd examples/taskapi
+node tests/api.test.js
+```
+
+### API keys
+
+| Key | User | Role |
+|-----|------|------|
+| `dev-key-alice-123` | Alice | admin |
+| `dev-key-bob-456` | Bob | member |
+| `test-key-789` | Test | member |
+
+### Example requests
+
+```bash
+# Health check
+curl http://localhost:3000/health
+
+# List tasks
+curl -H "Authorization: Bearer dev-key-alice-123" http://localhost:3000/tasks
+
+# Create a task
+curl -X POST http://localhost:3000/tasks \
+  -H "Authorization: Bearer dev-key-alice-123" \
+  -H "Content-Type: application/json" \
+  -d '{"title": "My new task", "priority": "high"}'
+
+# Update task status
+curl -X PATCH http://localhost:3000/tasks/1 \
+  -H "Authorization: Bearer dev-key-alice-123" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "done"}'
+```
+
+## Reset
+
+```bash
+bash examples/teardown.sh
+bash examples/setup.sh
+```

package/examples/setup.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# examples/setup.sh
+#
+# Sets up the taskapi example project for testing Switchman locally.
+#
+# What this does:
+#   1. Inits taskapi as a git repo with an initial commit
+#   2. Creates 3 git worktrees (simulating 3 parallel Claude Code instances)
+#   3. Runs switchman init
+#   4. Seeds 4 realistic parallel tasks
+#
+# Run from the switchman repo root:
+#   bash examples/setup.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TASKAPI_DIR="$SCRIPT_DIR/taskapi"
+WORKTREES_DIR="$SCRIPT_DIR/worktrees"
+
+echo ""
+echo "━━━ Switchman Example Setup ━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# ── Step 1: Init the project as a git repo ────────────────────────────────────
+
+echo "→ Initialising taskapi as a git repo..."
+cd "$TASKAPI_DIR"
+
+if [ -d ".git" ]; then
+  echo "  Already a git repo — skipping init"
+else
+  git init -q
+  git config user.email "demo@switchman.dev"
+  git config user.name "Switchman Demo"
+  npm install --silent
+  git add -A
+  git commit -m "Initial commit: taskapi Express REST API" -q
+  echo "  ✓ Git repo initialised"
+fi
+
+# ── Step 2: Create 3 worktrees ────────────────────────────────────────────────
+
+echo ""
+echo "→ Creating 3 git worktrees (simulating 3 parallel agents)..."
+mkdir -p "$WORKTREES_DIR"
+
+create_worktree() {
+  local name=$1
+  local branch=$2
+  local path="$WORKTREES_DIR/$name"
+  if [ -d "$path" ]; then
+    echo "  Worktree '$name' already exists — skipping"
+  else
+    git worktree add -b "$branch" "$path" -q
+    echo "  ✓ $name  →  branch: $branch"
+  fi
+}
+
+create_worktree "agent-rate-limiting"  "feature/rate-limiting"
+create_worktree "agent-validation"     "feature/input-validation"
+create_worktree "agent-tests"          "feature/write-tests"
+
+echo ""
+git worktree list
+
+# ── Step 3: Switchman init ────────────────────────────────────────────────────
+
+echo ""
+echo "→ Initialising Switchman in taskapi..."
+switchman init
+
+# ── Step 4: Seed tasks ────────────────────────────────────────────────────────
+
+echo ""
+echo "→ Seeding 4 parallel tasks..."
+
+switchman task add "Add rate limiting to all API routes" \
+  --priority 8 \
+  --description "Token bucket: 100 req/min per API key. Return 429 with Retry-After header."
+
+switchman task add "Add input validation to POST /tasks and PATCH /tasks/:id" \
+  --priority 7 \
+  --description "Validate title length, status enum, priority enum. Return 400 with descriptive errors."
+
+switchman task add "Write tests for the auth middleware" \
+  --priority 6 \
+  --description "Test requireAuth and requireAdmin: valid key, missing key, bad key, wrong role."
+
+switchman task add "Add pagination to GET /tasks" \
+  --priority 5 \
+  --description "Add ?page=1&limit=20. Return { tasks, count, page, totalPages }."
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✓ Setup complete."
+echo ""
+echo "Tasks ready:"
+switchman task list
+echo ""
+echo "→ Next: bash examples/walkthrough.sh"
+echo ""