git-paw

Parallel AI Worktrees — orchestrate multiple AI coding CLI sessions across git worktrees from a single terminal using tmux.

Demo

$ git paw

  🐾 git-paw — Parallel AI Worktrees

  ? Select mode:
  > Same CLI for all branches
    Different CLI per branch

  ? Select branches (space to toggle, enter to confirm):
  > [x] feat/auth
    [x] feat/api
    [ ] fix/typo
    [ ] main

  ? Select AI CLI:
  > claude
    codex
    gemini

  ✔ Creating worktrees...
    ../myproject-feat-auth/
    ../myproject-feat-api/

  ✔ Launching tmux session: paw-myproject
    Pane 1: feat/auth → claude
    Pane 2: feat/api → claude

  Attaching to tmux session...

What It Does

git-paw lets you run multiple AI coding assistants in parallel, each in its own git worktree and tmux pane. Pick your branches, pick your AI CLI(s), and git-paw handles the rest — creating worktrees, launching a tmux session, and wiring everything together. Stop and resume sessions at will; your worktrees and uncommitted work are preserved.

Features

• Parallel AI sessions — run Claude, Codex, Gemini, or any AI CLI across multiple branches simultaneously
• Git worktree isolation — each branch gets its own working directory, no stashing or switching needed
• Smart session management — reattach to active sessions, auto-recover after crashes or reboots, and rebase existing agent branches onto the repository's default branch on every git paw start so agents never drift behind supervisor commits on main (pass --no-rebase to opt out)
• Interactive or scripted — fuzzy branch picker and CLI selector, or pass --cli and --branches flags
• Per-branch CLI assignment — use Claude on one branch and Gemini on another in the same session
• Presets — save branch + CLI combos in config for one-command launches
• Custom CLI support — register any AI CLI with git paw add-cli
• Session persistence — state saved to disk, survives tmux crashes and system reboots
• Dry run — preview the session plan before executing with --dry-run
• Mouse-friendly tmux — click to switch panes, drag borders to resize, scroll with mouse wheel
• Spec-driven launch — auto-discover specs and launch sessions with --from-all-specs (or narrow to a subset via --specs NAME[,NAME...])
• AGENTS.md integration — auto-inject session context into worktree AGENTS.md files
• Session logging — capture raw terminal output per pane for later review
• Replay — view session logs with ANSI stripping or colored output via less -R
• Project init — git paw init bootstraps .git-paw/, config, and gitignore
• Standards-based — uses AGENTS.md following the Linux Foundation standard for AI agent instructions
• Agent coordination — built-in HTTP broker lets agents share status, artifacts, and blocked requests
• Dashboard TUI — live status table in pane 0 shows agent progress at a glance
• Broker messages panel — optional dashboard section showing real-time agent communication (configurable via [dashboard] show_message_log = true)
• Skill templates — coordination instructions auto-injected into each agent's AGENTS.md
• Boot-prompt injection — standardized boot instructions automatically prepended to all agent prompts, ensuring reliable self-reporting (register, done, blocked, question operations) — always enabled for broker sessions
• Cursor-based messaging — lossless message polling with sequence tracking
• Spec Kit backend — first-class support for GitHub Spec Kit projects via [specs] type = "speckit"; .specify/specs/ is auto-detected at the repo root and the [P]/non-[P] task split decomposes into per-task and consolidated worktrees
• --specs-format override — force-select the spec backend (openspec, markdown, speckit) on the command line, overriding both [specs] type in config and the .specify/ auto-detection
• --no-supervisor — single-session override of [supervisor] enabled = true for plain (non-supervisor) operation without editing config
• start --force — bypass the uncommitted-spec validation warning when launching with --from-all-specs or --specs
• Forward coordination — agents publish agent.intent before they begin editing so peers (and the broker conflict detector) see the planned file set ahead of the first commit
• Automatic conflict detection — the broker auto-emits [conflict-detector]-tagged agent.feedback for forward (overlapping intents), in-flight (overlapping modified_files), and ownership-violation conflicts; unresolved in-flight overlaps escalate to the supervisor inbox via agent.question
• Learnings mode — opt-in [supervisor] learnings = true collects deterministic friction signals (stuck duration, recovery cycles, forward conflicts, in-flight conflicts, ownership violations) into .git-paw/session-learnings.md for post-session review. No telemetry — the file is purely local and nothing is sent anywhere; you can optionally share it via a GitHub issue (after reviewing/anonymising it) to help improve the tool. See Learnings → Privacy & Sharing
• Governance pointers — point the supervisor at your existing ADRs, test strategy, security checklist, DoD, and constitution via the [governance] config table; Spec Kit projects auto-wire .specify/memory/constitution.md when present
• Auto-approval policy — [supervisor.auto_approve] controls safe-command prefixes and approval level for stalled-pane sweeps; [supervisor.common_dev_allowlist] seeds a curated dev-loop preset into .claude/settings.json so common build/test/git commands bypass per-prompt approval
• Conflict-detector tuning — [supervisor.conflict] exposes the in-flight escalation window (window_seconds), the intent-overlap warning toggle (warn_on_intent_overlap), and the ownership-violation escalation toggle (escalate_on_violation)
• Learnings flush cadence — [supervisor.learnings_config] flush_interval_seconds (default 60) controls how often learnings entries are flushed from memory to .git-paw/session-learnings.md
• Routing through the supervisor — type /agents in the supervisor pane to see the live agent inventory (status, mode, pane) and /tell <agent> <prompt> to route a prompt to one agent without tab-switching into its pane; [supervisor.tell] mode picks the delivery channel (feedback queue by default, send-keys for accept-edits agents) and every route is recorded in the session learnings
• MCP server (v0.7.0+) — git paw mcp exposes this repo's read-only state (coordination intents/conflicts, governance docs, specs/tasks, session status/learnings, agent skills, git context) over the Model Context Protocol so any MCP-aware client can query it; runs standalone over stdio, degrades gracefully when no session is active, and never invokes an agent CLI as a backend

Tip: git-paw uses AGENTS.md as the standard agent instruction file. If your AI CLI reads a different file (e.g., CLAUDE.md, GEMINI.md), you can symlink it:

ln -s AGENTS.md CLAUDE.md   # Claude Code reads CLAUDE.md
ln -s AGENTS.md GEMINI.md   # Gemini reads GEMINI.md

Add these symlinks to .gitignore so they stay local to each developer.

Platform Support

Platform	Status	Notes
macOS (ARM)	Supported	Primary development platform
macOS (x86)	Supported
Linux (x86_64)	Supported
Linux (ARM64)	Supported
Windows	WSL only	tmux is a Unix tool — use Windows Subsystem for Linux

Why no native Windows? git-paw relies on tmux for terminal multiplexing, which is not available natively on Windows. WSL provides a full Linux environment where git-paw works perfectly.

Quick Start: Same CLI

Use the same AI CLI across all branches:

# Interactive — pick branches and CLI from prompts
git paw

# Non-interactive — specify everything upfront
git paw start --cli claude --branches feat/auth,feat/api

This creates:

• A worktree for each branch (../yourproject-feat-auth/, ../yourproject-feat-api/)
• A tmux session with one pane per branch, each running claude

Quick Start: Per-Branch CLI

Use different AI CLIs on different branches:

# Interactive mode — select "Different CLI per branch"
git paw
# → Pick branches: feat/auth, feat/api
# → Pick CLI for feat/auth: claude
# → Pick CLI for feat/api: gemini

Result: a tmux session where feat/auth runs Claude and feat/api runs Gemini, side by side.

Quick Start: Supervisor Mode

Run an unattended supervisor agent that orchestrates the worker agents on your behalf:

git paw start --supervisor

# Skip supervisor for a single run even when [supervisor] enabled = true is set
git paw start --no-supervisor

# Bypass the uncommitted-spec validation warning when launching from specs
git paw start --from-all-specs --force
git paw start --supervisor --force

The supervisor agent runs in its own pane, polls each worker agent for progress and artifacts via the broker, runs the configured test command between merges, and writes a session summary when work completes. Use this mode when you want to leave a multi-branch session running without continually steering each agent yourself.

In v0.5.0 supervisor mode also seeds a curated dev-command allowlist into .claude/settings.json on session start so common dev-loop commands (cargo build, git commit, just, mdbook build, openspec validate, ...) bypass per-prompt approval. Opt out with [supervisor.common_dev_allowlist] enabled = false; extend with extra = [...].

--no-supervisor is the highest-precedence step in the supervisor-mode resolution chain — it wins over both [supervisor] enabled = true in config and any interactive prompt. It is mutually exclusive with --supervisor; passing both fails at parse time. --force only matters for spec-mode launches (--from-all-specs / --specs) and bypasses the warning when uncommitted spec changes are detected on disk.

Installation

From crates.io

cargo install git-paw

Homebrew

brew install bearicorn/tap/git-paw

Shell installer

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bearicorn/git-paw/releases/latest/download/git-paw-installer.sh | sh

Windows (WSL)

Install WSL, then use any of the Linux installation methods above inside your WSL environment:

# Inside WSL
sudo apt install tmux
cargo install git-paw

Prerequisites

• tmux — terminal multiplexer
• Git — with worktree support (2.5+)

git paw vs git-paw

Once installed to your PATH, git-paw works as a git subcommand:

git paw start    # git finds `git-paw` on PATH automatically

You can also call the binary directly — useful during development or if it's not on PATH:

git-paw start    # equivalent
cargo run -- start  # during development

All examples below use git paw, but git-paw works identically.

Usage

init — Initialize project

git paw init

Creates .git-paw/ directory with default config and sets up .gitignore for logs.

start — Launch or reattach

# Interactive launch
git paw start

# Specify CLI and branches
git paw start --cli claude --branches feat/auth,feat/api

# Launch every discovered spec (OpenSpec, Markdown, or Spec Kit)
git paw start --from-all-specs
git paw start --from-all-specs --cli claude

# Force-select the spec backend, overriding [specs] type and .specify/ auto-detection
git paw start --from-all-specs --specs-format speckit

# Narrow to specific specs, or open a multi-select picker
git paw start --specs add-auth,fix-session
git paw start --specs   # interactive picker (requires a TTY)

# Use a preset from config
git paw start --preset backend

# Preview without executing
git paw start --dry-run

# Bypass the uncommitted-spec validation warning
git paw start --from-all-specs --force

Smart behavior:

• Active session exists → reattaches
• Stopped/crashed session → auto-recovers (reuses worktrees, relaunches CLIs)
• No session → full interactive launch

add — Attach a branch mid-session (v0.6.0+)

git paw add feat/new-thing            # attach a worktree + agent pane (session's default CLI)
git paw add feat/api --cli codex      # choose the CLI for the new pane
git paw add --from-spec add-export    # derive branch + CLI from a discovered spec

Hot-attaches a worktree and agent pane to a running supervisor session — no stop/purge/restart, the other agents keep working. The grid re-tiles to the layout a start of that many agents would produce, the new agent boots with the same broker boot block + prompt a start-time agent gets, and the supervisor discovers it on its next sweep. Adding past the 25-agent cap is rejected; adding to a paused session leaves the new pane paused until git paw resume. See Session Lifecycle.

remove — Detach a single agent (v0.6.0+)

git paw remove feat/done-thing            # close pane, remove worktree, drop from session
git paw remove feat/wip --force           # remove even with uncommitted changes
git paw remove feat/keep --keep-worktree  # detach pane only; leave worktree + branch on disk

Detaches one agent: closes its pane, re-tiles the grid for the smaller agent count, removes its worktree (reusing purge's teardown), and drops it from the session. Safe by default — refuses a worktree with uncommitted changes (listing what would be lost) unless --force; --keep-worktree detaches the pane but leaves the worktree on disk. git paw remove supervisor is refused — use git paw stop to end the whole session.

pause — Soft-stop the session (v0.5.0+)

git paw pause

Detaches the tmux client, stops the broker, and leaves every CLI pane running. Preserves agent conversation state for instant resume via git paw start. Holds RAM (~300 MB per Claude pane), so use it for short breaks (lunch, meetings, end-of-day). See Pause and Resume for the full trade-off.

stop — Kill the CLIs, keep the worktrees

git paw stop          # prompts for confirmation in a TTY
git paw stop --force  # skip the prompt (scripts)

Kills the tmux session and every CLI pane process but preserves worktrees and state on disk. CLI conversation context is lost. Run git paw start later to recover with fresh CLI processes.

purge — Remove everything

# With confirmation prompt
git paw purge

# Skip confirmation
git paw purge --force

Removes the tmux session, all worktrees, and session state.

status — Check session state

git paw status

Shows session name, branches, CLIs, and status (active/stopped/no session).

list-clis — Show available CLIs

git paw list-clis

Lists auto-detected and custom AI CLIs with their source.

add-cli — Register a custom CLI

# With absolute path
git paw add-cli my-agent /usr/local/bin/my-agent

# With display name
git paw add-cli my-agent my-agent --display-name "My Agent"

remove-cli — Unregister a custom CLI

git paw remove-cli my-agent

Only custom CLIs can be removed — auto-detected CLIs cannot.

replay — View session logs

# List available log sessions
git paw replay --list

# View a branch's log (ANSI stripped)
git paw replay feat/auth

# View with colors via less -R
git paw replay feat/auth --color

# Replay from a specific session
git paw replay feat/auth --session paw-myproject

Requires session logging to be enabled in config.

mcp — Read-only MCP server (v0.7.0+)

Runs a Model Context Protocol server on stdio so any MCP-aware client (Claude Desktop, Cursor, ChatGPT Desktop, Windsurf, VS Code MCP) can query this repository's read-only state: coordination intents/conflicts, governance docs, specs and tasks, session status and learnings, agent skills, and git context. It runs standalone — no tmux session or broker required.

# Serve the repo in the current directory
git paw mcp

# Serve a specific repo (required for clients that spawn from a fixed dir,
# notably Claude Desktop)
git paw mcp --repo /path/to/your/repo

# Tee diagnostics to a file (stderr is always used; stdout is JSON-RPC only)
git paw mcp --repo /path/to/your/repo --log-file /tmp/git-paw-mcp.log

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "git-paw": {
      "command": "git",
      "args": ["paw", "mcp", "--repo", "/absolute/path/to/your/repo"]
    }
  }
}

See the MCP user-guide chapter for per-client setup (Cursor, ChatGPT Desktop, Windsurf, VS Code MCP), the full tool reference, and known limitations.

Configuration

Per-repo config (.git-paw/config.toml)

# Pre-select a CLI in the interactive picker
default_cli = "my-cli"
mouse = true

# Bypass picker entirely for spec-mode launches (--from-all-specs, --specs)
default_spec_cli = "my-cli"

# Prefix for spec-derived branches (default: "spec/")
branch_prefix = "spec/"

# Spec scanning
[specs]
dir = "specs"
type = "openspec"  # "openspec", "markdown", or "speckit"

# Session logging
[logging]
enabled = true

# Dashboard configuration
[dashboard]
# Show broker messages panel for real-time agent communication
show_message_log = true

[presets.backend]
branches = ["feat/api", "fix/db"]
cli = "my-cli"

Global config (~/.config/git-paw/config.toml)

default_cli = "my-cli"
mouse = true

[clis.my-agent]
command = "/usr/local/bin/my-agent"
display_name = "My Agent"

[clis.local-llm]
command = "ollama-code"
display_name = "Local LLM"

[presets.backend]
branches = ["feat/api", "fix/db"]
cli = "my-cli"

Per-repo config overrides global config for overlapping fields.

Supported AI CLIs

git-paw auto-detects the following AI coding CLIs when they are on PATH. The list reflects src/detect.rs::KNOWN_CLIS at the time of this release; the table grows as binaries land in upstream releases.

CLI	Binary
Claude Code	claude
OpenAI Codex	codex
Google Gemini CLI	gemini
Aider	aider
Vibe	vibe
Qwen	qwen
Amp	amp
opencode	opencode
Cline	cline
Droid	droid
Pi	pi
Junie	junie
Cursor Agent	cursor
GitHub Copilot CLI	copilot
cn	cn
Kilo Code	kilo
Kimi	kimi

Don't see your CLI? Register it:

git paw add-cli my-cli /path/to/my-cli --display-name "My CLI"

How It Works

git paw start
    │
    ├─ 1. Validate git repo
    ├─ 2. Load config (global + repo)
    ├─ 3. Detect AI CLIs on PATH + custom
    ├─ 4. Interactive selection (or use flags)
    ├─ 5. Create git worktrees
    │      ../project-feat-auth/
    │      ../project-feat-api/
    ├─ 6. Create tmux session (paw-project)
    │      ┌─────────────────┬─────────────────┐
    │      │ feat/auth        │ feat/api         │
    │      │ → claude         │ → claude         │
    │      │                  │                  │
    │      └─────────────────┴─────────────────┘
    ├─ 7. Save session state to disk
    └─ 8. Attach to tmux session

git paw pause  → soft stop (detach + broker stop; CLIs keep running)
git paw stop   → kills CLIs, keeps worktrees + state
git paw start  → auto-recovers (or restarts a paused session)
git paw purge  → removes everything

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Releases

Releases follow a single chore: prepare vX.Y.Z release commit on main that bumps Cargo.toml, regenerates CHANGELOG.md via git cliff, and archives completed OpenSpec changes (moving them under openspec/changes/archive/<date>-<change>/ and syncing their delta specs into openspec/specs/). Pushing the vX.Y.Z tag triggers cargo-dist on GitHub Actions to build cross-platform binaries and update the Homebrew tap.

After the tag, the maintainer publishes to crates.io manually (it is not wired into cargo-dist):

cargo publish --dry-run   # verify
cargo publish             # upload vX.Y.Z

The full procedure (archive ordering, changelog regeneration, tag rules, crates.io publish step, recovery from a botched prep commit) lives in AGENTS.md § Release & Distribution.

License

MIT — Copyright 2026 bearicorn