# git-paw

> Parallel AI Worktrees — orchestrate multiple AI coding CLI sessions across git worktrees

## Documentation

- [Introduction](https://bearicorn.github.io/git-paw/introduction.html): git-paw (Parallel AI Worktrees) orchestrates multiple AI coding CLI sessions across git worktrees from a single terminal using tmux.
- [Installation](https://bearicorn.github.io/git-paw/installation.html): Before installing git-paw, ensure you have:
- [Quick Start: Same CLI Mode](https://bearicorn.github.io/git-paw/quick-start-same-cli.html): This walkthrough shows how to launch git-paw with the same AI CLI on all branches — the most common workflow.
- [Quick Start: Per-Branch CLI Mode](https://bearicorn.github.io/git-paw/quick-start-per-branch.html): This walkthrough shows how to assign different AI CLIs to different branches — useful when you want to compare AI assistants or use specialized tools for specific tasks.
- [Quick Start: Orchestrator Mode](https://bearicorn.github.io/git-paw/quick-start-orchestrator.html): This walkthrough shows how to launch git-paw in supervisor mode and drive it from your own agent session, the orchestrator.
- [User Guide](https://bearicorn.github.io/git-paw/user-guide/index.html): This guide covers the full range of git-paw features beyond the quick starts.
  - [Session Lifecycle](https://bearicorn.github.io/git-paw/user-guide/session-lifecycle.html): This chapter covers what git paw start does to your worktrees on each launch (or relaunch), and how to control its behaviour when the defaults don’t fit.
  - [Worktree Placement](https://bearicorn.github.io/git-paw/user-guide/worktree-placement.html): Every agent git-paw launches works in its own git worktree — an independent checkout of a branch that shares the repository’s object store.
  - [Runtime Isolation](https://bearicorn.github.io/git-paw/user-guide/runtime-isolation.html): git-paw isolates each agent’s source: every agent gets its own git worktree, so nobody stashes, nobody switches branches, and nobody overwrites a peer’s edits.
  - [Security Posture](https://bearicorn.github.io/git-paw/user-guide/security-posture.html): This is the single, authoritative statement of git-paw’s trust model.
  - [Remote Control](https://bearicorn.github.io/git-paw/user-guide/remote-control.html): You can drive a git-paw session from a phone or another device.
  - [Per-CLI Setup](https://bearicorn.github.io/git-paw/user-guide/cli-setup.html): git paw setup-cli is the one command that writes into an agent CLI’s own settings file.
  - [FS-Scoped Sandbox](https://bearicorn.github.io/git-paw/user-guide/sandbox.html): An optional, opt-in way to confine an agent to its worktree using your OS’s kernel sandbox — sandbox-exec (Seatbelt) on macOS, bwrap (bubblewrap) on Linux/WSL.
  - [Spec-Driven Launch](https://bearicorn.github.io/git-paw/user-guide/spec-driven-launch.html): The --from-all-specs and --specs flags let you define branches, CLI assignments, and prompts in spec files instead of using interactive selection.
  - [Session Logging](https://bearicorn.github.io/git-paw/user-guide/session-logging.html): git-paw can capture the full terminal output of each AI CLI pane to log files.
  - [AGENTS.md Injection](https://bearicorn.github.io/git-paw/user-guide/agents-md.html): An agent’s working context is the combined view: the project’s tracked AGENTS.md plus a managed git-paw section that carries the entire spec body for the agent’s assigned change (proposal, design when present, task list, and any spec deltas).
  - [Agent Coordination](https://bearicorn.github.io/git-paw/user-guide/coordination.html): When multiple AI agents work in parallel, they benefit from knowing what the others are doing.
  - [Supervisor](https://bearicorn.github.io/git-paw/user-guide/supervisor.html): This chapter mirrors the user-facing prose for the bundled orchestrator skill (assets/agent-skills/orchestrator.md, exported to .git-paw/skills/orchestrator/SKILL.md; supervisor remains an alias of its name) — the doctrine the orchestrator runs against in supervisor mode.
  - [Tiered-Model Workflow](https://bearicorn.github.io/git-paw/user-guide/tiered-model-workflow.html): A smart orchestrator running a fleet of cheaper workers is the workflow git-paw is built for: one capable model supervises, and several lower-cost models do the implementation in parallel worktrees, with little-to-no human babysitting.
  - [Dashboard](https://bearicorn.github.io/git-paw/user-guide/dashboard.html): When the broker is enabled, one tmux pane runs the dashboard instead of an agent CLI, and it is pane 0 in every mode: the full-width top row above the agent grid, with the coding agents laid out row-major beneath it (no orchestrator CLI runs inside the session).
  - [Pause and Resume](https://bearicorn.github.io/git-paw/user-guide/pause.html): git paw pause is the soft-stop verb for short breaks (lunch, a meeting, end-of-day).
  - [Skill Templates](https://bearicorn.github.io/git-paw/user-guide/skill-templates.html): git-paw uses standardized agent skills following the agentskills.io specification.
  - [Docs Fetch Skill](https://bearicorn.github.io/git-paw/user-guide/docs-fetch.html): A bundled skill and helper that let an agent consult git-paw's documentation on demand.
  - [Governance](https://bearicorn.github.io/git-paw/user-guide/governance.html): git-paw can read your team’s existing governance documents as context for the supervisor agent — ADRs, a test strategy, a security checklist, a Definition of Done, and a project constitution.
  - [Learnings Mode](https://bearicorn.github.io/git-paw/user-guide/learnings.html): Learnings mode records deterministic friction signals from a supervisor session into a markdown file you can review after the run.
  - [Conflict Detection](https://bearicorn.github.io/git-paw/user-guide/conflict-detection.html): When supervisor mode is active, the broker runs an in-process conflict detector that watches for three failure shapes across parallel agents.
  - [MCP Server](https://bearicorn.github.io/git-paw/user-guide/mcp.html): git paw mcp runs a Model Context Protocol (MCP) server over stdio, so any MCP-aware client — Claude Desktop, Cursor, ChatGPT Desktop, Windsurf, VS Code MCP extensions — can query a repository’s state without an active git-paw session.
  - [Doctor](https://bearicorn.github.io/git-paw/user-guide/doctor.html): git paw doctor answers “why won’t it launch?” in one command.
    - [Selftest (internal)](https://bearicorn.github.io/git-paw/user-guide/selftest.html): git paw selftest runs an isolated, end-to-end session-lifecycle smoke check — the shipped form of the dogfood isolation recipe.
  - [CLI Prompt-Shape Profiles](https://bearicorn.github.io/git-paw/user-guide/cli-prompt-profiles.html): git-paw’s supervisor and prompt detectors recognise an agent CLI’s terminal surface — its “ready” banner, its permission-prompt wording, its mid-response footer — by matching known markers against captured pane text.
- [Configuration](https://bearicorn.github.io/git-paw/configuration/index.html): git-paw uses TOML configuration files at two levels, with repo-level settings overriding global ones.
- [Supported AI CLIs](https://bearicorn.github.io/git-paw/supported-clis.html): git-paw auto-detects these AI coding CLIs on your PATH:
- [CLI Reference](https://bearicorn.github.io/git-paw/cli-reference.html): git-paw is invoked as git paw (or git-paw).
- [Architecture](https://bearicorn.github.io/git-paw/architecture.html): This chapter covers git-paw’s internal architecture: module structure, data flow, and key design decisions.
  - [Target Architecture](https://bearicorn.github.io/git-paw/architecture-direction.html): The target structure git-paw's code is moving toward — ports and adapters at the edges, pure decisions in the middle — and the rules new code follows.
- [Specifications](https://bearicorn.github.io/git-paw/specifications/index.html): git-paw uses OpenSpec for formal, testable specifications: each capability has a dedicated spec.md under openspec/specs/ using RFC 2119 keywords (SHALL, MUST, SHOULD) and GIVEN/WHEN/THEN scenarios, and every scenario maps to at least one test.
- [Contributing](https://bearicorn.github.io/git-paw/contributing.html): Contributions to git-paw are welcome!
- [Changelog](https://bearicorn.github.io/git-paw/changelog.html): All notable changes to this project will be documented in this file.
- [FAQ](https://bearicorn.github.io/git-paw/faq.html): Parallel AI Worktrees.
- [Third-Party Licenses](https://bearicorn.github.io/git-paw/licenses.html): git-paw includes the following third-party software.