Introduction

git-paw (Parallel AI Worktrees) orchestrates multiple AI coding CLI sessions across git worktrees from a single terminal using tmux.

Working with AI coding assistants like Claude, Codex, or Antigravity is powerful — but what if you could run them in parallel across multiple branches at once? That’s exactly what git-paw does.

The Problem

You have a feature branch, a bugfix branch, and a refactoring branch. You want an AI assistant working on each one simultaneously. Normally you’d need to:

1. Open multiple terminals
2. Create git worktrees manually
3. Navigate to each worktree
4. Launch your AI CLI in each one
5. Juggle between them

The Solution

With git-paw, you run a single command:

git paw

git-paw will:

• Detect which AI CLIs you have installed (Claude, Codex, Antigravity, Aider, etc.)
• Prompt you to pick branches and a CLI (or different CLIs per branch)
• Create git worktrees for each selected branch
• Launch a tmux session with one pane per branch, each running your chosen AI CLI
• Persist the session state so you can stop, resume, or recover after crashes

Key Features

• One command to go from zero to parallel AI sessions
• Smart start — reattaches to active sessions, recovers crashed ones, or launches fresh
• Live branch-set editing (v0.6.0) — git paw add and git paw remove attach or detach a single agent mid-session, no stop/purge/restart, the other agents untouched
• Per-branch CLI selection — use Claude on one branch and Codex on another
• Session persistence — stop and resume without losing your place
• Custom CLI support — register any AI CLI binary, not just the built-in ones
• Presets — save branch + CLI combos in config for one-command launch
• Non-interactive mode — pass --cli and --branches flags for scripting
• Dry run — preview what git-paw will do before it does it

How It Works

┌──────────────────────────────────────────────────────┐
│                    tmux session                       │
│  ┌────────────────────┐  ┌────────────────────────┐  │
│  │  feat/auth → claude │  │  feat/api → claude     │  │
│  │                     │  │                        │  │
│  │  (git worktree)     │  │  (git worktree)        │  │
│  │                     │  │                        │  │
│  ├────────────────────┤  ├────────────────────────┤  │
│  │  fix/bug → codex    │  │  refactor/db → aider   │  │
│  │                     │  │                        │  │
│  │  (git worktree)     │  │  (git worktree)        │  │
│  │                     │  │                        │  │
│  └────────────────────┘  └────────────────────────┘  │
└──────────────────────────────────────────────────────┘

Each pane runs in its own git worktree, so there are no branch conflicts. Your AI assistants work independently and in parallel.

Requirements

• Git 2.5+ (worktree support)
• tmux 1.8+
• At least one AI coding CLI installed (see Supported AI CLIs)
• macOS or Linux (Windows via WSL only)

Next Steps

• Install git-paw
• Quick Start: Same CLI Mode — get running in 2 minutes
• Quick Start: Per-Branch CLI Mode — mix different AI CLIs

Machine-Readable Docs (for Agents)

This site — https://bearicorn.github.io/git-paw/ — also publishes an agent-friendly discovery surface so an LLM can find and target the right page without crawling every chapter:

• llms.txt — an llmstxt.org-style index listing every page with a one-line summary and its absolute URL.
• sitemap.xml and robots.txt — standard crawl and discovery files.
• Per-page metadata — each page embeds a <meta name="description"> and a JSON block (title, canonical URL, section anchor ids) in its <head>, so an agent can identify a page and jump to a section from a single fetch.

These artifacts are generated deterministically from the documentation sources on every build, so they never drift from the published content.

Installation

Prerequisites

Before installing git-paw, ensure you have:

• Git 2.5 or later (worktree support)
• tmux 1.8 or later

git paw doctor checks both versions for you.

Installing tmux

macOS:

brew install tmux

Ubuntu / Debian:

sudo apt install tmux

Fedora:

sudo dnf install tmux

Arch Linux:

sudo pacman -S tmux

Install git-paw

From crates.io (recommended)

cargo install git-paw

Via 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

From source

git clone https://github.com/bearicorn/git-paw.git
cd git-paw
cargo install --path .

Verify installation

git-paw --version

You should see output like:

git-paw 0.16.0

Since git-paw is named with the git- prefix, git recognizes it as a subcommand. Both of these work:

git-paw --help
git paw --help

Shell Completions

git paw completions <shell> prints a completion script to stdout, generated from the CLI definition. Install it through your shell’s standard mechanism:

bash:

git paw completions bash > /etc/bash_completion.d/git-paw
# or, for a user-local install:
git paw completions bash > ~/.local/share/bash-completion/completions/git-paw

zsh:

git paw completions zsh > "${fpath[1]}/_git-paw"

fish:

git paw completions fish > ~/.config/fish/completions/git-paw.fish

Open a new shell (or re-source your shell config) to pick up the completions.

Platform Support

Windows (WSL)

git-paw requires tmux, which is not natively available on Windows. Use Windows Subsystem for Linux (WSL):

# Install WSL (PowerShell as admin)
wsl --install

# Then inside WSL:
sudo apt install tmux
cargo install git-paw

All git-paw features work inside WSL. Your AI CLIs must also be installed within the WSL environment.

Install an AI CLI

git-paw needs at least one AI coding CLI installed. See Supported AI CLIs for the full list. Some popular options:

# Claude Code
npm install -g @anthropic-ai/claude-code

# OpenAI Codex
npm install -g @openai/codex

# Aider
pip install aider-chat

Next Steps

• Quick Start: Same CLI Mode
• Quick Start: Per-Branch CLI Mode

Quick Start: Same CLI Mode

This walkthrough shows how to launch git-paw with the same AI CLI on all branches — the most common workflow.

Prerequisites

• git-paw installed
• tmux installed
• At least one AI CLI installed (e.g., claude)
• A git repository with multiple branches

Step 1: Navigate to your repo

cd ~/projects/my-app

Step 2: Launch git-paw

git paw

If neither your repo nor your global config has a [supervisor] section, git-paw first asks Start in supervisor mode? [y/N] — answer n (the default) for this walkthrough.

Step 3: Select branches

A multi-select list of all your branches (sorted by name) appears with type-to-filter search:

Select branches (type to filter, ctrl-u to clear, space to toggle, enter to confirm)
filter:
  [x] feat/api
  [x] feat/auth
  [ ] fix/typo
  [ ] main
> [x] refactor/db

Type to narrow the list (case-insensitive substring match), use arrow keys to navigate, Space to toggle, Ctrl-U to clear the filter, and Enter to confirm. Branches you toggle stay selected even if a later filter hides them.

Step 4: Select your mode

git-paw presents a mode picker:

CLI assignment mode:
> Same CLI for all branches
  Different CLI per branch

Select Same CLI for all branches and press Enter.

Step 5: Select your CLI

Pick which AI CLI to use on all selected branches. Detected CLIs are listed by display name, with the binary in parentheses:

Select AI CLI for all branches:
  Antigravity (agy)
> Claude (claude)
  Codex (codex)

Step 6: git-paw does the rest

git-paw now:

1. Creates a git worktree for each selected branch
2. Creates a tmux session named paw-my-app
3. Opens one pane per branch
4. Launches your chosen CLI in each pane
5. Saves the session state for later recovery

The worktrees land under .git-paw/worktrees/ (for example .git-paw/worktrees/feat-auth/) in a repo set up with git paw init, or beside the repo (../my-app-feat-auth/) when no worktree_placement is configured — see Worktree Placement. Nothing else is printed on success: git-paw attaches you straight to the session. (From a non-interactive terminal it prints Session 'paw-my-app' started in detached mode. and a tmux attach -t paw-my-app hint instead.)

You’re now inside a tmux session with three panes, each running Claude in its own worktree. Each pane’s border label shows its pane index and branch (with [broker] enabled = true, the dashboard takes pane 0 and the agents start at pane 1):

┌─── 0: feat/api ───────────────┬─── 1: feat/auth ──────────────┐
│                                │                                │
│  Claude is ready to help...    │  Claude is ready to help...    │
│                                │                                │
├─── 2: refactor/db ────────────┴────────────────────────────────┤
│                                                                 │
│  Claude is ready to help...                                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Mouse mode is enabled by default — click a pane to switch to it, or drag borders to resize.

Non-interactive shortcut

Skip all prompts by passing flags:

git paw start --cli claude --branches feat/auth,feat/api,refactor/db

What’s next

• Switch panes: Click with mouse, or use Ctrl-b then arrow keys
• Detach: Press Ctrl-b d to detach from tmux (session keeps running)
• Reattach: Run git paw attach (or git paw again — it detects the active session and reattaches)
• Stop: Run git paw stop to kill tmux but keep worktrees
• Purge: Run git paw purge to remove everything

See the User Guide for the full details.

Quick Start: Per-Branch CLI Mode

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.

Scenario

You have three branches and want to use:

• Claude for the auth feature (complex logic)
• Codex for the API work (lots of boilerplate)
• Aider for the database refactor (incremental edits)

Step 1: Launch git-paw

cd ~/projects/my-app
git paw

(If neither your repo nor your global config has a [supervisor] section, git-paw first asks Start in supervisor mode? [y/N] — answer n.)

Step 2: Select branches

Select branches (type to filter, ctrl-u to clear, space to toggle, enter to confirm)
filter:
  [x] feat/api
  [x] feat/auth
  [ ] main
> [x] refactor/db

Type to filter the list (case-insensitive substring match); selections persist across filter changes, and Ctrl-U clears the filter.

Step 3: Select per-branch mode

CLI assignment mode:
  Same CLI for all branches
> Different CLI per branch

Step 4: Assign a CLI to each branch

git-paw prompts you for each selected branch in turn (in the order they are listed above):

Select CLI for feat/api:
  Aider (aider)
  Claude (claude)
> Codex (codex)

Select CLI for feat/auth:
  Aider (aider)
> Claude (claude)
  Codex (codex)

Select CLI for refactor/db:
> Aider (aider)
  Claude (claude)
  Codex (codex)

Step 5: Watch it launch

git-paw creates a worktree per branch, opens the paw-my-app tmux session with each branch’s chosen CLI in its own pane, and attaches you to it — nothing else is printed on success.

Each pane’s border label shows its pane index and branch (with [broker] enabled = true, the dashboard takes pane 0 and the agents start at pane 1):

┌─── 0: feat/api ───────────────┬─── 1: feat/auth ──────────────┐
│                                │                                │
│  Codex is ready...             │  Claude is ready to help...    │
│                                │                                │
├─── 2: refactor/db ────────────┴────────────────────────────────┤
│                                                                 │
│  Aider v0.x loaded...                                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Comparing approaches

Per-branch mode is great for:

• A/B testing AI assistants — give the same task to Claude and Codex, compare results
• Specialization — use a code-generation-focused tool for boilerplate and a reasoning-focused tool for complex logic
• Trying new tools — test a new AI CLI on one branch while using your trusted tool on others

Recovery

Session state captures the per-branch CLI assignments. If your terminal closes or tmux crashes:

git paw

git-paw detects the saved session, recreates tmux, and relaunches each branch with its assigned CLI — no re-selection needed.

Next Steps

• User Guide — session management, presets, dry-run, and more
• Configuration — save per-branch presets in config

Quick Start: Orchestrator Mode

This walkthrough shows how to launch git-paw in supervisor mode and drive it from your own agent session, the orchestrator. Several coding agents work in parallel; the orchestrator verifies them, runs tests between merges, and publishes a final summary.

What Orchestrator Mode Does

Supervisor mode with a spec flag (git paw start --supervisor --from-all-specs) launches every pending spec as its own coding agent in a tmux pane, with the dashboard above them. (Bare git paw start --supervisor, with no spec flag, opens the interactive branch picker instead.)

The orchestrator runs outside the tmux session. No orchestrator runs inside the session. The orchestrator is your own agent session (any agent CLI you like), run at the repository root and outside tmux. It loads the exported orchestrator skill and the per-session context, then drives the run through the bundled helpers (.git-paw/scripts/sweep.sh, broker.sh) or git-paw’s MCP server. It runs the configured test_command between merges, walks branches in topological order based on declared dependencies, and publishes a final summary status when the run is complete.

It does not approve permission prompts. Whether a command runs without asking is your agent CLI’s decision, and anything it prompts for is escalated to you. For a run that proceeds without stopping, pre-approve the commands in that CLI’s own allow rules, or use agent_approval = "full-auto" inside a sandbox.

Prerequisites

• The standard git-paw prerequisites: git-paw installed, tmux, an AI CLI on PATH, and a git repo.
• [broker] enabled = true in your config. Supervisor mode requires the coordination broker.
• A [supervisor] section is recommended but optional. If it is missing, --supervisor runs on built-in defaults, and a plain git paw start asks Start in supervisor mode?. No orchestrator CLI is needed to launch: the coding agents’ CLI resolves from --cli, then default_cli, then [supervisor].cli, and the launch fails only when none of them is set.
• A specs directory configured via [specs] (default: specs/) containing at least one pending spec.

Smallest Runnable Example

1. Initialize the repository

git paw init

git paw init writes .git-paw/config.toml (asking whether to enable supervisor mode by default and, if you do, for the test command) and installs the bundled helpers under .git-paw/scripts/. It also exports two skills and adds one pointer section:

• .git-paw/skills/orchestrator/SKILL.md is the orchestrator skill, rendered with your gate commands. It is the procedure your agent follows.
• .git-paw/skills/cli-setup/SKILL.md holds the consent rules for git paw setup-cli.
• A section between <!-- git-paw-orchestrator:start --> and <!-- git-paw-orchestrator:end --> is added to your root AGENTS.md. It tells any agent reading the file that, when a git-paw session is active, it is that session’s orchestrator and should read the two files above.

Both skills follow the standard skill-directory layout (a SKILL.md with name and description frontmatter), so a skill-aware agent CLI can load them directly. Copy or symlink them into your CLI’s own skill directory if it needs them there. .git-paw/skills/ is gitignored, and git paw start re-renders both files, so they never lag your config or the binary. Re-running git paw init reports Updated only for a file whose content changed.

2. Create one OpenSpec-format spec

mkdir -p specs/add-greeting
cat > specs/add-greeting/tasks.md <<'MD'
## Add a greeting helper

- [ ] Add `pub fn greet(name: &str) -> String` to `src/lib.rs`.
- [ ] Add a unit test asserting `greet("paw") == "hello, paw"`.
- [ ] Run `cargo test` and make sure it passes.
MD

3. Configure broker + supervisor

.git-paw/config.toml:

[broker]
enabled = true
port = 9119

[specs]
dir = "specs"
type = "openspec"

[supervisor]
enabled = true
cli = "claude"
test_command = "cargo test"
agent_approval = "auto"

4. Launch

git paw start --supervisor --from-all-specs

git-paw creates a worktree for each spec and opens a tmux session. The dashboard is in pane 0 (a full-width top row). There is one coding agent per spec in the panes below it, from pane 1 onwards. The launch then prints the attach command and the two orchestrator paths:

Supervisor session 'paw-myproject' launched with 1 coding agent(s).
Orchestrator context: .git-paw/AGENTS.local.md (point your orchestrating agent session at it)
Orchestrator skill:   .git-paw/skills/orchestrator/SKILL.md
Attach with:  tmux attach -t paw-myproject

.git-paw/AGENTS.local.md is the short session context. It holds the session name, the broker URL, the helper paths, any [governance] documents and, under --unattended, the drive-loop directive, and it points at the skill. It is the only file that carries this session’s values. The exported skill carries none, so the same SKILL.md serves every session.

5. Load the skill in your own agent

Open your own agent session at the repository root, outside tmux. Have it load .git-paw/skills/orchestrator/SKILL.md and read .git-paw/AGENTS.local.md. An agent that reads the root AGENTS.md finds both through the pointer section. Over MCP, get_skill with the name orchestrator serves the same skill (supervisor is accepted as an alias).

From there the orchestrator:

1. Follows events. It blocks on the broker’s event cursor (the MCP wait_for_events tool, or .git-paw/scripts/sweep.sh events), carrying the returned cursor forward. It inspects the session when an event or a stalled wave says to look, so it never polls pane captures on a timer. get_session_status and sweep.sh status give the roster at any time.
2. Verifies. It runs the five gates against each branch that reports done. It publishes a verdict only through the credential-carrying helpers: sweep.sh verified <agent> <message>, sweep.sh feedback-gate <agent> <gate> <message> or sweep.sh conflict-ack <agent-a> <agent-b> <file>. In the root session, the MCP publish_verified and publish_feedback tools do the same.
3. Answers. It replies to a worker’s agent.question with sweep.sh answer <agent> <text> [re].
4. Merges. Once every expected agent is verified, it fast-forwards each branch in topological order, runs the test command after each merge, and announces each advance with sweep.sh advanced-main <merged-branch> <summary>. In an attended run it may confirm the merge order with you first.

When every branch has merged (or been skipped), it publishes a final agent.status summarising which branches merged and which were skipped, and why.

6. Pair it with --unattended

git paw start --unattended --from-all-specs

--unattended adds an in-process drive loop: it keeps the coding-agent panes moving and escalates every live permission prompt to the broker, approving none. Your orchestrator reads those escalations through the event surface and relays each prompt to you. It runs sweep.sh approve <pane> only when you say so. In an unattended run the orchestrator merges as soon as every expected agent is verified, without asking first. It escalates only on a conflict (a non-fast-forward branch or a dependency cycle), an exhausted correction cycle, or a regression. If the loop exits on its heartbeat, re-run git paw start --unattended to re-attach a drive loop to the still-live session.

Your driving session can itself be remote-controlled from a phone through its own agent CLI. git-paw needs no extra topology for that. See Remote control.

Authoring a Change from Your Own Agent

An orchestrator connected over MCP can write the OpenSpec change it then launches, even without file tools of its own. Repository writes are off by default; you opt in per repository:

1. Enable the switch in the repository’s own .git-paw/config.toml (the user-level config cannot enable it):

   [mcp]
   allow_repo_writes = true
   

2. Restart the MCP server at the repository root. The switch is read once at startup, and the write tools exist only for a server in the main working tree.

3. Scaffold the change with create_spec and a kebab-case name, such as add-greeting.

4. Write each artifact with write_spec_artifact: proposal.md, one specs/<capability>/spec.md per capability, tasks.md, and anything else your workflow uses.

5. Check the structure with validate_spec, and fix what it reports.

6. Run your project’s own spec validator. validate_spec checks only a subset of the rules.

7. Review git diff and commit yourself, following your project’s conventions. The tools never stage or commit.

See Spec authoring for the tools’ parameters and the confinement rules.

Skipping Supervisor for One Session

If your project sets [supervisor] enabled = true (the recommended setup for active development), every git paw start launches in supervisor mode. To skip it for a single session, pass --no-supervisor. This suits a quick debug-only run or a one-off branch flip, and you don’t need to edit the config:

# Project config says [supervisor] enabled = true, but we want a plain session
git paw start --no-supervisor --cli claude --branches feat/quick-fix

--no-supervisor is the highest-precedence step in the supervisor mode resolution chain. It wins over both [supervisor] enabled = true in config and any prompt. It is mutually exclusive with --supervisor; passing both fails at parse time.

The flag only affects the current session. Your config is untouched, so the next git paw start returns to supervisor mode as configured.

Key Config Knobs

The full reference lives in Configuration → Supervisor. The fields you will reach for most often:

[supervisor.auto_approve] and [supervisor.common_dev_allowlist] are deprecated and have no effect. They still parse so old configs load, but each file declaring them warns once. Pre-approve routine commands in your agent CLI’s own allow rules instead. See Deprecated auto-approval tables.

See Configuration → Broker for [broker] settings and Configuration → Dashboard if you want the live broker-message panel turned on.

Broker Wire Format

Every coordination message the orchestrator and its agents exchange goes through the broker as a JSON envelope. The canonical example below comes from src/broker/messages.rs. The broker accepts an agent_id of supervisor or a lowercase two-part slug: letters, digits and -, with the parts joined by - or /. git-paw itself publishes the slug form, so branch feat/auth becomes feat-auth.

{"type": "agent.status", "agent_id": "feat-auth", "payload": {"status": "working", "modified_files": ["src/auth.rs"], "message": "wiring JWT verifier"}}

Nobody hand-writes these envelopes:

• The coding agents publish theirs through .git-paw/scripts/broker.sh (status, artifact, blocked, question, intent) or the MCP publish tools.
• The orchestrator publishes through .git-paw/scripts/sweep.sh (status-publish, verified, feedback-gate, conflict-ack, learn, answer, advanced-main) or broker.sh --agent supervisor (question, intent).
• The filesystem watcher and the post-commit hook publish agent.status and agent.artifact automatically.

The rest of the message set is agent.blocked, agent.intent, agent.question, agent.answer, agent.feedback, agent.verified, agent.advanced-main and agent.learning, plus the broker-emitted supervisor.verify-now. See Agent Coordination for the full reference with payload-field semantics.

Where to Look When Things Go Wrong

When a run misbehaves, these places have everything you need:

1. Dashboard pane (pane 0). With [broker] enabled = true the dashboard runs in pane 0 of the session and updates every second. Use it to spot which agent is blocked, which is working, and how long it has been since each agent’s last status update. See the Dashboard chapter for status-symbol meanings and controls.
2. Your orchestrator session. The orchestrator runs in your own agent session outside tmux and reports there as it walks agents through the merge plan. Its broker messages also appear in the dashboard’s broker log.
3. The orchestrator’s final status. When its merge loop completes, the orchestrator publishes a final agent.status (agent supervisor). It lists which branches merged cleanly, which were skipped and why, and any regressions it hit. It shows up in the dashboard’s broker log panel.
4. <session_name>.broker.log. This plain-text audit trail has one line per message the broker handled ([<seq>] <unix-seconds> [<agent_id>] <message summary>).
   • It lives in git-paw’s sessions directory, not in .git-paw/. On Linux that is ~/.local/share/git-paw/sessions/<session_name>.broker.log (or under $XDG_DATA_HOME). On macOS it is ~/Library/Application Support/git-paw/sessions/<session_name>.broker.log.
   • The name carries the session, so two repositories each keep their own log.
   • Tail it live with tail -f to watch coordination as it happens. The file is appended every five seconds; see Agent Coordination for the message types.

To inspect an individual agent’s pane history, run .git-paw/scripts/sweep.sh capture <pane>, or tmux capture-pane -p -t <session>:0.<pane> against the session named in .git-paw/AGENTS.local.md. The agent panes are in window 0; the session’s second window, broker, hosts the broker.

Governance

If your project has existing governance docs (ADRs, DoD, security checklist, test strategy, constitution), point the orchestrator at them via the [governance] table in .git-paw/config.toml. When set, those paths are written into the session context (.git-paw/AGENTS.local.md), and the orchestrator consults each doc as a sub-step of its spec-audit step. Findings flow through the existing agent.feedback errors path, with no new wire format. See the Governance chapter for the full config, what the orchestrator checks per doc, and illustrative starting-point examples for each doc type.

What’s Next

• User Guide → Supervisor: driving the session from your own agent, in depth.
• User Guide → Remote control: driving the session from a phone.
• User Guide → MCP Server: the read and write tools the orchestrator can use.
• User Guide → Agent Coordination: broker message types and how agents talk to each other.
• User Guide → Dashboard: the dashboard pane’s status table (pane 0 in every mode with a broker), controls, and configuration.
• User Guide → Governance: pointing the orchestrator at your project’s existing governance docs.
• Configuration → Supervisor: every supervisor field with defaults.

User Guide

This guide covers the full range of git-paw features beyond the quick starts.

Starting Sessions

Interactive start

Running git paw (or git paw start) with no flags launches the interactive flow:

1. Branch selection — multi-select with type-to-filter search (type to narrow, ctrl-u to clear, space to toggle, enter to confirm)
2. Mode selection — same CLI for all branches, or different CLI per branch
3. CLI selection — single pick (uniform) or per-branch assignment

Smart start behavior

git paw start inspects the current repo and decides what to do:

You never need to think about whether to “start” or “resume” — just run git paw.

Non-interactive start

Skip prompts with flags:

# Specify both CLI and branches — no prompts at all
git paw start --cli claude --branches feat/auth,feat/api

# Specify just CLI — still prompted for branches
git paw start --cli claude

# Specify just branches — still prompted for CLI
git paw start --branches feat/auth,feat/api

Using presets

Define named presets in your config (see Configuration):

git paw start --preset backend

This uses the branches and CLI defined in the [presets.backend] section of your config.

CLI Modes

Same CLI for all branches

The default mode. Every branch gets the same AI CLI. Best for:

• Working on related features with your preferred tool
• Batch processing branches with a single assistant

Different CLI per branch

Assign a different CLI to each branch. Best for:

• Comparing AI assistants side by side
• Using specialized tools for specific tasks
• Trying a new CLI on one branch while keeping your usual tool on others

Session Management

Checking status

git paw status

Displays the current session state:

Session: paw-my-app
Status:  🟢 active
Tmux:    running

  feat/auth → claude (/path/to/my-app/.git-paw/worktrees/feat-auth)
  feat/api → claude (/path/to/my-app/.git-paw/worktrees/feat-api)
  refactor/db → aider (/path/to/my-app/.git-paw/worktrees/refactor-db)

With the broker enabled, a Broker: line shows its URL and whether it is responding. git paw status --json emits the same information machine-readably, including each worker’s cli_session_id.

Status indicators:

• 🟢 active — tmux session is running
• 🔵 paused — git paw pause detached it; CLI panes are still running
• 🟡 stopped — session state saved and tmux not running, or tmux up but every agent pane exited (git paw start recovers)
• 🔴 stale — the receipt claims active, but the tmux session is gone; git paw start self-heals it, git paw purge --stale clears it
• No session — nothing saved for this repo

Reattaching

git paw attach

Reattaches your terminal to the session running for this repository — the same as tmux attach -t paw-<project>, without needing the exact session name. It errors with a pointer to git paw start when no session is running.

Stopping a session

git paw stop

This kills the tmux session but preserves:

• Git worktrees (with any uncommitted work)
• Session state file (branch/CLI assignments)

Run git paw later to recover the session with the same setup.

Purging a session

git paw purge

The nuclear option. Removes:

• Tmux session
• All git worktrees created by git-paw
• Session state file

Requires confirmation. Use --force to skip:

git paw purge --force

Dry Run

Preview what git-paw will do without executing:

git paw start --dry-run

Or with flags:

git paw start --cli claude --branches feat/auth,feat/api --dry-run

This runs the detection, selection, and planning steps, then prints the session plan and exits without creating worktrees or tmux sessions.

Tmux Navigation

Once inside a git-paw tmux session:

Mouse mode is enabled by default, so clicking and dragging just works. You can disable it in your config.

One Session Per Repo

git-paw manages one session per repository. If you run git paw in a repo that already has a session, it reattaches rather than creating a second session.

To work with multiple repos simultaneously, open separate terminals and run git paw in each repo directory.

Shell Completions

git paw completions <shell> prints a completion script to stdout for your shell’s standard completion mechanism:

git paw completions bash > /etc/bash_completion.d/git-paw
git paw completions zsh > "${fpath[1]}/_git-paw"
git paw completions fish > ~/.config/fish/completions/git-paw.fish

See the CLI reference for the supported shells.

Session Lifecycle

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.

Reattaching instead of forking

Before creating anything, git paw start looks up whether the current repository already has a live session (matched by repository path, not by project/session name) and reattaches to it instead of launching a fresh one. This applies uniformly whether the session is a bare launch or a supervisor-mode one ([supervisor] enabled = true in config, or --supervisor) — a supervisor-enabled repo’s bare git paw start still goes through the same guard before it ever reaches the supervisor auto-start flow.

• Interactively, it attaches your terminal to the existing session — identical to running git paw attach.
• Non-interactively (no TTY — a script, a cron job, an automated scanner), there is nothing to attach to. Rather than silently printing a hint and exiting successfully — which an automated caller could mistake for “a fresh session was launched” — start refuses with an actionable error naming the live session and how to attach to it.

The -N suffix (paw-<project>-2, -3, …) is reserved for genuinely distinct repositories that happen to share a project name (their directory basename); it is never applied as a result of re-running start against a repository that already has a session running.

Rebase on start

Every git paw start rebases each existing agent branch onto the repository’s default branch (whatever origin/HEAD tracks — typically main) before opening or reopening that branch’s worktree. This keeps agents starting from current main, which matters when the supervisor (you) advances main while agents are still working on their branches.

Why this is the default:

• A supervisor session typically lands commits on main while one or more agents are running on feat/* branches. Without rebasing on start, every subsequent agent commit chains from the stale baseline, forcing a per-branch rebase at merge time.
• The rebase is cheap when there’s nothing to do: git rebase exits zero with no rewrite when the branch is already up to date.
• The branch ref is updated even in the resume case — git paw start on a session whose worktrees already exist on disk picks up the new main commits transparently.

Rebases that don’t happen:

• A brand-new branch (one git-paw creates via git worktree add -b during this launch) is not rebased. It’s already at the current default-branch tip by construction.

Resolving the default branch without origin/HEAD

The rebase target is resolved by a single resolver shared by every launch path (start, add, and the rebase step itself), so start and a later resume can never disagree on which branch is “the default”. It prefers refs/remotes/origin/HEAD (whatever your remote’s default branch is — typically main); when that isn’t set (a repository with local-only commits and no remote, or a remote whose HEAD was never configured), it falls back deterministically instead of aborting:

1. A local main branch, if one exists.
2. Otherwise a local master branch, if one exists.
3. Otherwise the currently checked-out branch.

This means a fresh launch and every subsequent resume resolve to the same default branch and neither aborts for a reason the other didn’t hit — push the default branch to origin and run git remote set-head origin <branch> if you’d rather pin it explicitly than rely on the fallback.

Opting out: --no-rebase

Pass --no-rebase when you want the pre-v0.6 behaviour — agent branches opened at their current SHA with no rebase attempt:

git paw start --no-rebase
git paw start --no-rebase --cli claude --branches feat/auth,feat/api
git paw start --no-rebase --supervisor   # combines with other flags

Use cases:

• You are deliberately working against a stale baseline (e.g. an agent is reproducing a bug on a specific historical commit).
• An external tool has pinned a pre-rebase SHA on the agent branch and rewriting history would break it.
• You’re scripting against the pre-v0.6 launch contract and don’t want the new default behaviour.

Rebase conflicts

If the rebase hits a conflict — typically because both main and the agent branch modified the same line of the same file — git paw start:

1. Runs git rebase --abort on the affected branch.
2. Leaves the branch at its pre-rebase HEAD (no half-rebased state survives).
3. Exits with an error like Error: rebase onto main failed: <git's stderr listing the conflicting files>.

When you see this error:

1. cd into the affected agent’s worktree (by default at .git-paw/worktrees/<branch-slug>/; ../<project>-<branch-slug>/ with worktree_placement = "sibling").
2. Inspect the conflicting files git named in the error.
3. Either reconcile manually (e.g. git rebase main followed by resolving conflicts and git rebase --continue), or decide the change should land via a merge commit instead.
4. Once the branch is in a clean state, rerun git paw start (with or without --no-rebase depending on what you decided).

The conflict-abort path is intentional and not configurable — leaving a branch half-rebased poisons every subsequent git operation against it, which is far worse for the agent in that pane than a clean error at launch time.

What rebase does NOT do

• It does not git fetch or git pull for main. The rebase target is whatever origin/HEAD tracks locally; the user owns the remote-sync decision.
• It does not leave a surviving worktree’s files behind its branch. The rebase runs inside the worktree that has the branch checked out, so on resume that worktree’s files move with the rebased HEAD. If git refuses the rebase there (for example, the worktree has uncommitted changes), it fails like a conflict — see above.
• It does not rebase one agent branch onto another agent branch. Only feat/<change> onto the repository’s default branch.
• It does not loop or retry on failure. One attempt, abort on conflict, surface the error.

Resume vs. fresh launch

The rebase step runs in both flows:

• Fresh launch: branch exists locally, no worktree yet. Branch is rebased onto main, then the worktree is created at the rebased SHA.
• Resume (worktree already on disk from a prior session): branch is rebased in the existing worktree, the existence check confirms the worktree is registered for that branch, and git paw start returns success with the worktree’s branch ref now pointing at the rebased HEAD.

If you’re debugging a launch and want to know whether the rebase modified anything, git rev-parse <branch> from the main repo before and after git paw start will show the SHA change (or lack thereof).

The broker host

When the broker is enabled, every launch path — git paw start, the spec-driven launch, the supervised launch, cold recovery and resume from pause — runs the broker in its own process, git paw __broker, in a detached tmux window named broker. The window sits outside the pane grid, so pane numbering is unchanged; switch to it to see the host’s output.

A launch opens the session, starts the host, and waits up to 10 seconds for it to answer before it registers the agents with it, saves the session, or sends any boot prompt. If the host exits or never answers — most often because another process holds the broker port — the launch fails with an error naming the port and saves no session, so nothing half-launched is recorded. The dashboard in pane 0 is a client of the host: it shows ⚠ broker unreachable while the host is down and reconnects on its own.

git paw pause closes the broker window (the dashboard stays); git paw stop ends the whole session, host included. Both flush the session’s broker log on the way out.

Cold recovery resumes worker context

When git paw start recovers a stopped session — including a paused session whose tmux server died, and a session still up in tmux whose every agent pane has dropped back to a bare shell (crashed CLIs) — a CLI that supports it is relaunched with its prior conversation context restored instead of starting cold. See Per-CLI cold resume for the mechanism (session-id assignment at launch, resume on recovery) and which CLIs it covers today.

A session whose panes dropped back to a bare shell reports 🟡 stopped with Tmux: running, never 🔴 stale — its tmux session is still there, so git paw purge --stale leaves it alone and start is the remedy.

A receipt that still claims active after its tmux session vanished (a crash, or a machine sleep that tore the tmux server down) is not recovered: git paw status reports it as 🔴 stale, and start clears it the way git paw purge --stale does, then launches fresh.

Adding and removing branches mid-session

Before v0.6.0 the branch set was frozen at git paw start time: changing it meant stop/purge + re-start, which destroyed every agent’s in-flight conversation. git paw add and git paw remove edit a running supervisor session’s branch set in place — the other agents keep working undisturbed.

git paw add — hot-attach an agent

git paw add feat/new-thing              # attach a worktree + 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

What it does:

1. Resolves the branch and CLI — from the positional argument, or (with --from-spec) from a spec discovered in the configured [specs] format — OpenSpec, Markdown, Spec Kit, or Superpowers (same resolution as git paw start --specs NAME). An unknown spec name errors with the discovered candidate list; an unknown --cli errors with the detected CLI ids — and in both cases nothing is created.
2. Refuses — before touching anything — a branch whose broker agent_id is already taken by an agent in the session. The id is the slugified branch name, so two different branches can map to one id: adding feat-x to a session already running feat/x fails naming both branches and the shared id feat-x, because the two agents would share one inbox. Rename the branch so the ids differ. (Only when the broker is enabled; with it off, nothing addresses agents by id.)
3. Enforces the 25-agent cap before touching anything. Adding the 26th agent fails with the same “split into multiple sessions” message start uses.
4. Creates the worktree (same naming and idempotent-create behaviour as start; re-adding an existing worktree reuses it) and attaches the agent through the same boot pipeline a start-time agent uses — the broker boot block, the sidecar spec body (.git-paw/AGENTS.local.md), and the initial prompt are byte-identical.
5. Re-tiles the agent grid to the layout a start of that many agents would have produced. Existing panes keep their indices, so any in-flight send-keys targeting (supervisor sweeps) still lands on the right pane; the new pane gets the next index. The re-tile preserves every other agent’s pane — no existing agent loses its pane — and each agent row is rebalanced to equal width, so the added grid matches a start-time grid of the same count in both pane count and pane widths. After the re-tile, git-paw reconciles the session JSON against the live panes and warns if any agent has no live pane (a JSON↔tmux desync), so it is visible and recoverable rather than silent.
6. Registers the branch in the session so subsequent status, stop, purge, and pause include it.

The new agent’s boot block is injected only once its CLI reaches an interactive ready state (the launch-readiness gate), not after a blind fixed sleep — the same protection git paw start applies.

The supervisor is not signalled directly. The new agent auto-registers with the broker (filesystem watcher + its own boot-block heartbeat) and the supervisor discovers it on its next sweep — no restart, at most one sweep-interval of latency.

Paused sessions: if the session is paused when you add, the new pane is created but its prompt is held unsubmitted — the agent stays paused with the rest of the session and begins on the next git paw start.

git paw remove — detach a single agent

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

What it does:

1. Locates the agent by branch (errors with the live-agent list if it isn’t in the session).

2. Uncommitted-work safety: refuses to delete a worktree with uncommitted changes, listing the changed files, unless you pass --force. This mirrors git worktree remove’s own safety. --keep-worktree skips the check entirely (nothing is deleted).

3. Kills the agent’s pane and re-tiles the grid for the smaller agent count so it re-flows without leaving a hole. The target pane is resolved by mapping the removed branch’s worktree to a live pane via pane_current_path and killed by its tmux pane id — regardless of the process running in it (a bare shell from a failed/never-started CLI, a CLI, or anything else). Killing by resolved pane id (not by a position computed from the session JSON) guarantees only the removed agent’s pane is closed and never a different agent’s pane, even if a stale orphan pane has shifted the grid. The re-tile preserves every other agent’s pane and rebalances each row to equal width. The branch→pane mapping for the survivors is re-derived from pane_current_path on the supervisor’s next sweep, so a mid-grid removal is safe.

4. Removes the worktree (reusing git paw purge’s per-worktree teardown) unless --keep-worktree, then drops the branch from the session.

5. Branch safety: deletes the branch only when git-paw created it and its tip is an ancestor of the default branch or of the branch it was created from, printing Deleted branch <name> (was <sha>). A branch that existed before the session is never deleted. A created branch carrying commits in neither — or one whose merge state cannot be determined — is kept after its worktree is gone, and is reported with its tip and how to pick the work back up or throw it away:

   Kept branch feat/wip at 9f8e7d6 (3 commit(s) not in main)
     resume it with: git worktree add '/path/to/worktree' feat/wip
     discard it with: git branch -D feat/wip
   

   The discard command is git branch -d when git would accept the safe delete, -D when only the forced form would work.

   --force relaxes the uncommitted-work check only; it never deletes a branch with unmerged commits.

git paw remove supervisor is refused — to end the whole session use git paw stop (or git paw purge). The supervisor notices a removed agent passively: its heartbeat stops, and the supervisor drops it from its coordination scope on the next /status poll.

Scope: add / remove operate on every live session — bare, spec-driven and supervisor-mode alike. Every session git-paw builds uses the agent grid, which is the layout that can be re-tiled incrementally for a new agent count, so dynamic branch attachment no longer depends on the session’s mode. One branch per invocation; bulk add/remove and configurable layouts are tracked for a later release.

One exception — a session started by an earlier git-paw. Bare sessions used to be laid out with tmux’s whole-window tiled layout, which cannot be re-tiled while the session runs (re-tiling it would move every running pane under you). add and remove refuse such a session before touching anything, with an error naming the tiled layout. The fix is one restart:

git paw stop     # or detach and let the session go stale
git paw start    # rebuilds the window in the agent grid layout

Recovery rebuilds the window as a grid and records it, so after that restart add and remove work on the session normally. Sessions started by this version are already grids and are never refused.

Worktree Placement

Every agent git-paw launches works in its own git worktree — an independent checkout of a branch that shares the repository’s object store. worktree_placement controls where git-paw creates that directory.

Child vs sibling

There are two layouts:

Sibling is the original (v0.7.0) layout: worktrees are created in the repository’s parent directory, beside the repo. Three agents on my-project produce ../my-project-feat-a/, ../my-project-feat-b/, and ../my-project-fix-c/ — scattered across the parent folder.

Child keeps worktrees inside the repository, under .git-paw/worktrees/. The same three agents produce .git-paw/worktrees/feat-a/, .git-paw/worktrees/feat-b/, and .git-paw/worktrees/fix-c/. This matches how tools like Claude Code keep worktrees within the project tree.

The child-layout slug comes from the branch name alone — / becomes - and characters outside [A-Za-z0-9._-] are stripped — so feat/auth-flow → .git-paw/worktrees/feat-auth-flow/ and fix/issue#42 → .git-paw/worktrees/fix-issue42/. The project name is not prepended because the directory already lives under that project’s .git-paw/worktrees/.

Why the contained layout

The motivation for child is a project-scoped permission model. An agent CLI (or an MCP client, or a sandbox profile) scoped to the repository can read and write .git-paw/worktrees/ with a single grant. A sibling worktree lives outside the repository the tool is scoped to, so it either falls outside the grant or forces a broader, less precise one. Containing the worktrees lets one grant for .git-paw/worktrees/ cover every agent.

Because child worktrees live inside the repo tree, they must be ignored so git never tries to stage them. git paw init adds .git-paw/worktrees/ to .gitignore for you. If you switch an existing repo to child by editing the config manually, add that entry yourself. Git itself handles the nested .git correctly — a linked worktree carries its own .git file pointing back at the main repository.

Placement decides what an agent CLI can find

The same containment affects what an agent’s CLI can read, not just what a grant can cover. A worktree is populated from a commit, so anything the repository gitignores — an agent CLI’s command and skill definitions at the repository root, .claude/ among them — is simply absent from it. A sibling worktree lives outside the repository, so those uncommitted definitions are invisible: an agent told to run a workflow command finds nothing and quietly improvises one instead. A child worktree sits under the repository root, so the CLI’s upward search through ancestor directories still reaches them.

Committing the definitions fixes it under either layout. git paw doctor reports which applies: its spec-workflow check warns when the command a spec-driven launch instructs cannot be reached from where your worktrees are placed.

Existing sessions are never moved

Placement only governs new worktree creation. git-paw records the concrete, absolute path of each worktree in the session it created, and resume, status, and purge all operate on that recorded path — they never re-derive it from the current worktree_placement. The consequences:

• A session created under sibling keeps resuming and purging from its sibling path even if you later flip the config to child.
• A session created under child keeps using its .git-paw/worktrees/... path.
• Flipping the config mid-project leaves a mixed layout (old worktrees stay put, new ones follow the new setting). Each worktree is still torn down correctly because the recorded path is the single source of truth at teardown time. git-paw does not migrate existing worktrees.

This makes the upgrade to v0.8.0 a no-op for existing repositories: with no worktree_placement field, the effective placement is sibling, byte-for-byte identical to v0.7.0. Re-running git paw init backfills the field — see below.

Setting it

Set it per-repo in .git-paw/config.toml or globally in ~/.config/git-paw/config.toml (repo wins on conflict):

worktree_placement = "child"   # or "sibling"

See the Configuration reference for the full field description and merging rules.

git paw init backfills the field

Re-running git paw init in an already-initialised repo backfills every missing top-level default key, worktree_placement = "child" among them. If the repo already has worktrees under the sibling layout, init prints a warning naming them, states that it did not move them, and tells you how to keep the old layout. Nothing is moved, deleted, or re-registered — the choice is yours:

• Set worktree_placement = "sibling" to pin the previous layout. Init never touches an explicitly-set value, so the pin holds on every later run.
• Or leave the backfilled "child": existing worktrees keep resuming from their recorded sibling paths, and only new ones land under .git-paw/worktrees/.

Runtime Isolation

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.

It does not, by default, isolate each agent’s runtime. Sibling worktrees read the same .env and bind the same ports, so the moment two agents start a dev server, a preview, or a debugger, the second one fails with EADDRINUSE — or worse, quietly talks to the first one’s database.

Runtime isolation fixes the three collisions that matter: the shared env file, the shared port, and — through a hook you write — the shared database. All are opt-in, configured in .git-paw/config.toml:

[worktree.env]
copy = [".env", ".env.development"]

[worktree.ports]
base   = 3000
stride = 10
vars   = ["PORT", "VITE_PORT"]

[worktree.hooks]
on_create = "scripts/paw-db-branch.sh {worktree_id}"
on_remove = "scripts/paw-db-drop.sh {worktree_id}"

With no table present, nothing changes — no files are copied, no .env.local is generated, no command runs, and worktrees are created exactly as they were before. git-paw assumes no filename, no port, and no stack; you declare what your project actually needs.

Env files are copied, not linked

Each entry in [worktree.env] copy is copied verbatim from the repository root into the new worktree, after the worktree is created and before the agent’s CLI process starts. The agent’s very first read already sees a provisioned checkout.

The copy is independent — never a symlink. That is the whole point: a symlinked .env is shared mutable state across every agent, which is exactly the silent runtime corruption worktrees exist to prevent. One agent flipping FEATURE_X=true to debug its branch would flip it for everyone. A copy diverges cleanly instead, and any drift you actually care about surfaces at merge time.

A declared file that does not exist at the repository root is skipped with a warning and the worktree is still created. Per-branch divergence is normal, and a missing optional env file should not cost you a session.

Each worktree gets its own port block

Each worktree holds a runtime slot. Its port block starts at base + slot * stride, and the Nth name in vars receives base + slot * stride + N. With the configuration above:

The assignments land in a delimited managed block in the worktree’s .env.local, the override layer most stacks load last:

# >>> git-paw (managed) >>>
PORT=3010
VITE_PORT=3011
# <<< git-paw (managed) <<<

Anything you keep in .env.local outside that block survives, and regenerating the block is idempotent. The copied .env is never touched — offset ports live only in .env.local, so .env stays a faithful copy of the source you can diff against.

Keep stride at least as large as the number of vars, with headroom for vars you add later. A smaller stride would overlap adjacent worktrees’ blocks and hand two live agents the same port; git-paw clamps the stride up and warns, but it is better to get it right in config.

Ports are deterministic, not probed

git-paw does not scan the host for free ports. A slot’s block is computed from config and the slot index, nothing else.

The trade is deliberate. Probing would dodge a busy port once, but the block a worktree gets would change from run to run — so a bookmark, a proxy rule, or a teammate’s note about “the API is on 3010” would go stale every restart. Deterministic assignment means a worktree keeps its ports for as long as it exists.

The cost is that an assigned port can still be taken by something unrelated on your machine. When that happens, change base or stride — you are picking a range for the whole session, not fighting one process.

Slots survive add/remove churn

The slot is recorded in session state rather than derived from the worktree’s position in the list. Position would be fragile: remove the middle worktree of three and everything after it shifts down, so the next git paw add would be handed a still-running agent’s ports.

Instead, a new agent takes the lowest slot no live agent holds:

$ git paw add feat/one     # slot 0 → 3000
$ git paw add feat/two     # slot 1 → 3010
$ git paw add feat/three   # slot 2 → 3020
$ git paw remove feat/two  # slot 1 is freed
$ git paw add feat/four    # slot 1 → 3010, reused

Blocks stay bounded instead of climbing forever, and two concurrently active worktrees are never assigned overlapping blocks. git paw purge releases every slot along with the session.

Session state written before runtime isolation existed loads with no slot and is assigned one the next time the worktree is provisioned, so upgrading changes nothing until you opt in.

Giving each worktree its own database

Copying an env file and offsetting a port are things git-paw can do for any project. Branching a database is not — it means a Neon API call on one stack, createdb on another, a Docker volume on a third. So git-paw does not ship a driver. It runs your command at the two moments that matter, and lets that command hand its result back through .env.local.

Two scripts, one for each direction:

# scripts/paw-db-branch.sh — called with the worktree id
#!/bin/sh
set -e
createdb "paw_$1"
psql -q -d "paw_$1" -f db/schema.sql
echo "DATABASE_URL=postgres://localhost/paw_$1"

# scripts/paw-db-drop.sh — called with the same worktree id
#!/bin/sh
dropdb --if-exists "paw_$1"

Wire them up:

[worktree.hooks]
on_create = "scripts/paw-db-branch.sh {worktree_id}"
on_remove = "scripts/paw-db-drop.sh {worktree_id}"

Now git paw start --branches feat/two creates the worktree, copies the env files, allocates the ports, then runs paw-db-branch.sh feat-two inside that worktree. The one line the script printed to stdout joins the same managed block:

# >>> git-paw (managed) >>>
PORT=3010
VITE_PORT=3011
DATABASE_URL=postgres://localhost/paw_feat-two
# <<< git-paw (managed) <<<

The agent’s app reads .env.local and talks to its own database. A migration one agent runs cannot corrupt another’s fixtures.

git paw remove feat/two (or git paw purge) runs paw-db-drop.sh feat-two in the worktree before deleting it, so the database goes away with the branch.

Anything the hook prints that is not a KEY=value line is ignored, so your script can log progress freely. Only the assignments become environment.

Make teardown idempotent

Note the --if-exists in the drop script. on_remove is best-effort by design: if it fails, git-paw warns and removes the worktree anyway, because a failed teardown must never leave you with a stranded checkout. A crash or a forced purge can skip the hook entirely.

That means your teardown script will sometimes run against a resource that is already gone, and sometimes not run at all. Write it so a second run is harmless, and reconcile leftovers out of band (a periodic sweep of paw_* databases) rather than relying on the hook alone.

By contrast, a failing on_create does stop that worktree — git-paw reports the hook’s exit status and stderr rather than handing an agent a half-built runtime.

Print secrets on stdout and diagnostics on stderr. git-paw logs only the names of the variables it merged, so a password inside DATABASE_URL never reaches a log line — but a failing hook’s stderr is shown. And since the value lands in a plain .env.local, make sure that file is gitignored.

A hook is an arbitrary command from your config file, run with your privileges — the same trust model as a custom CLI’s command. git-paw never builds one from anything an agent or the network supplied.

Checking it worked

After starting a session, look inside any agent’s worktree (under .git-paw/worktrees/ by default — see Worktree Placement):

$ cat .git-paw/worktrees/feat-two/.env.local
# >>> git-paw (managed) >>>
PORT=3010
VITE_PORT=3011
# <<< git-paw (managed) <<<

If .env.local is missing, [worktree.ports] is absent or its vars list is empty and no hook printed an assignment. If a declared env file is missing from the worktree, check the warning git paw start printed — the file probably does not exist at the repository root. If a hook key is missing, check that the script prints it on stdout in exact KEY=value form.

See also

• Configuration — the full [worktree.env] / [worktree.ports] / [worktree.hooks] key reference
• Worktree Placement — where the worktrees themselves are created

Security Posture

This is the single, authoritative statement of git-paw’s trust model. Read it before trusting git-paw with autonomous execution. It is deliberately blunt about what the tool does and does not protect.

What git-paw runs

git-paw launches AI coding agents — arbitrary programs — in tmux panes on your machine, each in its own git worktree. Under supervisor/unattended mode (and whenever you point an agent CLI at a skip-permissions or full-auto flag), those agents execute arbitrary code with your user’s privileges: they run your build, your tests, shell commands, and anything else the model decides to run, often without pausing for per-command approval.

The blast radius is your user account. An agent — whether malicious, prompt- injected, or simply mistaken — can by default read and write anything your user can: your whole home directory, your SSH keys, your cloud credentials, your other repositories, and your login keychain. git-paw does not change your OS’s permission model; it automates running code within it.

git-paw decides nothing about your agent’s commands

git-paw makes no safety judgement about a command an agent asks to run, and it approves no permission prompt on its own. It has no safe-command list, no danger list, and no path-based safety rule. There is no command classifier.

Whether a command runs without a prompt is decided entirely by the agent CLI’s own permission system — the permission mode git-paw launches it with, plus whatever allow and deny rules you have configured in that CLI. Anything the CLI decides to ask about is a prompt, and every prompt is answered by a human.

What git-paw does is narrower, and it is the part it can do honestly: it detects that a pane is sitting on a live permission prompt and gets that prompt in front of you — on the broker, in the exit summary and in the manual-decision log — without stalling the rest of the wave. Under git paw start --unattended every live prompt is escalated this way. Approval keystrokes reach a pane only when a human explicitly runs sweep.sh approve <pane>, which answers once with option 1 and refuses an option 1 that would grant a durable “don’t ask again” permission.

No LLM process runs at the repository root inside a session. A supervised session holds only the dashboard and the coding agents, each confined to its own worktree; the orchestrator runs in your own agent session, under the permission mode you chose for it, and git-paw launches it with no flags. Every git-paw keystroke sender — sweep.sh approve, and the drive loop’s nudges, stale-input recovery and buffered-input submits — follows one role-based rule: keystrokes reach only a pane resolved as a coding agent (by the session’s discovery roster for the helper, by the recorded layout and the pane’s owning worktree for the loop). The dashboard and any pane no agent worktree owns are refused, whatever their index.

Earlier versions did decide. Up to and including v0.16.0, git-paw ran a command classifier that answered prompts it judged safe, often choosing the “Yes, and don’t ask again” option. Your agent CLI persisted those choices as durable permission grants in its own settings file — for Claude Code that is the repository-root .claude/settings.local.json, which every worktree and every one of your own sessions shares. Retiring the classifier stops new grants being created; it removes none of the existing ones. Review that file (and any user-level equivalent) and delete grants you did not intend. git-paw never edits or deletes it.

What the controls do — and do not — guarantee

git-paw’s controls are the ones below. None is a complete sandbox on its own; each narrows one specific risk. Do not read any of them as “the agent is now safe.”

Two things that used to appear in this table are gone, and should not be relied on: git-paw’s auto-approve classifier and its command allowlist ([supervisor.auto_approve], [supervisor.common_dev_allowlist]) are retired — both tables still parse so old configs load, but they have no effect and warn. The protected-paths and .git/-write rules existed only to stop that classifier approving such a write; with nothing approving automatically, those prompts reach you like any other. To enforce those boundaries mechanically, use deny rules in the agent CLI’s own settings, or the sandbox.

Writing into an agent CLI’s settings

git-paw writes a permission rule into an agent CLI’s own settings in exactly one circumstance: you ran git paw setup-cli. Running it is the consent. No other command, process or interface does it — not start, add, init, session recovery, the drive loop, the dashboard, or any tool exposed over MCP.

What it may write. For claude, one file: <main checkout>/.claude/settings.local.json, plus one anchored line in the repository’s shared info/exclude when the target is not already ignored. Never a file inside a worktree, never a user-level file, never the configured [clis.<name>].settings_path.

The grant. Twelve allow entries naming git-paw’s own helper scripts by relative path and fixed subcommand, from a compiled table. Nothing is derived from a command argument, your configuration or your repository content. No entry names curl, an interpreter, an absolute path or a directory wildcard. The keystroke-sending and verdict-publishing subcommands are deliberately excluded, and sweep.sh approve is pinned to an ask rule so it always reaches a human. The twelfth entry, sweep.sh events, is a pure read of the broker’s log and status — no keystroke, no verdict. See the full table in Per-CLI Setup.

An applied grant is never rewritten for you. When a release adds an entry to the table, a file applied under an earlier version keeps the entries that version wrote; git-paw changes nothing behind your back. git paw doctor reports the applied setup as out of date, and the remedy is explicit and yours: git paw setup-cli claude --undo, then git paw setup-cli claude --allowlist. Until then the new subcommand prompts like any ungranted command.

The tamper threat, and the mitigation. A granted helper runs without a prompt, and it lives inside the agent’s own worktree. In an edit-accepting mode the CLI would apply an agent’s edit to that script without asking, after which the grant runs whatever the agent wrote — arbitrary code, unprompted. A quieter variant: the helpers read .git-paw/config.toml, so an edited broker address turns a granted publish into exfiltration.

So the allowlist item never writes the grants alone. In the same file and the same replacement it writes Edit(**/.git-paw/scripts/**) to deny and Edit(**/.git-paw/config.toml) to ask. Both were confirmed against the installed CLI before the item shipped — including that the deny rule also blocks the filesystem commands the edit-accepting mode auto-approves (sed -i, cp, mv, rm, touch, and cd-prefixed forms), and that it covers both the Edit and the Write tool, at any depth, from a worker’s directory and from a root session reaching into a worker’s copy.

The gate. An item is written only when its facts have been verified against an installed copy of that CLI. An unverified item can be planned with --dry-run but never written. The claude allowlist item ships verified against Claude Code 2.1.220 (2026-10-15); git paw doctor reports the current status.

Residual risks. These remain even with the item applied:

• An agent CLI other than the one with a fact row has no row, so nothing is written for it — and nothing is pre-approved.
• A separately installed MCP server or other tool that writes files outside the CLI’s permission system is not governed by these rules.
• In bypassPermissions / full-auto, the grant adds no privilege because nothing prompts — but the protection rules buy nothing either. Do not pair the allowlist with those modes outside the sandbox.
• In the CLI’s own auto mode, its classifier decides edits.
• broker.sh --agent <other> can publish under another agent’s id. That is pre-existing; broker-side identity is a later release. Verdict publishing is deliberately not granted.
• A write by the CLI itself (a “don’t ask again” approval) landing between git-paw’s re-read and its rename would be lost. git-paw detects the change and stops rather than clobbering it, but prefer to run setup when no session is waiting on an approval.

A grant is not a safety judgement. git-paw decides nothing about your prompts. Whether a call runs without one is decided entirely by the agent CLI’s own permission system and the rules in its settings. git paw doctor additionally lists the broad allow rules already in that file, so you can see what earlier “don’t ask again” answers left behind — it reports them and never edits them.

Self-approval residue

One shape of leftover grant deserves naming on its own, because it undoes the single most important distinction the grant table draws.

The allowlist item grants sweep.sh per subcommand, and withholds approve, verified, feedback-gate and conflict-ack precisely because the target settings file reaches every session in the repository — a worker’s as much as the orchestrator’s. A durable allow rule naming one of those subcommands, or a whole-script Bash(.git-paw/scripts/sweep.sh *) wildcard that covers them all, hands every agent session exactly what was withheld: it can press the approval keystroke in another pane, or publish a supervisor verdict, without a prompt. An agent can then approve its own permission prompts and sign off its own work.

Such a rule is not something git-paw writes. It arrives from a “don’t ask again” answer — including ones the retired classifier accepted on your behalf up to v0.16.0 — or from a broad rule added by hand. git paw doctor now reports it, in the project CLI grant residue check, alongside a blanket curl grant and the inert allowed_bash_prefixes seed earlier versions wrote. See Doctor.

Removing it is manual by design. git-paw never rewrites or deletes a grant it did not write: it cannot prove the rule is not one you meant to add, and a tool that edits your permission rules on its own is the thing this whole section exists to rule out. Doctor names the file and the entry; the deletion is yours.

Hook bypass and tmux driving

Two things an agent session can do with ordinary commands step around git-paw’s own safeguards, and both have been seen in practice:

• Bypassing git-paw’s git hooks. git-paw’s hooks guard each agent’s branch and report its commits. A per-invocation override such as git -c core.hooksPath=…, or git commit --no-verify (-n), silently skips them — the branch guard and the commit report go with it.
• Driving tmux. tmux send-keys, tmux run-shell and tmux pipe-pane reach into the session’s panes from outside the agent’s CLI. Keystrokes sent that way can answer a permission prompt — the agent’s own included — and so bypass the human and the orchestrator entirely.

The bundled coordination skill tells every agent plainly not to do either. An instruction is not a control, though, and git-paw adds no permission rule for these commands: it pre-approves only its own helper workflow (setup-cli writes rules naming git-paw’s helper scripts and nothing else), and every other permission decision belongs to your agent CLI and to you. That is the same line the v0.17.0 classifier retirement drew.

If you want these forms to prompt — or to be refused outright — add your own ask or deny rules to your agent CLI’s settings, for example ask rules for git -c …, … --no-verify and the tmux verbs above. git-paw never writes them, never edits them, and never removes them. Like any rule matched on a command’s text, they are a speed bump against the natural forms rather than a boundary; the sandbox is the boundary.

Browser exposure — the broker’s Host and Origin guard

The coordination broker is an HTTP server on your loopback interface (127.0.0.1:9119 by default) and it authenticates nothing: any client that reaches the port can read GET /log — the whole session’s coordination traffic — and POST /publish any message, including an agent.answer or agent.feedback that coding agents read as authoritative guidance. Whatever those agents are allowed to run without asking — under a permissive CLI permission mode, or full-auto — a request that reaches the broker is a prompt-injection channel into a shell.

A web page you open in a browser can reach a loopback port through DNS rebinding: the attacker’s hostname re-resolves to 127.0.0.1, so the page becomes “same-origin” with http://<attacker-host>:9119 and its requests go to your broker. To block that, the broker checks two headers on every request, before routing — so the check covers every endpoint, including the 404 and 405 fallbacks and any endpoint added in a later release:

A refused request gets 403 with {"error":"forbidden host"} or {"error":"forbidden origin"}, is not routed, and changes no broker state.

No git-paw client is affected. The bundled broker.sh and sweep.sh helpers, the post-commit git hook, the Rust HTTP clients used by the CLI, the MCP server and the dashboard all address the broker by its configured http://<bind>:<port> URL and send no Origin.

The non-loopback exception

If you set [broker] bind to 0.0.0.0 or a LAN address, git-paw cannot enumerate the names your network uses for the machine, so the Host check is disabled. Two things follow, and the second is easy to get wrong.

First, the broker is reachable from your network by any host, with no authentication at all — a far larger exposure than the one this guard addresses.

Second, a non-loopback bind does not keep browsers out. The Origin check still blocks browser writes and cross-origin reads: browsers attach Origin to every POST, and to any cross-origin GET made in CORS mode (fetch defaults to it, as does XMLHttpRequest). A cross-origin GET made in no-cors mode sends no Origin, but the browser hands the page an opaque response it cannot read, so that is not a way out either.

A DNS-rebinding page, though, is same-origin with the broker once the attacker’s hostname re-resolves to your machine. A same-origin GET carries no Origin header at all, and its response is fully readable — so with the Host check off, fetch('/log') from that page is served and the page reads it. The same goes for /status and /messages/*. Only a loopback bind stops a rebinding page from reading the coordination log.

Every command that brings the broker up prints a warning on stderr naming the bind address: git paw start (including --from-specs), the supervisor launch, a recovery of a stopped session, and a resume from pause. The broker process prints it too, but into the dashboard pane, which switches to the alternate screen moments later. Do not expose the broker this way on a network you do not control.

This is not authentication

The guard distinguishes browsers and foreign host names from local processes. It does not authenticate anybody. Any process running on your machine can still reach the broker, publish any message, and read the whole log — including an agent that has gone off the rails, and any other software running as your user.

That includes pages: any page served from a loopback origin is accepted — http://localhost:3000, or any other port — so a local development server you are running, or a cross-site-scripting flaw in a page it serves, can reach the broker from the browser on both a loopback and a non-loopback bind. The guard excludes foreign origins, not all browser code.

If you need the broker to be unreachable by local processes, that is a containment problem; see the FS-scoped sandbox, and do not rely on this guard for it.

Migration: reverse proxies

A reverse proxy that forwards the original external Host to the broker gets 403. Configure it to rewrite Host to a loopback name (for nginx, proxy_set_header Host 127.0.0.1:9119;), or have clients address the broker directly. Tunnels and port-forwards need no change — they already present a loopback Host.

Broker verdict authority

Two broker messages carry the root session’s authority: agent.verified, which authorises a branch to merge, and agent.feedback whose from is the root identity supervisor, which the drive loop’s correction loop treats as a gate verdict. The broker accepts these only with the per-session authority credential that only the root session holds, sent in the X-Paw-Authority request header. Without it — or with a wrong value — POST /publish answers 403 {"error":"authority required"} and changes no broker state. An agent.status or agent.artifact that claims the verified status for a worker is treated as a verdict too, since the roster would otherwise mark the branch verified from it. The comparison is constant-time, and the message body (the wire envelope) is unchanged: the credential travels only in the header.

Where the credential lives. A broker-enabled git paw start mints 32 bytes of OS randomness (64 hex characters) per session and stores them in the user-data session file — under the platform data directory, outside the repository and so outside every worktree — which git-paw writes owner-only (0600). The launcher hands the same value to the broker host through a one-shot 0600 file next to it, which the host removes once read. It is never on a command line, in the environment, in a pane, or in a log, and it never appears in the per-repo discovery file, GET /status, GET /log, git paw status --json, MCP get_session_status, or the broker log. A session saved by an earlier git-paw gains a credential the first time recovery or a restart from pause starts its broker host.

Who carries it. Only root-side publishers:

• the unattended drive loop, for its own branch-refresh notification;
• the sweep.sh verdict verbs verified, feedback-gate and conflict-ack, which fetch it through the hidden git paw __authority subcommand — which refuses to run from a linked worktree.

A root session’s MCP server (one started in the main working tree) offers publish_verified and publish_feedback, which carry the root credential read from the same session file. A worktree session’s MCP server has no verdict tool.

A headless orchestrator one-shot is not handed the credential: it publishes a verdict only through those root-side paths — the sweep.sh verbs or a root session’s MCP verdict tools — like any root-side helper.

The worker-side broker.sh has no credential-bearing verb.

Threat model. The rule stops a mistaken or skill-misled worker — one following a stale example, or an LLM that decides its own work is verified — and a rogue worker sandboxed with home-directory reads denied: the sandbox’s Tier 2 (deny $HOME), or a Tier 1 blocklist that covers git-paw’s data directory (~/Library/Application Support/git-paw on macOS, $XDG_DATA_HOME/git-paw — by default ~/.local/share/git-paw — on Linux). The default sandbox profile confines writes only, so it does not hide the credential. A worker with home-directory read access is out of this rule’s threat model, whether it runs unsandboxed or under the default profile: it can read the credential, and keeping it out is the job of the sandbox’s read-confinement tiers.

What stays ungated. Every non-verdict message is accepted without the credential, as before — including agent.status, even one that claims the supervisor identity, which can wind down the drive loop’s wave early. Feedback from any other sender (the post-commit branch-guard hook, a person) is not a verdict and stays ungated, and so does one agent publishing a non-verdict message as another. Messages the broker’s own subsystems publish in-process (the conflict detector, the role guard) never cross HTTP and are not gated.

The headless orchestrator one-shot

Under --unattended, the drive loop can hand a judgment call — an ambiguous question, a merge decision, a correction-exhausted branch — to the orchestrator CLI, run once and non-interactively at the repository root. Its permission level is [supervisor] approval (falling back to agent_approval), and nobody is present to answer its own prompts.

• full-auto here is an unattended agent with root-level write access for up to [supervisor.escalation] timeout_seconds (default 30 minutes). It is the power the old orchestrator pane had, without its interactive surface: bounded by the timeout (which kills the whole process group), serialized to one invocation at a time, and logged to .git-paw/logs/<session>/orchestrator-escalations.log, with each outcome published on the broker. Run it inside the sandbox.
• Under full-auto the ask rule on sweep.sh approve does not apply. git paw setup-cli puts sweep.sh approve on ask so a human sees every approval; a skip-permissions turn consults no rule. The one-shot’s framing, which forbids running sweep.sh approve or answering any permission prompt, is then the only guard — an instruction, not a control. Permission prompts never enter its context: the loop never hands one off, so the one-shot has no prompt in front of it to be talked into approving.
• Under auto it cannot sign off work — with the built-in mapping. For claude, auto resolves to --permission-mode acceptEdits; with the setup-cli grants the verdict verbs (sweep.sh verified, feedback-gate, conflict-ack) are never granted, so a non-interactive turn is denied them and a merge decision stays on the broker for you. This does not hold for a custom CLI or wrapper that pins its own permission mode: its one-shot can do whatever that mode allows.
• Prompt injection from worker-written text is the residual risk. A question, artifact status or branch detail is text a coding agent wrote, and the context quotes it. It is fenced between markers as data, and the framing forbids acting on instructions inside it or verifying, merging or publishing a verdict because it asks — but that is an instruction to a model, not a control. Under full-auto, or a CLI wrapper with a permissive mode, a one-shot runs at the repository root where git paw __authority hands it the credential, so injected text could steer it into a self-verify and a merge. Run full-auto inside the sandbox.
• One pending question per agent. A worker publishing many distinct questions queues one one-shot at a time; the rest stay on the broker and are counted in the exit summary, so it cannot buy an LLM run per question.
• No secret reaches it. The escalation context goes on stdin, never on argv (nothing in ps), and the environment adds only GIT_PAW_BROKER_URL; the authority credential is never on its command line or in its environment.
• Interrupting git-paw does not stop it. The one-shot runs in its own process group, so Ctrl-C or a closed terminal reaches git-paw but not the one-shot, and its timeout is enforced by the drive loop, which is then gone. The escalation log records each one-shot’s pid, which is also its process group id; kill that group by hand. A session torn down under a running loop kills it.
• Its background processes outlive a normal exit. The whole group is killed on timeout or teardown, but when the one-shot exits on its own, any process it left running in the background keeps running.

Set [supervisor.escalation] enabled = false to keep every judgment call on the broker for a human.

MCP repository writes

The MCP server’s spec-authoring tools (create_spec, write_spec_artifact) are its only tools that write file content into the repository. MCP input is untrusted, because the orchestrator calling them may have been prompt-injected by content it read. These are the guarantees:

• Off by default, and only the repository can consent. The tools exist only when the repository’s own .git-paw/config.toml sets [mcp] allow_repo_writes = true. The user-level config, environment variables and tool arguments cannot enable them, and no tool has a parameter that grants consent. The server reads the switch once at startup and logs whether writes are enabled.
• Root session only. A server in an agent’s worktree never lists or runs them, whatever that worktree’s config says.
• Confined to the change directory. Lexical checks refuse an absolute path, a .. or .git component, and a change that is not one kebab-case segment. Canonical checks refuse a spec directory outside the repository, inside .git, at the repository root or inside .git-paw, a symlinked directory leading out of the change directory, and a symlinked target file. The spec directory comes from the repository’s own [specs] section only, never the user-level config. So writes land only inside change folders under the repository-configured spec directory, and never in .git or .git-paw. Where that directory points is the repository’s choice: set to .github or src, its “change folders” are CI or source directories. Content is written to a temporary file and renamed into place.
• No process, no commit. No tool spawns a process (validate_spec checks in-process), and nothing is staged or committed. git status / git diff and one server-log line per write record what was authored.

The limit. The switch is a file in the repository, so anything that can edit the root’s .git-paw/config.toml can turn it on. That includes an unsandboxed worker writing outside its worktree, or a merged branch that carries the key. The change shows up in the diff a human reviews and in the server’s startup log line, and the sandbox confines a worker’s writes to its worktree. Against an unsandboxed rogue worker, though, the switch is no defence, as with broker verdict authority. Likewise, a local process that can already write inside the change directory could swap a directory that was just checked for a symbolic link before the write lands. That is out of scope for the same reason: it already has write access.

The bottom line

• Treat every agent as capable of running arbitrary code as you.
• git-paw decides nothing about an agent’s commands and approves no prompt. What runs without asking is your agent CLI’s decision, from the rules you gave it.
• A CLI allow rule reduces friction; it is not containment. A full-auto level removes the prompts altogether.
• For containment, use the optional FS-scoped sandbox — and understand precisely what it does (writes) and does not (reads, by default) protect.
• If you ran v0.16.0 or earlier, audit your agent CLI’s settings file for durable “don’t ask again” grants the retired classifier accepted on your behalf. git paw doctor names the known-dangerous ones — above all a sweep.sh rule that lets an agent approve its own prompts — but removing them is yours to do.
• Run untrusted or aggressive automation on hardware, accounts, and repositories whose compromise you could tolerate.

git paw doctor prints a pointer to this page and reports whether your OS’s sandbox backend is available.

Remote Control

You can drive a git-paw session from a phone or another device. The orchestrator is your own agent session, so if that session can be remote-controlled, the whole run can be steered from anywhere. This chapter covers how.

The topology

phone / browser ──(the agent CLI's own remote control)──▶ your driving agent session
                                                            (local machine, repo root,
                                                             git-paw MCP server attached)
                                                                    │
                                                                    ▼
                                                     git-paw session (tmux: dashboard
                                                     at pane 0, coding agents from pane 1)

• The driving session runs on your local machine, at the repository root and outside tmux. git-paw’s MCP server is attached to it, and it has loaded the orchestrator skill (.git-paw/skills/orchestrator/SKILL.md) and the session context (.git-paw/AGENTS.local.md).
• You remote-control that session through the agent CLI’s native remote-control feature. Your phone is only a view into the local session. The session’s files, MCP servers and tools stay on the machine.
• The driving session drives git-paw the way it does when you sit at the keyboard. It uses the bundled helpers (.git-paw/scripts/sweep.sh, broker.sh) and the MCP tools: wait_for_events and get_session_status to follow the run, and, in the root session, start_session, pause_session, stop_session, purge_session, publish_verified and publish_feedback.

git-paw ships no bridge, tunnel or network transport of its own. The remote channel belongs to the agent CLI vendor, and git-paw opens no port for it. Pair the driving session with git paw start --unattended so the coding agents keep moving while you are away. Each permission prompt the drive loop escalates reaches you through the driving session, and you answer it from the phone.

Which agent CLIs can be the remote-controlled driving session

Last checked: 2026-10-29. These are third-party facts that change quickly; check the vendor’s current documentation before relying on a row.

A CLI without native remote control can still drive git-paw locally. git-paw does not build a bridge to make it remote-controllable.

Caveats

• The local process must stay running. The remote control is a view into a process on your machine. If the machine sleeps, loses its network or the process exits, the remote session stops with it. An outage of roughly ten minutes ends the remote session (Claude Code’s documented timeout; other vendors behave similarly), and you have to restart it locally. Keep the machine awake for long runs.
• Secure the channel yourself. Remote control extends the blast radius to whoever can reach that channel. Treat your vendor account and its sessions as access to your repository. See Security posture.
• Remote approval is still your approval. The orchestrator relays every escalated permission prompt to you, and runs sweep.sh approve only when you say so, whether you are at the keyboard or on your phone.

See also

• Quick Start: Orchestrator Mode: init, start, load the skill, follow, verify, merge.
• MCP Server: the read and write tools the driving session uses.
• Supervisor → Driving the session from your own agent.

Per-CLI Setup

git paw setup-cli is the one command that writes into an agent CLI’s own settings file. Running it is the consent.

Agents call git-paw’s bundled helper scripts constantly — to publish status, poll for messages, capture panes. Under most agent CLIs every one of those calls raises a permission prompt. setup-cli lets you pre-approve exactly those calls, in the CLI’s own allow rules, once.

Setup is consent-only

Nothing else in git-paw writes an agent CLI’s settings. Not start, not add, not init, not session recovery, not the drive loop, not the dashboard, and no tool exposed over MCP. Earlier versions of git-paw tried to seed permissions automatically; that was removed, and it is not coming back under a different name.

Everything the command does is therefore gated:

• it prints its plan before anything is written;
• it writes nothing without --yes or your confirmation on a terminal;
• it records every entry, so it can take back exactly what it added;
• it refuses to run from a linked worktree, so a coding agent in a worktree cannot run it by accident.

What it writes, and where

For claude, the allowlist item targets exactly one file:

<main checkout>/.claude/settings.local.json

That one file is enough. Claude Code reads the settings file at the repository root even when the session starts in a subdirectory or in a linked worktree — which is what the change’s fact gate confirmed against the installed CLI. So a single write covers your root session, every agent worktree nested under .git-paw/worktrees/, and every session you start later, including worktrees that do not exist yet.

git-paw never writes a settings file inside a worktree (that would put the file inside the agent’s own reach), never writes a user-level settings file, and never writes the path you configured as [clis.<name>].settings_path.

If the file is not already ignored by git, the plan also adds one anchored line to the repository’s shared info/exclude, so a file git-paw created does not show up in your git status.

The grant table

The allow entries are a fixed table. Nothing is derived from a command argument, from your configuration, or from anything in your repository — two differently configured repositories plan byte-identical entries.

That is twelve allow entries in total.

Each entry names the helper by its relative invocation path, like Bash(.git-paw/scripts/broker.sh *). No entry names an interpreter, an absolute path, a directory wildcard or curl.

sweep.sh events is granted — as Bash(.git-paw/scripts/sweep.sh events *) — because it only reads the broker’s log and status to serve the event long poll. It sends no keystroke and publishes no verdict.

What is withheld, and why:

• docs-fetch.sh get takes an absolute http(s):// or file:// URL. It is a read-anywhere and exfiltration primitive; find only fetches the one configured index.
• sweep.sh approve presses keys in another pane. It also gets an explicit ask rule, so it prompts even if some broader rule of your own would otherwise allow it.
• sweep.sh verified and feedback-gate publish supervisor verdicts, and conflict-ack writes feedback into other agents’ inboxes. The target file reaches worker sessions as well as the supervisor’s, so granting these would let a worker forge its own verification or tell a peer a conflict was cleared.
• sweep.sh answer and advanced-main publish with supervisor authority: an answer is authoritative guidance to another agent, and a main-advance event makes the drive loop rebase worker branches. Granting either would let a worker forge one without a prompt.
• sweep.sh classify is on its way out with the command classifier. It is listed as withheld so the guard that requires every subcommand to be explicitly granted or explicitly withheld keeps passing while it still exists.

The protection rules

A granted helper runs without a prompt, and it lives inside the agent’s own worktree. Without protection, an agent could edit the script and have the grant run whatever it wrote. So the allowlist item never writes the grants alone — it writes these in the same file and the same replacement:

The fact gate confirmed both against the installed CLI, including that the deny rule also blocks the filesystem commands acceptEdits auto-approves (sed -i, cp, mv, rm, touch, and cd-prefixed forms). git paw doctor additionally warns when a granted helper no longer matches the copy the binary bundles.

Using it

# See exactly what would be written. Writes nothing.
git paw setup-cli claude --allowlist --dry-run

# Apply it, with a confirmation on a terminal.
git paw setup-cli claude --allowlist

# Apply it without asking (scripts, CI).
git paw setup-cli claude --allowlist --yes

# Take back exactly what git-paw added.
git paw setup-cli claude --undo --yes

Run it from the repository’s main checkout. At least one of --allowlist, --trust, --hooks or --undo is required.

--trust and --hooks exist so the flag surface will not change when later releases add those facts. Today no CLI declares them, so they report “not supported” and write nothing.

Re-running after an upgrade

git-paw never rewrites recorded grants itself. When a release adds an entry to the grant table — sweep.sh events is the v0.18 example — a file you applied under an earlier version keeps exactly the entries that version wrote. Nothing updates it in the background.

git paw doctor notices and reports the applied setup as out of date, naming how many entries this version would also write. It judges that against your CLI’s settings file rather than against git-paw’s record, so an entry you already held yourself counts as applied — see the per-CLI setup checks. The remedy is to take back what git-paw wrote and apply the current table:

git paw setup-cli claude --undo
git paw setup-cli claude --allowlist

Until you do, the new subcommand simply prompts the way any ungranted command does — nothing breaks, you just answer a prompt.

Undo

--undo removes an entry only when it is still present, still byte-equal to what was recorded, and still of a shape the item produces. Anything else — an entry you edited, an entry someone added to the record by hand — is reported and dropped from the record, never removed from your file. The protection rules stay as long as any allow entry still names a path under .git-paw/scripts/, including one you added yourself.

Undo removes entries, not containers: an allow/ask/deny list that setup created and undo emptied is left in place, empty. An empty list grants nothing, and removing it would mean touching something git-paw cannot prove it created.

A file git-paw created is deleted only when nothing but its own skeleton is left; if you added a key of your own, the file stays.

Upgrading from 0.17.0 or earlier

If you applied the allowlist on an earlier release and git paw doctor told you the applied allowlist was out of date — straight after applying it, with an --undo and re-apply remedy that never cleared the warning — that is fixed. Setup skips a planned entry your settings file already holds and records only what it wrote, and doctor used to compare its plan against the record alone, so any entry you already had read as permanently missing. Doctor now judges the plan against the settings file, so an entry you already had counts as applied and the undo/re-apply round trip converges. Nothing about what setup writes, what it records, or what undo removes has changed.

Doctor also reports grant residue now: durable rules left in the project’s CLI settings by earlier versions or by earlier “don’t ask again” answers — a blanket curl grant, a sweep.sh rule covering a subcommand the table above withholds, or the inert allowed_bash_prefixes seed written before v0.16.0. git-paw does not rewrite a grant it did not write, so those must be removed by hand. See Doctor.

Verified and plan-only

Each item carries a verification status: whether its facts — the target file, the key paths, the entry forms, and the protection the entries rely on — were confirmed against an installed copy of that CLI.

• Verified: the plan can be applied.
• Plan-only: --dry-run still prints the plan, but writing is disabled and the command exits 2. --undo keeps working, so entries written by an earlier version can still be removed.

The claude allowlist item ships verified, against Claude Code 2.1.220 (2026-10-15). git paw doctor reports the current status.

Claude Code variants (a wrapper binary registered under another name) are covered by git paw setup-cli claude: the target settings file belongs to the repository, not to the binary.

The record

Every entry git-paw writes is recorded at:

<git-common-dir>/git-paw/cli-setup.json

It lives in the git directory, so it can never be committed, never shows up in any worktree’s git status, and is shared by every worktree of the repository. It is written owner-only, and an entry is recorded before it is written — a crash in between leaves a recorded entry that is not on disk, which undo simply drops.

Residual risks

Read these before applying the item:

• Prefer the FS-scoped sandbox. The allowlist reduces prompts; the sandbox bounds what a process can reach at all. They are complementary, and the sandbox is the stronger control.
• Do not pair the allowlist with full-auto outside a sandbox. In a mode where nothing prompts, the protection rules buy you nothing, because everything else is unprompted too.
• Undo it when you no longer want it. The grant reaches every session in the repository, including ones you start much later.
• Undo before downgrading. Entries already written stay in your file after a downgrade, and an older git-paw does not know how to remove them.
• Run setup when no session is waiting on an approval. The CLI writes to the same file when you answer “don’t ask again”; a write that lands between git-paw’s re-read and its rename would be lost. git-paw detects the change and stops rather than clobbering it.
• A grant is not a judgement about safety. git-paw decides nothing about your prompts. What runs without one is decided entirely by the agent CLI’s own permission system and the rules in its settings.

See also: Security Posture and Doctor.

FS-Scoped Sandbox

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. It bounds the blast radius of a full-auto agent: writes are allowed inside the worktree and denied outside, enforced by the kernel.

The sandbox is your own local configuration. git-paw does not invoke or generate it, and does not ship a maintained profile. It launches whatever [clis.<name>].command names; you point that at a small wrapper that execs the real CLI under the sandbox. Everything below is a worked example to copy and adapt to your CLI, OS, and stack — not a drop-in git-paw ships.

The sandbox confines writes. By default it does not restrict reads — see Confidentiality hardening — and it does not cover network or resource-exhaustion. Read the Security Posture first.

How it hooks in

git-paw already gives a wrapper everything it needs at launch: the pane’s working directory is the worktree, and GIT_PAW_BROKER_URL is in the environment. So a wrapper derives its scope from $PWD with zero git-paw changes.

The wrapper must be a PATH-resolvable executable. git-paw launches a custom CLI by its name on PATH — not by an arbitrary script path. Put your wrapper on PATH (e.g. symlink it next to the real CLI) and set command to that name:

[clis.claude-sandboxed]
command = "claude-sandboxed"   # a wrapper on PATH, NOT a path to a script

If you instead point command at a script path that isn’t resolvable by name, the pane drops to a raw shell and the boot prompt is typed into it.

git paw doctor reports whether sandbox-exec/bwrap is installed.

macOS (sandbox-exec)

A wrapper (claude-sandboxed on your PATH):

#!/bin/sh
set -eu
WT="$PWD"
GITDIR="$(git -C "$WT" rev-parse --git-common-dir)"; GITDIR="$(cd "$GITDIR" && pwd)"
exec sandbox-exec \
  -D WORKTREE="$WT" \
  -D GITDIR="$GITDIR" \
  -D GITHOOKS="$GITDIR/hooks" \
  -D GITCONFIG="$GITDIR/config" \
  -D TMPDIR="${TMPDIR%/}" \
  -D CLIHOME="$HOME/.claude" \
  -D CARGOHOME="${CARGO_HOME:-$HOME/.cargo}" \
  -f "$HOME/.config/git-paw/sandbox.sb" \
  claude "$@"

The profile (sandbox.sb), a (allow default) base that denies writes except a scoped set:

(version 1)
(allow default)                          ;; reads + network stay open
(deny file-write*)
(allow file-write*
  (subpath (param "WORKTREE"))           ;; the worktree
  (subpath (param "GITDIR"))             ;; shared .git — needed to commit
  (subpath (param "TMPDIR"))
  (subpath (param "CLIHOME"))            ;; the CLI's own config/auth/cache
  (subpath (param "CARGOHOME"))          ;; toolchain cache (stack-specific)
  (regex #"^/private/tmp/claude-")       ;; the CLI's per-session temp/cwd
  (subpath "/private/tmp")               ;; shell heredocs (zsh writes /private/tmp/zsh*)
  (literal "/dev/null") (literal "/dev/tty") (regex #"^/dev/ttys[0-9]+$"))
;; Close the git-persistence gap (see below):
(deny file-write*
  (subpath (param "GITHOOKS"))
  (literal (param "GITCONFIG")))

/private/tmp must be writable, not just $TMPDIR and the CLI’s per-session prefix: zsh writes heredoc bodies to /private/tmp/zsh* while building the command it’s about to run, so the standard multi-line commit idiom — git commit -m "$(cat <<'EOF' … EOF)" — hits Operation not permitted without this grant. /private/tmp is already world-writable and holds no secrets, so this is a write-only convenience grant; it does not change the read-confidentiality tiers below (see Confidentiality hardening).

What breaks under the sandbox

Some failures aren’t a missing write grant — they’re the kernel refusing to exec at all, and no profile rule fixes them:

Setuid/setgid binaries cannot exec under sandbox-exec. /bin/ps and /usr/bin/top are setuid root on macOS. Seatbelt refuses to exec a setuid binary inside any profile, even the most permissive one:

$ sandbox-exec -p '(version 1)(allow default)' /bin/ps -o pid= -p $$
sandbox-exec: execvp() of '/bin/ps' failed: Operation not permitted

An agent running ps inside a wrapped CLI typically only sees a bare operation not permitted: ps — the same wording the sandbox uses for a denied write. Don’t chase it with a write grant: it isn’t one, and no (allow …) rule fixes it. Use pgrep instead — it works under the same profile because it isn’t setuid.

The bundled worker-orientation skill already tells agents this, so both surfaces agree; an agent that hits it should adapt (use pgrep) rather than probe or widen the profile.

Linux / WSL (bwrap)

#!/bin/sh
set -eu
command -v bwrap >/dev/null || exec claude "$@"   # detect-and-degrade
WT="$PWD"
GITDIR="$(git -C "$WT" rev-parse --git-common-dir)"; GITDIR="$(cd "$GITDIR" && pwd)"
exec bwrap \
  --ro-bind / / \
  --bind "$WT" "$WT" \
  --bind "$GITDIR" "$GITDIR" \
  --ro-bind "$GITDIR/hooks" "$GITDIR/hooks" \
  --ro-bind "$GITDIR/config" "$GITDIR/config" \
  --bind "${TMPDIR:-/tmp}" "${TMPDIR:-/tmp}" \
  --bind "$HOME/.claude" "$HOME/.claude" \
  --bind "${CARGO_HOME:-$HOME/.cargo}" "${CARGO_HOME:-$HOME/.cargo}" \
  --dev-bind /dev /dev \
  --unshare-user \
  --chdir "$WT" \
  claude "$@"

bwrap needs unprivileged user namespaces; some hardened kernels disable them — hence the command -v bwrap degrade line. sandbox-exec is deprecated but present on every macOS; both are pragmatic, not stable contracts.

The --bind "${TMPDIR:-/tmp}" "${TMPDIR:-/tmp}" line already covers shell heredocs on Linux — zsh writes heredoc bodies under $TMPDIR (or /tmp when unset), and both are bound writable, so the git commit -m "$(cat <<'EOF' … EOF)" idiom works here without an extra grant. ps is not setuid on Linux and works fine here — see What breaks under the sandbox for why it fails on macOS instead. bwrap itself sets no_new_privs, so even a setuid binary that did run inside it would run without its elevated privileges.

The writable set to get right

The profile is only as good as this list. Beyond the worktree, an agent CLI legitimately needs to write:

• The shared .git — a child worktree commits into the main repo’s .git, so it must be writable except .git/hooks and .git/config (below).
• The CLI’s own config/auth/cache (~/.claude, ~/.config/…) and its per-session temp/cwd. Claude Code, for example, uses /private/tmp/claude-<uid>/ and /private/tmp/claude-<hash>-cwd symlinks (random names → a regex, not a subpath) — omit these and the agent’s shell tool dies with operation not permitted.
• TMPDIR and device nodes (/dev/null, /dev/tty, the pane pty).
• Toolchain caches the workers write to (~/.cargo, ~/.rustup, …) — these are stack-specific; source them from your stack, don’t assume.
• Network stays open by default: agents need the loopback broker and outbound model-API egress.

The git-persistence gap

Keep .git writable for commits, but bind .git/hooks and .git/config read-only. Otherwise a confined agent can plant a .git/hooks/post-commit script or set core.pager/editor/fsmonitor to an arbitrary command — which fires later, unsandboxed, with full privileges the next time you run plain git outside the box. The agent can still commit (index/objects/refs); it just can’t plant persistence.

Credential refresh (per-OS)

A long-lived agent refreshes its OAuth token mid-session. Where that token lives differs by OS, and it affects the profile:

• macOS: the token is in the login Keychain, and refresh writes it back — an in-process write the (deny file-write*) base blocks, so the agent logs in fine at first but hits “Not logged in” when the token expires. To allow refresh, add ~/Library/Keychains to the writable set. Tradeoff: that grants write to your whole login keychain (and reads were already open) — so the sandbox protects filesystem write-integrity, not the confidentiality of keychain secrets. If your CLI can be configured to use file-based credentials (a file under the already-writable CLIHOME), prefer that and deny the Keychain entirely.
• Linux: credentials are file-based (headless: a file under ~/.claude*/) or written by a separate Secret Service daemon (desktop). The file lives in the writable CLIHOME, and the daemon writes on the agent’s behalf outside the sandbox — so neither has the macOS refresh problem.

Confidentiality hardening

The base profile confines writes only; the agent can still read anything your user can (SSH keys, cloud creds, other repos). If that matters, add read-denials. Two tiers:

Tier 1 — blocklist (cheap). Keep (allow default), deny reads of known secret stores:

(deny file-read*
  (subpath (param "SSH"))       ;; ~/.ssh
  (subpath (param "AWS"))       ;; ~/.aws
  (subpath (param "GNUPG")))    ;; ~/.gnupg

Tier 2 — allowlist (strong). Deny reading your home, then re-allow only what the agent needs (everything outside $HOME — system libraries — stays readable, so the app still runs):

(deny file-read* (subpath (param "HOME")))
(allow file-read*
  (subpath (param "REPO"))
  (subpath (param "CLIHOME"))
  (subpath (param "CARGOHOME"))
  (subpath (param "KEYCHAINS")))   ;; still needed for macOS auth (see above)

~/.ssh is safe to deny for a git-paw worker: it commits locally (no key needed unless you sign commits with an SSH key), and pushes/fetches are done by the unsandboxed supervisor or you — not the worker. Deny it unless your workers sign with an SSH key or push over SSH themselves, in which case grant the specific key plus SSH_AUTH_SOCK rather than the whole folder.

The one residual even under Tier 2 is the login Keychain (allow-listed for auth); per-item ACLs do not gate a confined agent in your unlocked session. Close it only via file-based credentials as noted above.

Spec-Driven Launch

The --from-all-specs and --specs flags let you define branches, CLI assignments, and prompts in spec files instead of using interactive selection. git-paw reads spec files from a configured directory, creates worktrees for each pending spec, and launches AI CLIs with the spec content injected into each worktree’s gitignored .git-paw/AGENTS.local.md sidecar (the tracked AGENTS.md is left untouched).

Quick Example

# Initialize repo config (creates .git-paw/config.toml)
git paw init

# Add spec files to your specs/ directory, then launch every discovered spec
git paw start --from-all-specs

# Narrow to specific specs without editing config
git paw start --specs add-auth,fix-session

# Open a multi-select picker (requires an interactive terminal)
git paw start --specs

Picking specs at launch time

You have three ways to control which specs are launched:

• --from-all-specs — launches every discovered spec across the configured backend.
• --specs NAME[,NAME...] — comma-separated list of spec names. Mirrors the existing --branches feat/a,feat/b syntax. Unknown names exit with the discovered-set listed as candidates so you can correct quickly.
• --specs (bare, no values) — opens a multi-select picker showing every discovered spec. Each row shows the unit identifier; for Spec Kit features that decompose into multiple worktrees, the row also shows a worktree-count hint (e.g. 003-user-list — 3 worktrees: 2 [P] + 1 phase/). The picker is a type-to-filter multi-select (identical to the branch picker): type to narrow the rows by case-insensitive substring match against the displayed label, Ctrl-U clears the filter, Space toggles, and Enter confirms. Selecting a filtered row still expands to every underlying entry for that unit, and selections persist across filter changes.

--from-all-specs and --specs are mutually exclusive — they express opposing intents — and clap rejects any invocation that combines them.

Picker requires a TTY

The bare --specs form requires an interactive terminal. When stdin is not a TTY (CI, scripted invocation, redirected input), git-paw exits with an actionable error pointing at the explicit forms:

error: --specs without values requires an interactive terminal
  Use `--specs NAME[,NAME...]` to narrow explicitly, or
  `--from-all-specs` to launch every discovered spec.

Name resolution rules

--specs NAME matches against the discovered set using these strategies in order:

1. Exact match on the spec id (case-sensitive). Matches OpenSpec change names, Markdown filename stems, or Spec Kit decomposed entry ids like 003-user-list-T009.
2. Spec Kit feature-name match — the value matches a Spec Kit feature directory prefix (e.g. 003-user-list). All decomposed entries belonging to that feature are launched together.
3. Spec Kit numeric prefix — a digits-only value (e.g. 003) matches a unique feature directory whose name starts with 003 followed by a non-digit boundary. Ambiguous prefixes (two features both starting with 003) are rejected with the candidate list.

Unknown names error out before any worktrees are created. The error message includes the unresolved name AND the discovered candidate list. There is no partial start.

Spec Formats

git-paw supports four spec formats: OpenSpec (directory-based), Markdown (file-based), Spec Kit (.specify/-based, GitHub Spec Kit), and Superpowers (docs/superpowers/plans/-based, obra/superpowers).

OpenSpec Format (default)

Each pending change lives in its own subdirectory under the specs directory. The subdirectory name becomes the branch identifier.

specs/
  add-auth/
    tasks.md          # Required — main prompt
    specs/
      jwt/spec.md     # Optional — supplementary spec
  fix-pagination/
    tasks.md

Discovery is by archive status, not task completion. --from-all-specs includes every change subdirectory under specs/ except anything under specs/archive/. A change with all tasks marked - [x] in its tasks.md is still picked up — task-completion is a progress tracker, not a discovery filter. After completing and verifying a change, run:

openspec archive <change-name>

before the next git paw start --from-all-specs invocation. openspec archive moves the change directory under specs/archive/<date>-<change>/ and syncs its delta specs into the main specs at specs/<capability>/spec.md. The next session won’t spawn a worktree for it.

tasks.md contains the prompt content sent to the AI CLI. It supports optional YAML frontmatter:

---
paw_cli: claude
---

## Implement JWT Authentication

Add JWT token support to the auth module.

The paw_cli field overrides the CLI for this specific spec. If omitted, the default resolution chain applies (see CLI Resolution below).

Supplementary spec files in specs/<name>/spec.md are appended to the prompt with section headers. File ownership can be declared with “Files owned:” or “Owned files:” followed by a markdown list.

Markdown Format

Flat .md files in the specs directory. Each file uses YAML frontmatter to control status and branch mapping.

specs/
  add-auth.md
  fix-pagination.md
  design-notes.md      # ignored — no paw_status: pending

Example file (specs/add-auth.md):

---
paw_status: pending
paw_branch: add-auth
paw_cli: claude
---

## Implement JWT Authentication

Add JWT token support to the auth module.

Frontmatter Fields

Only files with paw_status: pending are picked up.

Spec Kit Format

Spec Kit projects place each feature in its own directory under .specify/specs/<feature>/, alongside an optional .specify/memory/constitution.md for project-level rules.

.specify/
  memory/
    constitution.md            # Optional — project rules / governance
  specs/
    001-room-setup/
      spec.md                  # Feature requirements
      plan.md                  # Implementation plan
      tasks.md                 # Required — task list with phases
      checklists/              # Optional — advisory validation criteria
        security.md
    002-poker-voting/
      spec.md
      plan.md
      tasks.md

Selecting Spec Kit. git-paw does not auto-detect the spec system from the filesystem — you set it explicitly. Either configure [specs] type = "speckit" with dir = ".specify/specs" in .git-paw/config.toml (git paw init prompts you to choose the spec system and writes this section), or pass --specs-format speckit for a single launch.

Selecting a spec system for one launch with --specs-format:

# Force Spec Kit even when [specs] config says otherwise
git paw start --from-all-specs --specs-format speckit

# Force OpenSpec on a project that has a `.specify/` folder
git paw start --from-all-specs --specs-format openspec

# Force Superpowers on a project with docs/superpowers/plans/
git paw start --from-all-specs --specs-format superpowers

tasks.md decomposition. Spec Kit’s tasks.md files use ## Phase N: <Name> headings and - [ ] T<NNN> task lines. git-paw decomposes the current phase (the first phase with any incomplete task) into one worktree per kind:

• Each incomplete [P]-marked task → its own worktree on task/<task-id>-<slug> (one agent per task, parallel).
• All remaining incomplete non-[P] tasks → one consolidated worktree on phase/<feature>-<phase-slug> (one agent works through them sequentially, since the absence of [P] indicates shared files or context).

## Phase 2: Foundational
- [ ] T009 [P] Contract test POST /auth/otp/request   → task/t009-contract-test-...
- [ ] T010 [P] Contract test POST /auth/otp/verify    → task/t010-contract-test-...
- [ ] T011 Setup database schema                       ┐
- [ ] T012 Create auth tables                          ├ phase/<feature>-foundational
- [ ] T013 Seed test data                              ┘

In this example, one feature directory produces three worktrees and three branches. This “one Spec Kit feature → multiple branches” model is intentional — [P] tasks parallelise across worktrees; non-[P] tasks sequence within a single worktree.

Phase advancement. Phases earlier than the current one are assumed complete (all - [x]). Phases later than the current one are deferred — they only produce worktrees on a future scan, after every task in the current phase has been ticked off. Fully completed features (every task in every phase is - [x]) are skipped silently.

Boot prompts. Each Spec Kit worktree’s .git-paw/AGENTS.local.md sidecar contains:

1. Feature Context — the full spec.md content.
2. Implementation Plan — the full plan.md content (omitted when absent).
3. Validation Criteria (advisory) — each checklists/<file>.md content under its own heading. Checklists are advisory.
4. Your Task — the single task description (task/... worktrees) or the ordered task list plus sequential-execution + - [x] writeback + agent.artifact (with status: "done") instructions (phase/... worktrees).

Task writeback. Agents working in a phase/... worktree flip - [ ] to - [x] in the worktree’s tasks.md as they complete each task. The writeback may be committed alongside the task’s code change or as a separate commit. Per-line edits across worktrees are merged by git in the normal way. The conflict detector exempts writebacks to the shared tasks.md from ownership-violation detection; concurrent edits to it by two worktrees can still raise in-flight warnings.

Constitution wiring. With [specs] type = "speckit" and no explicit [governance] constitution setting, git-paw probes <specs dir>/../memory/constitution.md (normally .specify/memory/constitution.md) and, when it exists, wires it in as the governance constitution automatically — so a project that already has a Spec Kit constitution gets it configured for free. An explicit [governance] constitution value always wins; see Configuration → Spec Kit constitution auto-wiring.

Superpowers Format

obra/superpowers is a multi-CLI methodology plugin whose writing-plans skill saves implementation plans as flat Markdown files under docs/superpowers/plans/. git-paw scans those plans — one worktree per incomplete plan.

docs/superpowers/plans/
  2026-07-20-add-auth.md       # one plan = one worktree
  2026-07-21-export-csv.md

Unlike Spec Kit, a superpowers plan is not fanned out into per-task worktrees — a plan is a sequential TDD chain meant for a single subagent-driven-development worktree, so each plan file maps to exactly one branch: plan/<plan-file-stem>.

Plan structure. Each plan carries a header (**Goal:**, **Architecture:**, **Tech Stack:**) and one or more ### Task N: <name> sections, each with a **Files:** block (exact paths) and bite-sized - [ ] checkbox steps plus Run: verification commands.

Discovery. A plan is picked up when it has at least one incomplete - [ ] step. A plan whose every step is - [x] is skipped (with a warning); a .md file with no ### Task/step lines — e.g. a design doc under docs/superpowers/specs/ — is skipped silently.

Selecting Superpowers. As with every format, git-paw does not auto-detect it — configure [specs] type = "superpowers" with dir = "docs/superpowers/plans" (git paw init prompts you to choose the spec system), or pass --specs-format superpowers for a single launch.

Boot prompt. Each worktree’s .git-paw/AGENTS.local.md sidecar contains: Plan Context (Goal / Architecture / Tech Stack), Your Tasks (the plan’s task sections with their Files: and Run: metadata), and an Execution instruction to work the steps in order, flip - [ ] → - [x] in the plan file as each lands, and commit your work when every step shows - [x]; the post-commit hook will auto-publish your completion.

Configuration

Configure spec scanning in .git-paw/config.toml (or the global config):

# Default CLI for spec-mode launches (bypasses picker when set).
default_spec_cli = "my-cli"

# Prefix for spec-derived branch names (default: "spec/").
branch_prefix = "spec/"

# Spec scanning configuration.
[specs]
dir = "specs"         # Directory containing spec files (relative to repo root)
type = "openspec"     # "openspec" (default), "markdown", "speckit", or "superpowers"

The interpretation of dir depends on the format:

• openspec — directory of change subdirectories (<dir>/<change>/tasks.md).
• markdown — directory of .md files (<dir>/<spec>.md).
• speckit — directory of feature subdirectories (<dir>/<feature>/tasks.md); typically .specify/specs.
• superpowers — directory of flat plan files (<dir>/<plan>.md); typically docs/superpowers/plans.

Branch Naming

Branch names depend on the format:

• OpenSpec: <branch_prefix><id> where ID is the subdirectory name. specs/add-auth/ with prefix spec/ becomes branch spec/add-auth.
• Markdown: <branch_prefix><id> where ID is paw_branch (if set) or the filename stem. specs/add-auth.md with prefix spec/ becomes branch spec/add-auth.
• Spec Kit: branch prefix is task/ or phase/ depending on the entry kind; branch_prefix is not applied. Example: .specify/specs/003-user-list/tasks.md with task - [ ] T009 [P] Add login form produces branch task/t009-add-login-form.
• Superpowers: plan/<slugified plan-file stem>; branch_prefix is not applied. Example: docs/superpowers/plans/2026-07-20-add-auth.md produces branch plan/2026-07-20-add-auth.

Spec Kit and Superpowers derive their branch name from spec text — a task description, a plan-file stem — by lowercasing it and replacing every character outside [a-z0-9_] with -. Underscores survive into the branch name. A task reading - [ ] T001 [P] Create ROOM_SETUP.md produces branch task/t001-create-room_setup-md, and a plan file add_auth.md produces branch plan/add_auth: _ is legal in a git ref, and the branch is durable state that worktree recovery and --resume use to look up work, so it is left intact.

The agent’s broker agent_id is a separate derivation from that branch name, and it does not keep _ — the broker’s id grammar forbids it, so the underscore maps to - there. The branch task/t001-create-room_setup-md publishes as agent task-t001-create-room-setup-md. See Identifier Forms for the full conversion.

CLI Resolution

When a spec-mode launch runs, CLIs are resolved in priority order:

1. --cli flag (highest) — applies to all specs, no prompt
2. paw_cli in spec — per-spec override from frontmatter
3. default_spec_cli in config — fills remaining specs without prompt
4. default_cli in config — pre-selects in picker for remaining
5. Interactive picker (lowest) — prompts for any unresolved specs

# Override all specs to use claude
git paw start --from-all-specs --cli claude

# Use per-spec paw_cli and default_spec_cli from config
git paw start --from-all-specs

# Narrow to a subset
git paw start --specs add-auth,fix-session --cli claude

# Preview without executing
git paw start --from-all-specs --dry-run
git paw start --specs add-auth --dry-run

Combining --from-all-specs with supervisor mode

--from-all-specs --supervisor (or --from-all-specs with [supervisor] enabled = true in your config) engages the supervisor flow against the discovered specs. git-paw scans the configured specs directory, creates one worktree per spec, and builds one tmux session with the dashboard pane (pane 0) and the per-spec agent panes from pane 1 — the orchestrator runs outside the session, reading the context rendered into .git-paw/AGENTS.local.md — then returns with an attach hint (or, with --unattended, runs the in-process drive loop instead) — same supervisor architecture as --branches-driven sessions, just with branches discovered from specs.

The CLI Resolution chain above applies identically here — --supervisor never bypasses or alters it. In particular, default_spec_cli is honoured for a spec-driven worker pane exactly as it is without --supervisor, so a [clis.<name>] sandbox pinned via default_spec_cli cannot be silently swapped for a different CLI just because the launch went through the supervisor flow. git paw doctor also reports the effective spec-worker CLI and warns if a configured default_spec_cli is never actually reachable by any discovered spec — see Doctor.

# Spec-driven session with supervisor watching
git paw start --from-all-specs --supervisor

# Same outcome via [supervisor] enabled = true in .git-paw/config.toml
git paw start --from-all-specs

# Skip supervisor for this session even if enabled in config
git paw start --from-all-specs --no-supervisor

When [broker] enabled = true — the broker defaults to disabled and must be opted into explicitly in config (supervisor mode does not turn it on for you) — each spec agent pane receives a boot block via tmux send-keys carrying its BRANCH_ID, broker URL, and the patterns for publishing through the bundled broker.sh helper. This applies to both spec-mode-only (--from-all-specs without supervisor) and supervisor mode; a spec-mode-only launch additionally submits the boot block (rather than leaving it pre-filled) and appends the task prompt naming the agent’s spec assignment, so the agent starts work without a human completing the prompt by hand — see Boot-block submission and task-prompt injection below.

Boot-block submission and task-prompt injection

Not every launch path treats its agent pane’s initial prompt the same way:

• Bare git paw start (no spec selection) pre-fills the boot block — followed by the worktree rule naming that pane’s own worktree root — into the pane’s input line and stops. No Enter is sent. This is deliberate: the launch is human-driven, so you type your actual task after the boot instructions and submit it yourself.
• A spec-driven launch (--specs / --from-all-specs, with or without --supervisor) has no human typing the task — the task comes from the spec — so leaving the prompt pre-filled would strand the agent with nothing to act on. Both the supervisor path and the non-supervisor spec-mode path submit the agent’s prompt automatically: the text is injected, then — after a brief per-CLI settle delay — a separate Enter submits it. That prompt is the boot block (when the broker is enabled), the task prompt’s prose naming the agent’s spec assignment, and the worktree rule, joined by blank lines.
• With [broker] enabled = false, the non-supervisor spec-mode path (bare --specs / --from-all-specs, no --supervisor) injects no boot block — it is broker-specific content — but still injects and submits the task prompt, since the agent’s assignment does not depend on the broker. The supervisor path builds its agent panes’ prompt the same way regardless of whether the broker is enabled, so a supervisor-mode agent still receives a boot block even with the broker off; only its broker-coordination instructions are then inert.

Every launch path also composes its pane’s command from the resolved approval flags (agent_approval and any per-CLI approval_args override) — a bare or spec-driven launch is not exempt just because no supervisor is watching.

The workflow entry point

A spec format may declare a workflow entry point: one command line that brings the agent into the format’s native workflow, so it walks its task list and ticks tasks off rather than improvising a private process. Today only OpenSpec declares one — /opsx:apply <id>. Markdown, Spec Kit, Superpowers and the no-spec --branches path declare none.

When a format declares an entry point, a launch that submits the agent’s prompt sends two messages, not one:

1. the composed prompt above (boot block + task prose + worktree rule), and
2. the entry point on its own, as a separate composer line with its own Enter.

The command used to sit inside the task prompt’s prose, at the end of a sentence — and a weaker model read that sentence and narrated the command instead of running it, going idle with the work untouched. Submitted alone, the line is what a paste-aware CLI parses as a slash-command invocation, which is the behaviour the agent needs. The text comes only from the spec format’s own bundled template; git-paw’s code names no workflow command, so a format whose apply invocation changes changes only its template.

A pane whose format declares no entry point receives exactly one message, and the launch does not wait on it at all.

The idle wait

git-paw does not type the second message the instant the first one is sent. Typing into a CLI that is still working is unpredictable — a slash command dropped into a busy composer may be queued as text, run later, or discarded, and a keystroke that lands on a live permission prompt answers it. So after the first message’s Enter, the launch waits until the pane is idle:

• no live permission prompt,
• not mid-response, and
• an input box that is empty, or whose shape the CLI’s prompt-shape profile does not recognise,

observed on two consecutive captures. A single idle-looking capture is not enough: the instant between the Enter and the CLI starting its turn reads as idle too. Immediately before typing, git-paw captures the pane once more and types nothing unless it is still idle — so a pane that raised a prompt or started responding in the meantime receives no stray keystroke. The entry point is then submitted with the same split-send the first message used: literal text, settle delay, separate Enter.

Every waiting pane is polled in one loop, concurrently, under a single ~120-second budget — so a session’s launch grows by its slowest first turn, not by the sum of them. The OpenSpec prose tells the agent its workflow command is coming, which keeps that first turn short.

This wait happens before the launch attaches you to the session (and before git paw add prints its confirmation), so git-paw announces it first:

Waiting for 3 agent(s) to go idle before submitting their workflow command (up to 120s)...

If you see that line and nothing after it for a while, a pane is still working or is sitting at a permission prompt — attach in another terminal with tmux attach -t paw-<project> to see which.

A CLI git-paw has no profile for matches none of the markers above and therefore reads as idle. At worst its entry point follows the first message almost immediately — exactly what that CLI’s own input queue would see from a human typing two messages in a row.

If a pane never goes idle

When the budget elapses with a pane still busy or still sitting at a permission prompt, git-paw types nothing into it and prints a warning to stderr naming the pane, the agent, and the exact line to submit:

warning: pane 2 (spec-add-auth) did not go idle within 120s, so its workflow
command was not submitted; once the agent is idle, submit: /opsx:apply add-auth

The launch continues normally — the agent has its assignment and its boot block, it simply has not been dropped into its spec workflow. Attach to the session, answer whatever the pane is waiting on, and type the quoted command into that pane yourself. An unattended run leaves the same line in its output for an orchestrator to act on.

git paw add and paused sessions

git paw add to a running session follows the same rule: the new agent’s prompt is submitted, then its entry point once its pane goes idle.

git paw add to a paused session submits nothing — the pane is created but the prompt is held in the session record for the restart. The entry point is held alongside it. git paw start then submits the held prompt, waits for the pane to go idle, submits the entry point, and clears both. A session receipt written by an earlier git-paw carries no held entry point and restarts exactly as it did before; see Pause and Resume.

Non-interactive launches

If git paw start is invoked from a non-interactive terminal — CI, scripted invocation, or a harness tool that pipes stdin — git-paw skips the auto-attach step and prints an attach hint instead:

Session 'paw-myproject' started in detached mode.
Attach with:  tmux attach -t paw-myproject

Supervisor mode never auto-attaches, interactive terminal or not: the orchestrator is your own agent session outside tmux, and (without --unattended) the launch prints Supervisor session '<name>' launched with <N> coding agent(s)., the orchestrator-context path (.git-paw/AGENTS.local.md), and the same Attach with: hint. Attach later from a real terminal:

tmux attach -t paw-myproject

Session Logging

git-paw can capture the full terminal output of each AI CLI pane to log files. This lets you review what happened in a session after it ends.

Enabling Logging

Add the [logging] section to your .git-paw/config.toml (or global config):

[logging]
enabled = true

When enabled, git-paw uses tmux pipe-pane to capture each coding-agent pane’s output to a log file when it launches a fresh session — a plain git paw start, a spec-driven launch, or a supervisor session. The dashboard pane is not logged, and neither are panes attached later with git paw add or the panes of a session recovered by git paw start after git paw stop.

Log Storage

Logs are stored under .git-paw/logs/ organized by session:

.git-paw/logs/
  paw-my-project/
    feat--add-auth.log
    fix--pagination.log

Branch names are sanitized for filenames — / becomes -- (e.g., feat/add-auth becomes feat--add-auth.log).

The git paw init command automatically adds .git-paw/logs/ to .gitignore so logs are never committed.

Replaying Logs

Use git paw replay to view captured logs.

List available sessions and branches

git paw replay --list

Shows all sessions and their logged branches.

Replay a branch

git paw replay feat/add-auth

The argument must match a log exactly — as the original branch name (feat/add-auth), the sanitized stem (feat--add-auth), or the full filename (feat--add-auth.log). Partial names are not matched; when nothing matches, the error lists the available branches.

By default, ANSI escape codes are stripped for clean text output.

Replay with colors

git paw replay feat/add-auth --color

Preserves ANSI colors and pipes through less -R for scrollable colored output.

Replay from a specific session

git paw replay feat/add-auth --session paw-my-project

By default, the most recent session is used. Use --session to specify an older one.

Flags

AGENTS.md Injection

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). The agent reads the spec from this combined view plus openspec/changes/<id>/, not from the boot prompt.

git-paw writes that combined view to a gitignored sidecar, .git-paw/AGENTS.local.md, in each worktree — not to the worktree’s tracked AGENTS.md. The boot prompt points the agent at the sidecar. The tracked AGENTS.md is left exactly as the project committed it, so a legitimate hand edit to it (yours or the agent’s) shows up in git status and commits normally, mid-session.

Why a sidecar. Through v0.7.0 git-paw injected its section into the tracked worktree AGENTS.md and then ran git update-index --assume-unchanged AGENTS.md to keep git add -A from committing the ephemeral injection. That bit is file-level: git stopped reporting every change to AGENTS.md, not just the injected block. An agent that needed to commit a real AGENTS.md edit found git status reporting the file unmodified and the commit silently empty for that path. Moving the injection to a gitignored sidecar removes the reason assume-unchanged existed: the tracked file is never touched, so it is never hidden.

Boot-Prompt-Full-Body Model

Earlier versions of git-paw embedded a condensed spec excerpt inside the supervisor-mode boot prompt itself (“Branch + CLI + Spec content + Owned files”). The supervisor-mode boot prompt is intentionally short: it points the agent at the sidecar .git-paw/AGENTS.local.md and at the change directory openspec/changes/<id>/, and tells the agent to read those files before acting. (Because the supported CLIs auto-load only the worktree-root AGENTS.md and not the sidecar, the prompt is what directs the agent to the sidecar’s combined content — every backend, including OpenSpec, points there first.)

The benefits of this split:

• The spec body lives in a markdown file the agent can re-read at any time, not in volatile boot-prompt context.
• The boot prompt becomes small enough to remain in the agent’s working context for the entire session, even after long conversations.
• Manual operators can pre-stage the boot block at the pane input line via paste, the same way the supervisor stages it programmatically.
• The same generator (src/agents.rs::setup_worktree_agents_md) writes the same content in both supervisor mode and broker-only mode, so the agent’s experience does not depend on which mode launched it.

How It Works

1. Sidecar. When a session starts, each worktree gets a .git-paw/AGENTS.local.md sidecar containing the combined view (the root AGENTS.md content plus the managed git-paw section). The sidecar is overwritten on every git paw start so the spec body never goes stale.
2. The tracked AGENTS.md is untouched. git-paw does not write to it, hide it, or exclude it. A hand edit to it appears in git status and commits normally.
3. Exclusion. The sidecar path (.git-paw/AGENTS.local.md) is added to the worktree’s ignore set so the ephemeral injection is never committed. For a linked worktree, git honors info/exclude only from the common git directory, so the entry is written there.
4. Self-healing upgrade. If a worktree carries a stale assume-unchanged bit on AGENTS.md from a pre-sidecar git-paw, the next git paw start clears it (git update-index --no-assume-unchanged AGENTS.md) so the tracked file becomes committable again — no manual git update-index needed.

Markers

git-paw manages its section in the sidecar using HTML comment markers so the root AGENTS.md content carried alongside it is preserved across launches:

<!-- git-paw:start — managed by git-paw, do not edit manually -->

(git-paw content here — full spec body)

<!-- git-paw:end -->

Content between these markers is replaced on each launch. Content outside the markers is preserved. If no markers exist, the section is appended to the end of the file.

Orchestrator pointer section

Separately from the per-session sidecar, git paw init injects one short, permanent section into your root AGENTS.md (creating the file when it is absent), between its own markers:

<!-- git-paw-orchestrator:start -->

(when a git-paw session is active, you are its orchestrator: read
 .git-paw/skills/orchestrator/SKILL.md and .git-paw/AGENTS.local.md)

<!-- git-paw-orchestrator:end -->

It is how the agent you drive the session with discovers the orchestrator skill: AGENTS.md is the cross-CLI file that agent already reads. The prose comes from a bundled, project-agnostic asset and carries no broker URL, secret, toolchain or vendor name. Re-running git paw init replaces the section in place, leaving everything outside the markers byte-identical. Unlike the per-session <!-- git-paw:start --> block, it is configuration, not session state: git paw stop and git paw purge leave it alone. Delete the section by hand if you do not want it; init reports what it wrote.

Sidecar Content

Each worktree’s .git-paw/AGENTS.local.md sidecar includes:

• The root repo’s AGENTS.md content (if any), preserved verbatim.
• A git-paw section between the markers carrying:
  • Branch name and assigned CLI for this worktree.
  • Full spec body — proposal, design, tasks, and any spec deltas from openspec/changes/<id>/. The exact set depends on what the change directory contains; missing files (design.md is often optional) are silently skipped.
  • Owned files list (from OpenSpec file-ownership declarations) when declared.
  • Boot block that calls the bundled .git-paw/scripts/broker.sh helper for the agent to self-report status, artifacts, blockers, and questions. The helper (installed by git paw init, alongside the supervisor’s sweep.sh) discovers the broker URL and shapes the JSON, so the boot block carries no raw curl or broker URL. Nothing is seeded into the agent CLI’s settings file, and git-paw answers no prompt on the agent’s behalf. Whether the helper runs without prompting is the CLI’s own decision; because it always lives at the stable path .git-paw/scripts/broker.sh, one permission rule you write there covers every call instead of a broad curl rule — see Coordination.

The supervisor-mode boot prompt does not duplicate any of this content — it points at the sidecar. If a change is updated on disk during a session (e.g. the supervisor edits tasks.md to mark a task complete), the worktree’s sidecar is regenerated on the next git paw start invocation rather than live-patched mid-session.

Agent Coordination

When multiple AI agents work in parallel, they benefit from knowing what the others are doing. The coordination broker is a lightweight HTTP server that lets agents share status updates, publish artifacts, and flag blockers – all without touching git.

Enabling the Broker

Add a [broker] section to your .git-paw/config.toml:

[broker]
enabled = true

When you run git paw start, pane 0 becomes a dashboard instead of an agent pane and the agents start at pane 1. Supervisor mode keeps the same layout: the orchestrator runs outside the session (see Supervisor § Session layout). The broker runs in its own process in a detached broker window; the dashboard is a client of it and displays a live status table.

How Agents Discover the Broker

git-paw sets the GIT_PAW_BROKER_URL environment variable in every agent pane. Agents use this URL to send and receive messages. A typical value is http://127.0.0.1:9119.

With the broker enabled, each agent’s boot block calls the bundled broker helper (or, for an MCP-speaking CLI, the MCP publish tools), and the agent’s AGENTS.md view carries the bundled coordination skill with the broker URL pre-expanded, so agents know how to use the broker without any manual setup.

Requests the broker refuses

The broker is unauthenticated, so before routing any request it checks two headers to keep browsers and DNS-rebinding pages out. A refused request is not routed and changes no broker state:

A Host must also be followed by nothing or a well-formed :<port>, so localhost:evil.com is refused; a duplicated or unreadable Host is refused; and an absolute-form request target (GET http://host/path) must name a loopback authority too.

Because the check runs before routing, it also answers for unknown paths and wrong methods: a request with a foreign Host gets 403, not 404/405.

Every client git-paw ships — the broker.sh and sweep.sh helpers, the post-commit hook, the CLI, the MCP server and the dashboard — addresses the broker by its configured http://<bind>:<port> URL and sends no Origin, so none of them is affected. See Security Posture for the threat model, the non-loopback-bind exception, and the reverse-proxy migration.

A verdict message is refused on its own terms, after those checks:

Feedback from any other sender — the post-commit branch-guard hook, the in-process conflict-detector, a person — is not a verdict and needs no header. Root-side helpers (sweep.sh verified, feedback-gate, conflict-ack) attach the credential for you; see Security Posture.

Broker helper

git paw init installs a bundled agent-side helper at .git-paw/scripts/broker.sh — the agent-facing analogue of the supervisor’s sweep.sh. .git-paw/scripts/ is gitignored, so a fresh agent-worktree checkout does not contain it. git paw start and git paw add therefore auto-provision the helper into each agent worktree at setup: they write broker.sh (whenever the broker is enabled) and docs-fetch.sh (whenever docs_base_url is configured) — with the shared _paw_common.sh preamble both scripts source — into the worktree’s .git-paw/scripts/, executable, from the same bundled assets init installs. The scripts are (re)written on every attach, so a worktree’s helper always matches the running binary’s version and agents never copy it by hand from assets/. The agent invokes the helper by its stable relative path.

The helper wraps every agent→broker curl an agent is allowed to make. It discovers the broker URL from .git-paw/config.toml [broker] (defaulting to http://127.0.0.1:9119) and shapes the JSON internally, so callers pass only simple arguments. The agent id comes from --agent <id> (the boot block passes the pre-expanded branch id) or, absent one, from slugifying the current worktree branch. Run .git-paw/scripts/broker.sh --help for the full surface.

In the repository’s main working tree the helper needs an explicit --agent <id>. Agents publish from linked worktrees; the main working tree is the orchestrator’s, and deriving an id from its branch would mint a phantom agent named after the default branch (main → agent-main) rather than identifying anybody. Run there without --agent, the helper exits non-zero with a diagnostic naming the remedy and publishes nothing. Pass the identity you mean — broker.sh --agent supervisor question "which order?" — and it publishes as before. Nothing changes for an agent in its own worktree, where derivation works exactly as it always has.

valid_for_seconds is a required field of agent.intent, so the helper always sends one: give a TTL explicitly when you want a different window, and the default of 900 seconds (15 minutes) applies otherwise.

A publish the broker rejects is loud. Every publish subcommand checks the broker’s HTTP response. When the broker does not accept the publish — any non-2xx status, or no response at all because the broker is not running — the helper prints the broker’s error to stderr and exits non-zero; it never reports the publish as done. Treat a non-zero exit as “this event did not reach the broker” and fix the cause (a malformed agent id, a stopped broker) rather than moving on. The same holds for the supervisor-side sweep.sh publish verbs.

The helpers are refreshed on every attach. git paw start and git paw add (re)write <worktree>/.git-paw/scripts/ from the bundled assets of the binary that launched the session, on every launch path, so a worktree’s helper always matches that binary’s version. Re-attaching a worktree that already has the scripts rewrites them rather than failing — which also means local edits to a worktree’s helper copy are overwritten. Edit assets/scripts/ (when developing git-paw itself) rather than a deployed copy.

Why a script and not a git paw publish subcommand? The helper is an agent-internal mechanism. A user-facing subcommand would surface in --help and produce confusing errors when run by a human (no broker, no session). A script under .git-paw/scripts/ is unambiguously agent-internal, mirrors the supervisor’s sweep.sh, and gives you a single stable path that one permission rule in your agent CLI can name — see Boot calls and permission prompts.

Boot-Prompt Injection

To ensure reliable agent self-reporting, git-paw automatically injects a standardized boot instruction block into every agent’s initial prompt. The block calls .git-paw/scripts/broker.sh (with the pre-expanded --agent <id>) for four essential operations — no raw curl and no broker URL appear in the boot block:

1. REGISTER - Immediate Status Publication

Agents automatically publish their working status with a “booting” message as their very first action:

.git-paw/scripts/broker.sh --agent feat-auth status booting

2. DONE - Task Completion Reporting

The primary completion path is git commit. The git-paw post-commit hook auto-publishes agent.artifact { status: "committed" } with modified_files derived from git diff HEAD~1 --name-only, so agents working on code changes do not publish anything manually — they commit and the hook reports on their behalf.

The boot block retains a manual agent.artifact { status: "done" } fallback for code-less tasks (docs-only updates handled outside the worktree, planning notes, exploration tasks where the artifact is information reported to the broker). The block warns agents NOT to publish manual done while their worktree has uncommitted changes — they should commit instead.

.git-paw/scripts/broker.sh --agent feat-auth artifact --exports "" --files ""

3. BLOCKED - Dependency Waiting Notification

Agents can properly declare when they’re waiting on dependencies:

.git-paw/scripts/broker.sh --agent feat-api blocked "auth token format" feat-auth

4. QUESTION - Uncertainty Escalation (Critical)

Agents are instructed to publish questions and wait for answers rather than guessing:

.git-paw/scripts/broker.sh --agent feat-auth question "Should the JWT use RS256 or HS256 signing?"

IMPORTANT: The boot block explicitly instructs agents: “DO NOT CONTINUE UNTIL YOU RECEIVE AN ANSWER!”

MCP tool form

The four events above are the broker.sh helper form. For a CLI known to speak MCP (Model Context Protocol) — the built-in set is claude, codex, cursor-agent, and agy — the boot block instead expresses each event as an invocation of the matching MCP publish tool: publish_status, publish_artifact, publish_blocked, publish_question. The events, their meanings, and their ordering are identical between the two forms; only the invocation mechanism differs, and each MCP publish tool resolves the publishing agent id from the session’s own worktree branch automatically — the boot block never needs to pass one.

An unrecognized or unknown-capability CLI always gets the broker.sh form. This is the safe default: a boot block naming tools a CLI cannot call would strand the agent at the very first step, so git-paw only switches to the MCP form when it is confident the target CLI can act on it.

A [clis.<name>] mcp = true|false entry overrides the built-in set, and is consulted first. The lookup is keyed on the CLI’s identity — the [clis.<name>] key, or the built-in / pass-through name — never on the command that key launches, so a custom variant such as [clis.claude-oss] command = "claude" keeps the helper form until you set mcp = true on it.

The MCP publish surface has no inbox or poll tool, so even the MCP form of the boot block reads the agent’s inbox with .git-paw/scripts/broker.sh --agent <id> poll.

Boot calls and permission prompts

Whether an agent’s first boot action stalls on a permission prompt is decided by the agent CLI’s own permission system — nothing in git-paw decides it, and git-paw grants nothing on your behalf. Two things are in play:

• the agent CLI’s resolved permission mode, set via agent_approval (see Configuration → Supervisor). Under a mode that still prompts for shell commands, the boot publish will prompt;
• your own allow rules in that CLI. The boot block always invokes the helper at the single stable path .git-paw/scripts/broker.sh (or the bash .git-paw/scripts/broker.sh form), precisely so one permission rule scoped to that exact path covers every boot call — never a broad curl * rule, and never per-endpoint curl prefixes that drift with URL normalisation or flag order.

git-paw writes to no CLI settings file — not the repo-root .claude/settings.json, not a per-worktree copy, and not a configured [clis.<name>].settings_path. It also never answers the prompt for you: if the boot publish prompts, an --unattended run escalates it for a human decision like any other prompt, and the rest of the wave keeps moving. The same is true of routine dev commands (git status, grep, find, your stack’s build/test verbs) — they run without asking only when the CLI’s own mode or rules permit it.

Pre-approving the helper calls, with your consent

If you would rather not answer those prompts at all, you can pre-approve git-paw’s helper calls in the agent CLI’s own allow rules:

git paw setup-cli <CLI> --allowlist --dry-run   # see exactly what it writes
git paw setup-cli <CLI> --allowlist             # apply it

This is optional and consent-only: you run it, it prints its plan before writing anything, and git paw setup-cli <CLI> --undo takes back exactly what it added. No launch path, no drive loop and no MCP tool ever runs it. A call that runs without a prompt still does so only through the agent CLI’s own permission system and the rules in its settings — git-paw makes no safety decision about any command. See Per-CLI Setup for the grant table, the protection rules that come with it, and the residual risks.

Boot Block Injection Modes

• Supervisor Mode: Boot block is prepended to each agent’s task prompt, then submitted (injected, then a separate Enter after a settle delay)
• Spec-driven, non-supervisor mode (--specs / --from-all-specs without --supervisor): the boot block (when the broker is enabled) is prepended to the task prompt the same way, and submitted the same way — the task comes from the spec, not a human, so the combined prompt cannot be left for someone to complete and submit by hand
• Bare, human-driven mode (git paw start with no spec selection): Boot block is pre-filled into each agent pane’s input line and left unsubmitted (user pastes their task after the boot instructions, then submits both together)

Both submitting modes end the injected prompt with the worktree rule. When the agent’s spec format declares a workflow entry point, a second line follows as its own message once the pane goes idle — see The workflow entry point.

The worktree rule

Every prompt git-paw injects into a coding agent pane at launch ends with a bundled worktree rule naming that agent’s absolute worktree root. It is appended by every injecting path — the bare pre-fill (which is still left unsubmitted, with no Enter), spec-driven and supervised start, git paw add, and a prompt held for an agent added while the session was paused — so no path can forget it. The rule is placed last, for recency: it is the constraint the agent should still be holding when it starts editing.

The rendered text, with the pane’s own recorded worktree path substituted:

Your worktree root is <worktree root>. Every file you create or edit SHALL lie under that directory. Never write outside it — not by an absolute path, and not by a relative path that climbs out of it (such as ../).

The ../ clause is the point. Under child placement the repository’s main checkout is an ancestor of every worktree, so a relative path that climbs far enough reaches it — and an agent told only to “use relative paths” can edit the main checkout without ever typing an absolute path. Naming the root makes the boundary something the agent can check a path against.

Like the rest of the boot prompt, the rule is instruction, not enforcement. What actually stops an out-of-worktree write is the agent CLI’s own outside-directory permission prompt and, if you have configured one, the FS-scoped sandbox — see Memory Isolation below. The template is project-agnostic: it names no tool, CLI or project, only the path.

Paste Handling

The boot block includes instructions for proper paste handling, particularly the requirement to send an additional Enter key after paste operations to ensure full content processing.

Benefits

• Reliable Monitoring: Agents self-report immediately on boot
• Consistent Behavior: All agents follow the same coordination pattern
• One rule covers every boot call: the boot block invokes the bundled broker.sh helper at one stable path, so a single permission rule in your agent CLI can allow it — rather than a broad curl grant. Whether it prompts at all is that CLI’s decision; if it does, the prompt is escalated to you, never auto-answered
• Supervisor Visibility: Questions and blockers surface to the dashboard promptly
• Audit Trail: All boot operations are logged in the broker log

Worktree Environment

A fresh worktree surfaces a few conditions that look broken but are actually expected policy. The bundled coordination skill briefs agents to recognise them and adapt rather than spend budget diagnosing a non-bug:

• Gitignored install artifacts. Per-stack install artifacts (dependency directories, build/restore caches) are absent from a fresh checkout by design and may already be provisioned by an operator-configured worktree on_create hook before the agent’s CLI starts. Agents are told not to reach for the repo-root copy or symlink it in, and to run their stack’s install step themselves only when the artifacts are genuinely missing.
• FS-confinement is policy, not a fault. When a worktree is FS-confined by an operator-configured sandbox, an Operation not permitted on a path outside the worktree is the sandbox working as intended. Agents are told to adapt rather than probe it (xattr, id, ls -lO@, write-probes) and to keep working inside their worktree.
• Setuid binaries under a sandbox. Some setuid-root system binaries — ps is the canonical example — cannot exec inside a sandbox. This is expected and not fixable, and does not indicate anything else is wrong.

This orientation is stack-agnostic: it never names a specific package-manager invocation, referring instead to “the stack’s install step.”

Memory Isolation

Coding agents are briefed (via the bundled coordination skill) that their worktree is their entire writable territory:

• Persistent artifacts live in the worktree. Memory files, notes, scratch state, and any configuration an agent generates for itself SHALL be created inside the agent’s own worktree — never elsewhere on the machine.
• Operator configuration directories are off-limits for writes. Home-level CLI configuration directories (and the per-project memory subtrees beneath them) and the host repository’s .claude/ and .git-paw/ control directories belong to the operator. Writing there mutates state shared across sessions and agents.
• Question instead of write. When a task appears to require writing outside the worktree, the agent publishes agent.question describing the path and waits for an answer rather than writing.

The agent is told the same boundary twice, on purpose: once here, by the bundled coordination skill it reads from its sidecar, and once at the end of its very first prompt, by the worktree rule — which names the absolute path rather than leaving the agent to infer it.

This boundary is carried by doctrine, not by a mechanical check in git-paw: a write targeting operator territory raises the CLI’s own permission prompt, which is escalated to a human and never answered automatically (see Agent permissions). For mechanical enforcement, add deny rules in the agent CLI’s own settings or use the sandbox. The supervisor treats an observed out-of-worktree write attempt as a boundary violation with scoped feedback and repeat-escalation (see Out-of-worktree write violations). The guidance closes the remaining gap: persistence paths that never raise a prompt are governed by the briefing itself.

Message Types

Most broker messages use the same JSON envelope:

{
  "type": "agent.<variant>",
  "agent_id": "<slug>",
  "payload": { ... }
}

<slug> is the agent’s slugified branch name (lowercase alphanumeric + - only; slashes and underscores from a branch name like feat/auth or feat/my_auth become hyphens — feat-auth, feat-my-auth). Eight variants use this envelope: agent.status, agent.artifact, agent.blocked, agent.intent, agent.question, agent.feedback, agent.answer, and agent.verified. Three more do not: agent.advanced-main carries its fields flat alongside type (see Advanced Main); agent.learning, published by the learnings aggregator, carries its agent_id inside payload; and supervisor.verify-now is emitted by the broker itself — carrying only the committing branch_id — to the supervisor inbox whenever an agent.artifact { status: "committed" } arrives and [supervisor] verify_on_commit_nudge is on (the default). src/broker/messages.rs is the source of truth for the payload schemas.

agent.status and agent.artifact are normally automatic. The filesystem watcher publishes agent.status (with modified_files) whenever a worktree’s git status --porcelain output changes, and the post-commit git hook publishes agent.artifact with status: "committed" and the committed file list every time an agent commits. The manual curl examples below are escape hatches for cases where the automatic publishers do not apply (e.g. code-less tasks or heartbeat injection during read-only investigation).

Status

An agent reports what it is currently doing along with any files it has already modified in this work step.

curl -s -X POST "$GIT_PAW_BROKER_URL/publish" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.status","agent_id":"feat-auth","payload":{"status":"working","modified_files":["src/auth.rs"],"message":"implementing login endpoint"}}'

Artifact

An agent shares the result of a commit (or the analogous output of a code-less task) so peers can see exports and modified files. The modified_files array is what the conflict detector watches for in-flight overlap.

curl -s -X POST "$GIT_PAW_BROKER_URL/publish" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.artifact","agent_id":"feat-auth","payload":{"status":"committed","exports":["AuthClient"],"modified_files":["src/auth.rs","src/auth/client.rs"]}}'

Blocked

An agent declares that it is waiting on something specific from another agent (or external resource). from names the agent that can unblock it.

curl -s -X POST "$GIT_PAW_BROKER_URL/publish" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.blocked","agent_id":"feat-api","payload":{"needs":"auth token format","from":"feat-auth"}}'

Intent

An agent declares which files it plans to modify before any edit lands. The broker conflict detector reads agent.intent to flag forward conflicts when two agents target overlapping paths. valid_for_seconds is the TTL after which consumers MAY treat the intent as stale.

curl -s -X POST "$GIT_PAW_BROKER_URL/publish" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.intent","agent_id":"feat-auth","payload":{"files":["src/auth.rs","src/auth/client.rs"],"summary":"wire AuthClient","valid_for_seconds":900}}'

Each files entry may also be an object declaring the regions within a file the agent intends to touch — see Declaring regions for the region-level granularity added in v0.6.0.

Question

An agent escalates an uncertainty to the supervisor inbox. The asking agent blocks at its prompt until a typed reply arrives.

curl -s -X POST "$GIT_PAW_BROKER_URL/publish" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.question","agent_id":"feat-auth","payload":{"question":"Should the JWT use RS256 or HS256 signing?"}}'

Feedback

A supervisor (or the broker’s auto-emitted [conflict-detector] voice) sends a list of error messages to a target agent. The target agent_id field on the envelope is the receiver; from inside the payload is the sender.

Feedback from supervisor is a verdict: the broker refuses it without the session’s authority credential (403 {"error":"authority required"}), so the supervisor publishes it through the helper, which attaches the credential:

.git-paw/scripts/sweep.sh feedback-gate feat-auth testing "test for HS256 path is failing"

The wire body it sends:

{"type":"agent.feedback","agent_id":"feat-auth","payload":{"from":"supervisor","errors":["[testing] test for HS256 path is failing"]}}

Answer

A supervisor replies to an asking agent’s agent.question with a non-error answer. Like feedback, the envelope agent_id is the receiver (the agent being answered) and from inside the payload is the sender; the message routes to the target agent’s inbox only. answer carries the reply text and the optional re field is a short reference to the question being answered (omitted when absent). An answer is authoritative guidance to act on — it is not an error report, so the receiving agent has nothing to fix and nothing to re-publish. Reserve agent.feedback for corrective errors.

curl -s -X POST "$GIT_PAW_BROKER_URL/publish" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.answer","agent_id":"feat-auth","payload":{"from":"supervisor","answer":"Use RS256; the key rotation tooling assumes it","re":"RS256 or HS256?"}}'

Verified

A supervisor confirms that an agent’s work has passed every verification gate. The agent_id is the agent whose work was verified; verified_by names the verifier. Every agent.verified is a verdict, refused without the session’s authority credential, so it is published through the root-side helper:

.git-paw/scripts/sweep.sh verified feat-auth "all five gates pass"

The wire body it sends:

{"type":"agent.verified","agent_id":"feat-auth","payload":{"verified_by":"supervisor","message":"all five gates pass"}}

Advanced Main

The supervisor publishes this after every successful merge to the default branch so dependent agents learn the base moved. The payload fields are flat (alongside type, not nested under payload): from, merged_branch, new_main_sha, base (the resolved default-branch name), merged_at, and an optional summary.

curl -s -X POST "$GIT_PAW_BROKER_URL/publish" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.advanced-main","from":"supervisor","merged_branch":"feat/auth","new_main_sha":"a1b2c3d4e5f6","base":"main","merged_at":"2026-06-04T13:30:00Z","summary":"landed AuthClient"}'

The broker rejects a publish missing any required field (merged_branch, new_main_sha, base, merged_at) with a 400-class error naming the field. Each event carries a deterministic id derived from merged_branch + new_main_sha + base + UTC-hour-bucket, so re-publishing the same merge within the hour dedups to one logical event.

When You Depend on a Peer’s Work

When a peer’s agent.artifact lists work an agent depends on, the bundled coordination skill tells the agent to treat it as a signal, not an instruction to graft the peer’s commit: publish agent.blocked naming the peer and what it needs, then continue on unblocked work (or wait if none remains). Agents must not cherry-pick a peer’s commit into their own branch — the supervisor later merges that commit from the peer’s own branch, so the grafted copy leaves the dependent branch divergent and unmergeable. Peer work arrives through the base branch instead, via the agent.advanced-main discipline below.

When Main Advances

An agent.advanced-main event arrives on your normal /messages/<agent_id> poll — no special subscription is needed. When the base it names is one your branch depends on, react deliberately, never automatically:

1. git fetch origin <base> to bring the new SHA local.
2. git log HEAD..origin/<base> --oneline to see exactly what landed.
3. Decide between rebase, merge, or wait based on what changed and the state of your working set.

Agents do not auto-rebase on receipt: rebasing rewrites history and can conflict with in-flight work, so it always requires judgment. If you do rebase, commit or deliberately stash your work first so a rebase conflict can never wipe uncommitted edits. (The bundled coordination skill teaches this discipline to coding agents directly.)

Separately, when the operator sets [supervisor] branch_refresh = true, the supervisor’s unattended drive loop may itself rebase an idle, clean worker branch onto the default branch after a merge. The worker is then told its HEAD moved by an agent.feedback tagged [branch-refresh] — never by agent.advanced-main. See Supervisor → Branch refresh.

Polling for Messages

Agents poll for messages from other agents using cursor-based pagination. The since parameter is a sequence number – the broker returns only messages with a sequence greater than the given value.

# First poll -- get all messages
curl -s "$GIT_PAW_BROKER_URL/messages/feat-auth?since=0"

The response includes a last_seq field. Pass this value as since on the next poll to get only new messages:

# Subsequent poll -- only new messages since last check
curl -s "$GIT_PAW_BROKER_URL/messages/feat-auth?since=42"

This cursor-based approach is lossless – no messages are missed between polls, regardless of timing.

Agents can use the bundled helper instead of a raw curl for the same read — .git-paw/scripts/broker.sh poll [since] issues GET /messages/<agent-id>?since=<n> and prints the returned messages (see Broker helper).

Waiting for Events

/messages/<agent_id> is one agent’s inbox. GET /log is the whole session’s message log, and it is the read surface for anything that watches the session as a whole — a supervisor, an external orchestrator, a monitoring script.

curl -s "$GIT_PAW_BROKER_URL/log?since=0"

The response is {"entries": [...], "last_seq": N}. since is the same cursor the inbox poll uses: the broker returns only entries whose sequence is greater than the value you pass, and last_seq is the cursor to send next. An empty response reports last_seq equal to the since you sent, so a reader’s cursor never rewinds and never has to re-read the log from the start. (Before v0.18 an empty response reported 0, which rewound every reader that trusted it — this is the one behaviour change in the response.)

The broker epoch — reset your cursor when it changes

Sequence numbers are per-broker and restart at zero every time a broker starts, which a git paw pause + git paw start cycle does. Because a cursor never rewinds, a reader that kept its old cursor across a restart would sit above everything the new broker appends: it would see nothing, forever, and time out every long poll while the session worked normally around it.

Every GET /log response therefore carries an epoch identifying the running broker instance (its start time in Unix milliseconds), and so do sweep.sh events and wait_for_events:

{ "entries": [ ... ], "last_seq": 57, "epoch": 1761500000123, "wave": { ... } }

Record the epoch alongside your cursor, and whenever it differs from the one you recorded, send since=0 on your next request — the entries you have already seen belong to a broker that no longer exists, so re-reading from the start is correct and happens exactly once per restart. The first epoch you see needs no reset; there is no earlier cursor to invalidate. git-paw’s own in-tree readers (the drive loop’s observer, the MCP tool) already do this.

The long poll

Add wait=<seconds> and the broker holds the request open until there is something to return:

# Block for up to 30s, or return the moment an entry newer than 42 is appended
curl -s "$GIT_PAW_BROKER_URL/log?since=42&wait=30"

• wait is whole seconds and is capped at 60. A larger value is clamped; a non-numeric value is rejected with HTTP 400.
• With wait and nothing newer than since, the request is held until an entry is appended or the wait elapses — whichever comes first. A wait that elapses with nothing new returns {"entries": [], "last_seq": <since>}.
• Without wait, the request returns immediately, exactly as before.

This is what makes an external reader event-driven rather than capture-diff polling. A reader that samples pane output on a timer silently misses anything that starts and finishes between two samples; a reader that blocks on the cursor sees every appended entry exactly once, whatever the timing.

The bundled helper verb

The supervisor-side helper wraps both reads in one call:

.git-paw/scripts/sweep.sh events <since> [wait]

wait defaults to 30 seconds. The verb calls GET /log?since=&wait= and GET /status, and prints one JSON object to stdout:

{ "entries": [ ... ], "last_seq": 57, "epoch": 1761500000123, "wave": { ... } }

It is strictly a read: it sends no keystroke and publishes nothing. With no reachable broker it prints an object carrying "no_session": true and exits 0, so a caller never has to distinguish a crash from a session that is not running. It is granted read-only by git paw setup-cli <CLI> --allowlist.

An MCP-speaking client reaches the same surface through the wait_for_events tool.

Checking Overall Status

The /status endpoint returns a summary of all agents and their latest state:

curl -s "$GIT_PAW_BROKER_URL/status"

Wave staleness

Per-agent heartbeats answer “is this agent alive?” They do not answer “is this wave getting anywhere?” A session can sit on an unanswered permission prompt for days with every pane alive and every agent reporting working. So /status also carries a wave object describing the session as a whole:

"wave": {
  "last_progress_unix_secs": 1761500000,
  "idle_seconds": 11520,
  "stall_threshold_seconds": 1800,
  "stalled": true
}

What counts as progress is deliberately narrow — exactly two things:

• A wave phase advances. An agent.status whose status or phase differs from that agent’s previously recorded values, or any agent.artifact, agent.verified, agent.feedback, or agent.advanced-main.
• A branch tip moves. The broker’s filesystem watcher sees an agent worktree’s HEAD commit change.

What does not count, however much of it arrives:

• a repeated identical agent.status — whatever its modified_files set;
• uncommitted file churn;
• agent.question, including the unattended drive loop’s escalation of a live permission prompt and its re-escalation of the same prompt;
• agent.learning, agent.blocked, agent.intent, agent.answer, and the broker’s own supervisor.verify-now nudge;
• an agent.status carrying one of the stuck-detection helper’s synthetic alert phases — stuck-on-prompt, stuck-stream-timeout, context-bloat, no-progress or blocked-on-supervisor. Each is a report about a wave that is not moving, so counting it would let the detection of a stall reset the stall clock; no-progress says as much in its own name. A status moving an agent back out of one of those phases is an ordinary phase advance and does count.

That exclusion list is the point: those are precisely the messages that keep arriving while a wave sits on an unanswered prompt, so counting them would make the signal report healthy exactly when it matters most.

A broker that has accepted no message at all reports its own start time as the last progress. stalled is true when the threshold is non-zero and idle_seconds exceeds it.

The threshold is the [broker] wave_stall_minutes key — default 30 minutes, 0 to disable the flag while still reporting idle_seconds. See the configuration reference. Thirty minutes sits just above the unattended drive loop’s 25-minute heartbeat, so a wave that is merely between heartbeats is not reported as stalled.

The same object is surfaced by git paw status (human and --json), the dashboard status line, the MCP tools get_session_status and wait_for_events, and sweep.sh events — so a waiter whose long poll times out with no entries still learns that the wave has stalled.

Multi-Repo Considerations

Each git-paw session runs its own broker. If you have multiple repos running sessions simultaneously, each needs a unique port:

# In repo-a/.git-paw/config.toml
[broker]
enabled = true
port = 9119

# In repo-b/.git-paw/config.toml
[broker]
enabled = true
port = 9120

git-paw enforces this: a broker reports the repository it serves on GET /status, and a session that finds another repository’s broker on its port is refused with an error naming that repository and telling you to set a distinct [broker] port. See Multi-repo port assignment.

The default port is 9119. The broker binds to 127.0.0.1 (localhost only) by default — the [broker] bind setting — and should never be exposed to the network.

Automatic Conflict Detection (v0.5.0)

When supervisor mode is active, the broker runs an in-process conflict detector that auto-emits agent.feedback (tagged [conflict-detector] in the errors array) and, for unresolved in-flight conflicts, escalates to the supervisor inbox via agent.question. Three failure shapes are detected:

• Forward conflicts — two agents publish agent.intent with overlapping files. Both receive agent.feedback listing the other agent and the overlapping paths. Toggle with [supervisor.conflict] warn_on_intent_overlap.
• In-flight conflicts — two agents’ agent.status modified_files sets overlap on the same file. Both receive agent.feedback. The broker waits [supervisor.conflict] window_seconds (default 120) for one side to stop touching the file; if both keep modifying it, the detector escalates a true collision to the supervisor inbox via agent.question (an overlap whose declared regions are disjoint is downgraded to an informational agent.feedback instead).
• Ownership violations — an agent’s modified_files includes a file outside its own active agent.intent and inside another agent’s active intent. The violator receives agent.feedback; if [supervisor.conflict] escalate_on_violation = true the supervisor inbox also receives a follow-up agent.question. The shared spec tasks.md every agent ticks its own line in is exempt.

See the Conflict Detection chapter for the full walkthrough — failure shapes, the [conflict-detector] tag, supervisor inbox routing, and the configuration knobs.

Audit Trail

The broker appends every message to a <session_name>.broker.log file in git-paw’s session-state directory (~/Library/Application Support/git-paw/sessions/ on macOS, $XDG_DATA_HOME/git-paw/sessions/ — default ~/.local/share/git-paw/sessions/ — on Linux), outside the repository. Each line is plain text — [<seq>] <unix-seconds> [<agent_id>] <message summary> — and the file is flushed every 5 seconds, giving an audit trail of agent communication. For the full JSON of every message, query the broker’s GET /log endpoint (see Waiting for Events).

The log file is automatically cleaned up by git paw purge.

Working Heartbeat

The broker’s filesystem watcher publishes agent.status whenever a worktree’s git status changes, which keeps the dashboard’s last_seen timestamp fresh during active editing. The watcher cannot observe read-only tool uses (file reads, greps, searches), permission-prompt waits, or LLM-only deliberation between tool calls — so a long read-heavy investigation looks stuck on the dashboard even though the agent is making progress.

To bridge that gap, the embedded coordination skill instructs agents to publish a lightweight agent.status heartbeat every 5 tool uses while actively working, through the bundled broker helper, which publishes {"status":"working","message":"<text>","modified_files":[]}:

.git-paw/scripts/broker.sh --agent feat-auth status "reviewing auth tests"

The heartbeat reuses the existing agent.status shape — no new wire format is introduced. The broker merges heartbeats with watcher-driven updates without conflict.

Activity phrases

A status payload may also carry an optional activity field — a short phrase naming what the agent is doing right now:

curl -s -X POST http://127.0.0.1:9119/publish \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.status","agent_id":"feat-auth","payload":{"status":"working","activity":"running the test suite","modified_files":[]}}'

The field is optional and backward compatible: a payload that omits it deserializes and re-serializes exactly as before, so existing agents and stored messages are unaffected. When present, the dashboard’s Broker log panel renders the phrase alongside the status. Because the panel also collapses consecutive identical heartbeats, a phrase that changes as the work moves along keeps each phase on its own row.

Prefer Native Read Tools Over Shell Pipelines

The bundled coordination skill teaches agents to prefer their CLI’s own native file-read and search facilities over a shell text-extraction pipeline (a command that pipes output through line-slicing or field-extracting utilities) when inspecting source. Two costs motivate this:

• The approval stall — a shell pipeline typically requires a permission approval before it runs, so the agent waits on a prompt every time.
• The dead grant — a durable approval is keyed on the exact command string, so the next inspection (a different line range, a different search term) never matches it, and the allowlist accumulates entries that exist only to be ignored.

The same mechanic governs scratch files: when an agent captures a command’s output across repeated iterations, the skill tells it to reuse one scratch path rather than writing a fresh numbered file each time, since a durable approval keyed on a path does not carry over to a new filename.

The guidance is deliberately CLI-agnostic — it names no specific CLI, tool, or vendor — so it holds for any CLI git-paw launches.

Commit Cadence

The bundled coordination skill teaches a per-group commit cadence. When a change has an OpenSpec-style tasks.md with numbered groups (## 1., ## 2., …), the agent commits after every - [ ] item in a group is - [x] — one group, one commit (by default) — before starting the next group.

The skill bounds uncommitted work to roughly ten files at a time. If a single group exceeds that mid-implementation, the agent splits into multiple commits using a (part N of M) suffix:

close per-scenario coverage gaps (part 1 of 2)
close per-scenario coverage gaps (part 2 of 2)

Each commit must be a releasable unit — it builds and passes its own gates on its own, not a checkpoint of half-finished work. When the agent needs to fix the commit it just made (a typo, a missed file) and that commit has not yet been verified, the skill tells it to fold the fix in with git commit --amend rather than land a separate fix typo micro-commit. It must not --amend an already-verified commit or an earlier group’s commit — --amend applies only to the most-recent, not-yet-verified commit. This keeps the history as clean, verifiable units and avoids the manual release-time squashes earlier cycles needed (148→10 in v0.6.0, 4→1 in v0.7.0).

The bundled skill does not mandate, default to, or recommend a commit-message format. Message format is a per-project convention, so the skill defers entirely to the host project’s injected AGENTS.md (subject style, any prefix or scope convention, any “no AI-assistant trailer” rule), and any commit example it shows — like the (part N of M) split above — uses a format-neutral subject. git-paw’s own repo uses Conventional Commits, but only via git-paw’s own AGENTS.md, never via the skill the binary exports to other projects.

Per-group cadence protects against agent crashes, conflict mediation, and /clear resets losing unbounded work, and it maps cleanly to the post-commit hook’s agent.artifact { status: "committed" } event sequence the supervisor consumes during verification.

Terminal Action — Commit Then Publish, Never Archive

The bundled coordination skill defines the coding agent’s terminal action as:

1. A commit. The post-commit git hook auto-publishes agent.artifact { status: "committed" } with the committed file list. For code changes this is the canonical “done” signal.
2. A manual agent.artifact { status: "done" } (rare). Used only for code-less tasks or to announce named exports peers depend on.

The skill is explicit that the coding agent SHALL NOT invoke /opsx:verify <change-id> or /opsx:archive <change-id> — both are off-limits for the coding agent and are the supervisor’s job:

• Verification runs the supervisor’s five-gate framework (testing → regression → spec audit → doc audit → security audit) against the committed branch. Self-verification by the coding agent bypasses gates and produces a premature agent.verified the supervisor never reviewed.
• Archiving happens on the release branch during the supervisor’s cherry-pick
  • merge flow, not on the agent’s feature branch. Archiving from a feature branch leaves the change directory deleted on an unmerged branch and produces confused history.

The skill frames this positively as a stand-by-after-commit protocol: once the final commit lands, the agent publishes the terminal signal and then waits — it does not reach for verify/archive. While standing by it waits for one of three supervisor messages: agent.verified (work passed — pick up the next task), agent.feedback (fix the listed errors and re-publish agent.artifact), or a further agent.intent (new scope to pick up). This is the actionable counterpart to the role-gating forbidden-commands rule — what to do instead of self-verifying. On the supervisor side, that post-commit agent.artifact is the cue for the supervisor (not the agent) to run /opsx:verify and /opsx:archive.

This is a paw-specific rule for the bundled coordination skill. Single-agent workflows that self-verify can override the rule via the standard skill resolution chain (a user override at <config_dir>/git-paw/agent-skills/coordination.md wins over the bundled default).

Identifier Forms — Branch vs agent_id

Two related forms of an agent identifier appear throughout the broker protocol:

• Branch name — the original git ref (e.g. feat/no-supervisor-flag). Used in git checkout, git worktree, git push, and any other git command.
• agent_id — the dashed slug form (e.g. feat-no-supervisor-flag). Used in every /publish envelope’s agent_id, every /messages/<id> URL, and payload fields that name another agent, such as from in agent.blocked.

agent_id is the slugified form of the branch name. The conversion (named slugify_branch in the source) lowercases the input, replaces every character outside [a-z0-9] with - — underscores included — collapses runs of -, trims leading and trailing -, falls back to the literal agent-unnamed if the result is empty, and prefixes a single-word result with agent- (hotfix → agent-hotfix). Every output therefore matches the agent_id pattern /publish enforces, and no branch can derive the reserved id supervisor.

A branch name may keep _; its agent_id never does. Branch names git-paw derives from spec text keep underscores — a Spec Kit task naming ROOM_SETUP.md produces the branch task/t001-create-room_setup-md — because _ is legal in a git ref and the branch is durable state that recovery and --resume use to look up work. Only the broker’s id grammar forbids _, so the mapping happens at the id boundary: that branch publishes as task-t001-create-room-setup-md.

Match the form to the context: dashed agent_id in any JSON going to or coming from the broker; slashed branch name in any shell command involving git.

Stash Hygiene in Worktrees

When multiple worktrees run side-by-side, every worktree shares the same underlying git stash list. A git stash pop invoked without inspection can pop an entry created by a different worktree, conflict with your in-progress changes, and wipe work. The embedded coordination skill teaches agents three rules:

1. List before pop — git stash list first; inspect every entry’s branch label and timestamp.
2. Inspect before pop — git stash show -p stash@{N} to read the patch contents of the specific entry before popping.
3. Pop only your own — only pop entries you authored on the current worktree. If authorship is uncertain, leave the stash alone and escalate via agent.question.

Blind git stash pop is a data-loss pattern in a multi-worktree session and is not recommended.

Supervisor Acknowledgement of agent.question

When an agent publishes agent.question, it blocks at its prompt waiting for a typed reply. A blocked agent does not poll its inbox for agent.answer responses, so a supervisor that only publishes agent.answer to the broker will see its answer recorded on the dashboard while the asking agent stays blocked indefinitely.

The supervisor skill therefore instructs supervisors (both human and LLM) to both publish agent.answer (the non-error reply shape — agent.feedback stays reserved for corrective errors) and send the answer text to the asking agent’s tmux pane via tmux send-keys. The MCP publish tools include no inbox read, so the dual write applies to agents booted with the MCP tool form too.

Spec Kit Consolidated Worktrees

When git-paw drives a Spec Kit project (.specify/specs/<feature>/), each feature’s current phase decomposes into multiple worktrees:

• One worktree per [P]-marked task (branch prefix task/). These are parallelisable.
• One consolidated worktree per non-[P] task group (branch prefix phase/). Non-[P] tasks share files or context, so a single agent works through them sequentially.

The embedded coordination skill picks up on the branch prefix:

• task/<task-id>-<slug> branches: the agent runs the standard “before/while editing” coordination pattern for a single task.
• phase/<feature>-<phase-slug> branches: the agent:
  1. Works through the listed tasks in tasks.md order.
  2. Flips - [ ] to - [x] for each completed task in the worktree’s tasks.md. The writeback can be a separate commit or bundled with the task’s code change.
  3. Publishes agent.intent for the union of files across the next 1–2 tasks (with a generous TTL) rather than one publish per task.
  4. Publishes agent.artifact with status: "done" only when every listed task shows - [x] in tasks.md. Partial completion is not “done”.

When tasks.md is the merge-conflict surface between worktrees, git’s line-level merge handles per-task checkbox flips automatically. A checkbox writeback to the shared tasks.md is never reported as an ownership violation — the conflict detector exempts that file — while forward and in-flight overlap detection still apply to it.

Workflow phases

The bundled coordination skill structures an agent’s editing work into two phases that mirror the skill’s “Before you start editing” and “While you’re editing” sections.

Before you start editing

Before touching any file, the agent:

1. Reads the spec or task description in full to understand the scope.
2. Publishes agent.intent listing the specific files it plans to modify, a one-line summary, and a TTL in seconds (default 900 = 15 minutes). This advertises ownership to the broker conflict detector so forward conflicts are caught before any edit lands.
3. Polls its inbox once for warnings or overlapping peer intents — not a busy loop, a single poll.
4. Decides on overlap: if a peer’s intent already covers the same files, the agent picks among wait (peer’s TTL is short, work is small), split (narrow the file list to avoid overlap, re-publish agent.intent with the reduced scope), or escalate (publish agent.question describing the overlap so the supervisor or human can decide). If no overlap is reported, the agent proceeds to edit immediately — there is no explicit go-ahead to wait for.

While you’re editing

Once editing is underway, the agent keeps the intent honest and asks rather than racing:

• Re-publish intent on scope growth. If the in-progress work touches files that were not in the original agent.intent, the agent re-publishes agent.intent with the expanded files list before touching the new files. The re-published intent replaces the previous claim for downstream consumers.
• Question on peer overlap. If a peer’s agent.intent arrives in the inbox naming a file in the same module the agent is editing, the agent sends agent.question describing the overlap and pauses edits on the contested file. Silently racing the peer to a commit is forbidden.

The agent MUST NOT:

• Perform pairwise check-ins on every change — the broker is not a chat channel and peers are not waiting for status pings.
• Wait for an explicit go-ahead from peers when no conflict signal exists — silence from the broker means “no overlap detected”, not “permission pending”.
• Block on broker silence — if agent.intent polling returns no overlap, the agent proceeds.

Declaring regions (v0.6.0)

By default an intent claims whole files, so the detector warns any two agents who name the same path. When several agents collaborate on different parts of one shared file, that whole-file warning is noise — and noisy warnings get dismissed, taking real overlaps with them. From v0.6.0, each files entry MAY be an object that declares the regions the agent intends to touch, and the detector then warns only when the declared regions actually intersect.

A files array may mix bare-path strings (file-level intent, the v0.5.0 shape) and region objects freely. Four region kinds are recognised:

• function — { "kind": "function", "name": "<symbol>" }
• class — { "kind": "class", "name": "<symbol>" }
• block — { "kind": "block", "anchor": "<heading or landmark>" } for prose or config files
• range — { "kind": "range", "start_line": N, "end_line": M } when no symbolic name fits

Worked example. Two agents both intend src/auth.rs, but feat-auth is hardening validate_token while feat-session reworks refresh_session:

# feat-auth
curl -s -X POST "$GIT_PAW_BROKER_URL/publish" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.intent","agent_id":"feat-auth","payload":{"files":[{"path":"src/auth.rs","regions":[{"kind":"function","name":"validate_token"}]}],"summary":"harden token checks","valid_for_seconds":900}}'

# feat-session
curl -s -X POST "$GIT_PAW_BROKER_URL/publish" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.intent","agent_id":"feat-session","payload":{"files":[{"path":"src/auth.rs","regions":[{"kind":"function","name":"refresh_session"}]}],"summary":"rework session refresh","valid_for_seconds":900}}'

Because the declared functions differ, no forward-conflict warning fires — the two agents proceed in parallel on the same file. Had both named validate_token, the warning would fire and name the intersecting function.

Four rules govern detection:

• Both sides must declare regions for region-level matching. If either side omits regions (a bare path string), the detector conservatively falls back to a file-level warning — the v0.5.0 safety net.
• Name matching is normalized. Region names are compared after case-folding, trimming, collapsing separator runs (space, underscore, hyphen) to a single form, stripping a trailing (), and stripping a leading declaration keyword (fn, def, function, class) — so spelling variants of the same symbol intersect: validate_token matches Validate Token() and fn validate_token. Genuinely distinct symbols (foo_bar vs foobar) stay distinct.
• Cross-kind comparisons are conservative. A function/class/block region compared against a range always intersects (the detector can’t resolve a symbol to line numbers without parsing source). Named regions of different kinds — say function foo vs block foo — intersect when their normalized names match, because they almost always describe the same construct through different lenses. Both shapes carry a hint noting the comparison was conservative.
• Don’t manufacture narrow regions to dodge a warning. A region you don’t really own hides a collision that resurfaces later as a merge conflict.

Because matching is string-based, three declaration rules keep intents detector-comparable:

• Use the canonical source spelling — declare validate_token, not a paraphrase like token validation logic; the detector cannot equate two paraphrases of the same symbol.
• Declare all the regions the work touches, including shared constant blocks, import sections, and asset files — not only the headline function.
• Re-publish agent.intent when scope grows mid-task, before touching a region that was never declared.

This guidance is taught to agents by the bundled coordination skill (assets/agent-skills/coordination.md, the “Declaring regions” section), which is the authoritative source.

Context budget

After the “While you’re editing” discipline, the coordination skill teaches agents to manage their own context window so they don’t hit an opaque “context length exceeded” failure mid-task and lose uncommitted work. The guidance has four parts:

• Residual-budget heuristic. After the boot block, skill prose, and governance docs load, an agent aims to keep at least ~60% of the model’s context window free for task work. This is a heuristic target judged by the agent, not a config field.
• Three named moments to compact / clear / summarise, in priority order: after each spec scenario completes (compact), when the working set grows past ~40% of the window (compact), and when switching between sub-tasks that don’t share state (clear).
• Commit before you compact. Every compact / clear / summarise operation is preceded by a commit or an agent.artifact publish, so reducing context is never lossy.
• Proactive context-bloat flagging. When an agent’s pane shows a /clear to save <N>k tokens hint with N at or above [supervisor] context_bloat_threshold_k (default 250), the supervisor flags it with a synthetic agent.status carrying phase: "context-bloat"; the agent commits (or publishes an agent.artifact) first, then clears or compacts.

The bundled coordination skill (assets/agent-skills/coordination.md, the “Context budget” section) is the authoritative source for the exact heuristics, the named moments, and the per-CLI compact/clear mechanism table (claude, claude-oss, and a generic fallback). This chapter only summarises it.

Supervisor

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. Sections here document the same rules the skill teaches, so users reading the mdBook can understand the orchestrator’s behaviour without opening the skill file directly.

For the launcher-level “how do I start supervisor mode” walkthrough, see Quick Start: Orchestrator Mode. For the broker-side message contract the supervisor exchanges with coding agents, see Agent Coordination.

Which CLI the coding agents launch with

A supervised launch given neither --branches nor a spec selection runs the same interactive selection flow as git paw start: the branch picker, the assignment-mode prompt, and the CLI picker (uniform, or one picker per branch). Each coding agent then launches with the CLI that selection mapped to its branch — the uniform choice, or that branch’s own per-branch choice. default_cli only pre-selects an entry in those pickers; it never skips them.

The session-wide fallback — --cli, else default_cli, else [supervisor].cli — applies only to launch paths that show no CLI picker, such as --branches without --cli; when none of the three is set the launch fails, naming --cli and default_cli. Spec-driven branches keep their own resolution chain (see Spec-driven launch).

Session layout: the orchestrator runs outside the session

A supervised session holds the dashboard at pane 0, as a full-width top row, and one coding agent per pane from pane 1, row-major below it (at most five per row). No pane runs an orchestrator CLI. The orchestrator is your own agent session, run outside tmux at the repository root. The launch re-renders the exported orchestrator skill (.git-paw/skills/orchestrator/SKILL.md, with the gate commands and the spec-path doctrine) and writes the session context — the session name, the broker URL, the helper paths, any [governance] documents and, under --unattended, the drive-loop directive — into the gitignored sidecar .git-paw/AGENTS.local.md, and prints both paths with the attach hint. The orchestrator reads them and drives the run through the bundled helpers (.git-paw/scripts/sweep.sh, broker.sh) or the MCP server. See Driving the session from your own agent. Its roster row (supervisor) appears on the dashboard once it publishes its own agent.status; the launcher never publishes on its behalf.

[supervisor].cli (else default_cli) names the orchestrator’s CLI in that context and is the coding agents’ last CLI fallback; no orchestrator CLI is needed to launch. It is also the CLI the --unattended drive loop runs headlessly for a judgment call (see Headless hand-off). [supervisor].approval shapes no pane command — it is the approval level of those headless invocations.

A live session started by an earlier release (orchestrator CLI at pane 0, dashboard at pane 1, agents from pane 2) keeps working until it ends: every command derives the agent panes from the session’s recorded dashboard index, and nothing types into that session’s first two panes. Recovering it rebuilds the layout above.

Driving the session from your own agent

The orchestrator is whatever agent session you already use — any agent CLI, at the repository root, outside tmux. git-paw gives it three things:

Both .git-paw/skills/ exports (the orchestrator skill and the cli-setup skill beside it) are in the standard skill-directory layout, so a skill-aware CLI can load them directly; copy or symlink them into a vendor skill directory if your CLI needs that. Over MCP, get_skill serves the same skill under the name orchestrator (or its alias supervisor).

The surfaces it uses.

• Follow the session by blocking on the broker’s event cursor — the MCP wait_for_events tool or .git-paw/scripts/sweep.sh events — carrying the returned cursor forward, and inspect when an event or a stalled wave says to. get_session_status, sweep.sh status and sweep.sh inbox read the roster and the orchestrator’s inbox. A sampled pane capture can miss a prompt that was answered and replaced between two samples, so capture (sweep.sh capture <pane>) is for inspection, not detection.
• Publish verdicts only through the credential-carrying helpers: sweep.sh verified, sweep.sh feedback-gate and sweep.sh conflict-ack (in the root session, the MCP publish_verified and publish_feedback tools do the same). The broker refuses a verdict without the session’s authority credential.
• Answer and announce with sweep.sh answer <agent> <text> [re] and, after each merge, sweep.sh advanced-main <merged-branch> <summary>. Its own questions and main-side intents go through broker.sh --agent supervisor question|intent. The skill contains no raw HTTP request.
• Run the session from the root session with git paw commands or the MCP start_session, pause_session, stop_session and purge_session tools.

Pairing with --unattended. git paw start --unattended adds the in-process drive loop: it keeps the panes moving and escalates every live permission prompt to the broker, approving none. The orchestrator reads those escalations first each cycle, relays each prompt to you in its own session, and runs sweep.sh approve <pane> only on your explicit instruction. It merges as soon as every expected agent is verified and escalates only on a conflict, an exhausted correction cycle or a regression (see Merge orchestration). If the loop exits on its heartbeat, re-run git paw start --unattended to re-attach a drive loop to the live session. The driving session can itself be remote-controlled from a phone — see Remote Control.

Unattended mode (--unattended)

git paw start --unattended runs a supervisor wave to completion with no human in the seat. Without it, git paw start --supervisor builds the tmux session and returns immediately with an attach hint, expecting a human (or a throwaway pane-scraper script) to watch the panes, answer permission prompts, and notice when the work is done. --unattended folds the driving half of that operator loop into the tool itself.

--unattended engages supervisor mode (you do not also need --supervisor), then — instead of returning — runs an in-process drive loop in the foreground git paw start process. It is designed for detached operation: it does not attach a terminal and does not replace your shell with an interactive supervisor CLI. It is mutually exclusive with --no-supervisor.

--unattended approves nothing. The loop detects live permission prompts and escalates every one of them for a human decision; it never answers one. For a run that genuinely does not stop for prompts, the decision has to be made before the prompt exists — in your agent CLI’s own allow rules, or by launching the agents at [supervisor] agent_approval = "full-auto" inside the documented sandbox. See Agent permissions.

Each poll (~15 seconds) the loop:

• Sweeps every coding-agent pane — and only those. It enumerates panes and resolves each to its agent by pane_current_path (never by pane index, which drifts), capturing each coding pane with its own capture-pane call. The dashboard, and any pane no agent worktree owns, is never captured, escalated or typed into.
• Acts only on a live prompt — the prompt’s structural markers (numbered option glyphs and/or the Do you want to … question, with the Esc to cancel footer) anchored on the modal block itself, searching upward from the end of the capture and tolerating up to 13 non-blank trailing lines of non-prompt content below it (a task list, a status strip, a progress footer), so a CLI that renders chrome under its input area doesn’t hide a live modal — and so a prompt offering a “don’t ask again” option is detected too. Beyond that true end, liveness requires the modal’s actual shape (the footer anchoring a line, with an option list nearby), not a bare mention of the footer text in narration or tool output. Prompt-like text scrolled well past that bound is ignored.
• Escalates every live prompt, whatever the command is. The loop makes no judgement about the prompted command — ls -la and rm -rf / are handled identically. The prompt is recorded on the broker as an agent.question review item (from supervisor), written to the manual-decision log, captured as a learning, and listed in the exit summary. No keystroke is sent, to that pane or any other: the orchestrator outside the session reads the review item and relays it to the human.
• Submits a directive left buffered on an idle pane. A pane showing no live prompt and no mid-response marker, whose input box still holds unsubmitted text, has a stranded directive: the CLI swallowed the first Enter into its paste buffer. The loop sends a follow-up Enter first; if the text survives that, it runs the same clear-and-recover sequence nudges use (see below), re-typing the text read from the whole input box. A paste-buffer placeholder is never cleared — it is escalated instead. Neither the live-prompt scan (there is no prompt) nor the ~25-minute stuck detector would otherwise surface that stall. A pane that is actively generating is never touched.
• Keeps the wave moving while a prompt waits. An escalation is non-blocking: one agent parked on a prompt never freezes the others, and the loop does not wait for anyone to answer. Repeated escalations are deduplicated per (agent, command-shape) within a five-minute window, so a prompt still unanswered after that window is re-escalated as a reminder rather than every fifteen seconds. A prompt nobody ever answers does not, on its own, end the run — the wave ends on completion or the heartbeat.
• Leaves judgment calls on the broker — see The loop is a pump, the supervisor is the brain — and hands a question, a merge decision or a correction-exhausted branch to a headless one-shot orchestrator when one resolves.
• Re-engages a gate-failed worker, when [supervisor.correction] auto_loopback is enabled — closing the verify↔fix cycle without a human hop.

The loop keeps polling until one of:

1. Completion — a terminal PASS/FAIL verdict is signalled, or every agent’s tasks are checked complete.
2. Stuck / bloat — the stuck-detection signal fires.
3. Heartbeat — about 25 minutes pass without progress, so you are re-engaged with a status summary rather than the loop running forever. Progress is a coding agent’s branch tip moving (a new commit) or its phase advancing (e.g. working → committed → verified/done); the interval is measured from the last progress the loop saw, not from launch. Nothing the loop does itself counts — its escalations, its reminder re-escalations of an unanswered prompt, the learnings it records, its own rebases of a branch after a merge — and neither does changed pane output or a repeated working status. So a wave that keeps committing is never cut off at 25 minutes, while a wave whose agents all sit on unanswered prompts still exits one interval after its last progress. Before exiting, the loop takes one fresh status look, so a done published during a long tick still ends the run as completed.
4. Session torn down — the loop’s own session instance is purged, stopped, or replaced (see Session-instance lifecycle below).

On exit it prints a summary: the outcome (completed / escalated-for-review / stuck / heartbeat / session-torn-down), each agent’s resolved final state and its merged/unmerged status, the deduped list of prompts escalated for human review, a line stating that the orchestrator runs outside the session and its CLI is not monitored by the loop, and pointers to the broker log and captured learnings. Because there is no human to hand-write findings, the loop self-captures qualitative learnings during the run and once more at wind-down.

A heartbeat, stuck or interrupted exit ends the loop, not the session — the panes, their conversations and their worktrees are all still there. Re-run the same git paw start --unattended to drive it again; see Re-attaching a drive loop to a live session.

Each agent’s final state is resolved from the most-progressed lifecycle phase ever observed for it during the run — not simply the last /status row — so a generic working heartbeat published after a verified/done artifact event can never make a finished worker look unfinished in the summary.

The merged/unmerged roll-up is ref-derived, never inferred from a worker’s reported status. A worker reaching verified/done says nothing about whether its branch ever reached the default branch — reporting a wave completed on the strength of worker status alone was the failure mode a 0.16.0 external dogfood surfaced: the summary read completed, 2/2 branches merged, zero escalations, while main was unchanged and both branches were still ahead. At exit the loop asks git directly, once per coding branch, whether the branch tip is an ancestor of the default branch (git merge-base --is-ancestor); a comparison git cannot make (a deleted branch, a bad ref) counts as unmerged — the fail-safe direction, since this summary is the input to a destructive git paw purge. The wave-level roll-up line (e.g. 2/2 branches merged) and each agent’s own line (<agent>: <phase> · merged / <agent>: <phase> · unmerged (N ahead of <default>, tip <sha>)) both come from this same ref check, and print for every outcome with coding agents — a heartbeat exit gets the same truth, not only a completed one. completed now implies every branch is merged. A wave that finishes with any branch unmerged reads escalated-for-review instead, with one [unmerged] escalation entry per unmerged branch, so “Escalations awaiting human review” can no longer read 0 while work sits un-integrated — check this list, not just the outcome word, before running purge.

CLI unavailability

A rate-limited or logged-out coding agent is an explicit non-success signal — not a silent idle pane the loop waits out for up to 25 minutes. Each poll, every coding-agent pane’s capture tail is also scanned for a CLI-unavailability marker (a usage/session-limit phrase, an organisation spend-limit phrase, or a login-loss phrase such as an expired/missing credential). A match becomes a deduped cli-unavailable escalation that quotes the matching line, and the loop keeps driving the rest of the wave; a wave carrying one is never reported completed, and that worker’s branch shows as unmerged in the exit summary regardless. Text on the dashboard — whose broker log can quote a worker’s banner — is never scanned.

The scan tolerates the same bounded trailing region of non-prompt content the live-prompt gate does, so a banner is still found underneath chrome a CLI draws below it — current Claude Code’s persistent task list, a status strip, or similar — rather than only a fixed last few lines. A marker separated from the end of the capture by more than that bound still counts as scrolled away and is ignored, same as before.

Markers are resolved per pane, for its own CLI: a [clis.<name>] override of cli_unavailable_markers applies to that CLI’s panes, falling back to the embedded Claude Code default (which includes You've hit your session limit, an organisation org's monthly spend limit, an expired/missing login, and an invalid API key) when the CLI has no override. The override resolves from that pane’s own broker-reported CLI (the /status snapshot), so it only takes effect once that pane has published at least one status — a pane’s first sweep of the run, before any /status row exists for it, always falls back to the embedded default for that one tick. git paw __prompt-profile --field cli_unavailable_markers reads the exact same resolved field the loop does — it is a read path for the bundled sweep.sh helper’s other detectors (stuck-shape, live-prompt) to stay in sync with the Rust side, not a second detector: sweep.sh itself does not consult cli_unavailable_markers or evaluate a pane for CLI unavailability today.

A cli-unavailable escalation is deduplicated on the agent and the matched marker — never on the banner line’s full text, which can carry a reset time or countdown — so the same banner observed across sweeps is one escalation, while two distinct banners on one agent (e.g. a session limit followed later by a login failure) are two.

The orchestrator runs outside the session, so the loop has no pane to watch for the orchestrator’s own CLI dying — every exit summary says so explicitly (The orchestrator runs outside the session; its CLI is not monitored by the loop.) instead of implying coverage it does not have.

Nothing in an unattended session approves a prompt — the loop escalates and the human answers. The dashboard subprocess runs no approver either, attended or unattended; it renders the broker log and nothing more.

Re-attaching a drive loop to a live session

A drive loop ends while the session it was driving is still perfectly alive — on the heartbeat, on a stuck signal, or because you interrupted it. To drive that session again, re-run the same git paw start --unattended command in its repository:

# Drove the wave the first time; drives it again the second time
git paw start --unattended --from-all-specs

The live session is neither relaunched nor forked. Launch-selection flags (--branches, --specs, --from-all-specs, --cli) are never applied to a session that already exists — attaching a new agent to a live session is git paw add — and that is exactly what lets the original launch command double as the re-attach command. No paw-<project>-2 is created.

What it does next depends on the session’s effective status:

A revive or recovery that fails fails the command, without running a loop.

The terminal is never attached, even from an interactive shell — the drive loop occupies the foreground process, exactly as it does on a fresh --unattended launch. The command prints the session name and the git paw attach line for watching it from another terminal.

In every other respect the re-bound loop is the same loop: the same cadence, the same escalation, correction and heartbeat behaviour, the same exit summary, and it approves nothing. It drives the session’s own agent roster, and reaches the broker at the endpoint recorded for that session rather than the one in your current configuration — so a [broker] port changed after launch cannot point the loop at another repository’s broker, or at none.

Bare sessions are refused. A session started without supervisor mode deliberately leaves its boot prompts unsubmitted for a human to send, and the loop’s buffered-input recovery would submit them. start --unattended against one exits non-zero naming the session, stating that only a session launched in supervised mode can be driven unattended, and pointing at git paw attach for driving it by hand. Nothing about the session is changed. A --dry-run likewise binds nothing and is unaffected.

One drive loop per session

Two loops on one session would each nudge, submit buffered input and escalate into the same panes, so at most one may drive a session instance at a time. Every loop — whether from a fresh launch or a re-attach — holds a drive-loop binding: a lease file at .git-paw/tmp/drive-loop.binding (gitignored, beside the approval claims) naming the session instance and the loop itself. It is refreshed every poll and released when the loop exits.

A start --unattended that finds a live loop already holding the binding refuses before changing anything — no session, pane or worktree state is touched, and no second loop runs. It exits non-zero with an error naming the session, the process id holding the binding, and the binding file. Wait for that loop to exit (or stop that process), then re-run the command.

A loop killed without releasing its binding does not wedge the next one. A binding that stops being refreshed lapses after the staleness window — the larger of four poll intervals and two minutes, and of the window the holder itself recorded, so a loop polling more slowly than the caller is never displaced while it is alive — and the next start --unattended simply takes it. There is never a lock file to clear by hand. A loop that exits cleanly releases its binding immediately, so a re-attach right after a heartbeat exit binds without waiting at all.

Two start --unattended runs that reach a lapsed binding at the same instant still produce exactly one loop: the binding is read, judged and rewritten under an exclusive lock (.git-paw/tmp/drive-loop.lock), so the second runs its check against the first’s result and refuses. That lock file is left in place between runs; it is empty, and nothing needs to be done about it.

git paw stop revokes the session’s binding, and recovering a stopped session supersedes any binding left behind for it. A loop that finds its binding revoked or taken over exits session-torn-down on its next poll without acting — see Session-instance lifecycle below.

Deleting .git-paw/tmp/ ends a running loop. The binding goes with it and the loop exits on its next poll. That is fail-safe rather than destructive: a loop that is not running approves nothing, so the panes go on waiting for a human exactly as they would have. Re-run git paw start --unattended to bind a new loop.

Upgrading mid-run. A drive loop started by a git-paw older than this one holds no binding, so a re-attach is not refused while it is still running — and you would end up with two loops driving the same panes. Stop that older --unattended process before re-attaching to its session.

Session-instance lifecycle

A loop binds to the specific session instance it began driving — not just the session name — and re-confirms on every tick, before it sweeps or sends anything, that it is still that instance’s driver. Two things must hold:

• The session receipt still describes the instance it bound to. The receipt’s creation timestamp is the durable instance token. If the receipt is gone, its created_at no longer matches (a new session of the same name was started after a purge), or its status is now stopped, the loop is done.
• The drive-loop binding still names this loop. git paw stop revokes it, and a re-attach that recovers a stopped session supersedes it.

Either one failing exits the loop immediately — without sweeping panes or sending any keystrokes — rather than continuing to drive whatever now occupies that session name. This is what makes purge/stop safe to run against a session still being driven unattended: the old loop notices on its very next poll and gets out of the way instead of escalating prompts from a session it no longer owns.

The binding covers the gap the receipt alone cannot see. Recovering a session keeps its created_at, so a session stopped and recovered inside one poll interval looks unchanged to the receipt check — and the loop bound to the stopped instance would go on driving the recovered one. Revoking the binding on stop is what tells it otherwise.

# Drive every discovered spec to completion, unattended
git paw start --unattended --from-all-specs

# Or a fixed branch set
git paw start --unattended --branches feat/auth,feat/api

Multiple feedback → fix → re-verify cycles per agent are normal and are not treated as a stuck signal — the loop lets agents iterate.

The loop is a pump, the supervisor is the brain

The drive loop is deliberately mechanical: it cannot decide anything. The orchestrator is the opposite — it can reason about anything — and it runs outside the session, so the loop never types into it. Every judgment call the loop meets is a broker review item, and nothing is injected into any pane:

The loop never waits on any of them: one call being deliberated cannot freeze the wave, and every record stays on the broker until it is answered. The orchestrator reads them there — through sweep.sh, the broker helper or the MCP server — and so does a human reading the dashboard’s broker log.

A permission prompt is relayed, not decided. Deciding it from the pane text would make the orchestrator a classifier — one reading untrusted output, and so reachable by prompt injection. The orchestrator puts the prompt in front of the human, naming the agent and the command, and runs sweep.sh approve <pane> only when the human explicitly says to.

A nudge is sent reliably, not fired and forgotten. Typing text into a pane and immediately following it with Enter is not enough: on a paste-aware CLI the text can land in a paste buffer, and a bare follow-up Enter against a stale input line is a proven no-op — it does not submit anything. So every nudge — a worker re-engagement, and a stranded directive’s recovery — sends the text, waits the CLI’s configured settle delay (the same [clis.<name>].submit_delay_ms the boot prompt uses), then sends Enter as a separate keystroke. Verification waits that same settle delay again, so the pane has redrawn, before taking the check capture — and judges by the input box’s content, never by comparing it against the sent text verbatim: a long nudge wraps onto more than one visual row, and only its first row still carries the prompt sigil, so an exact-equality check would misread a wrapped line as already delivered. The text counts as still present when the input box is non-empty and either starts with that first row or shows a paste-buffer placeholder; it counts as submitted once the box is empty or the pane has left its idle state. A line still present is recovered by clearing it (Ctrl-U), re-typing the text read from the whole box, and sending Enter again, up to a bounded number of attempts. A pane still wedged after every attempt is escalated to the broker for human review and listed in the exit summary’s escalations — deduplicated per pane, so a persistently stuck line is reported once rather than on every ~15-second sweep. The whole send — the first attempt through every recovery attempt — runs under the target pane’s exclusive claim (see “One approver per pane, enforced” below), so a recovery only ever clears a line the loop itself just put there, never text a worker agent typed.

No nudge is sent once the loop is winding down. The wind-down/exit state is checked before dispatching any nudge on a tick, so a worker’s idle pane gains no further unsubmitted text on the loop’s way out.

Worker nudges skip finished workers. Any nudge aimed at a worker pane is suppressed once that worker has finished — its broker status is done or verified. The signal is deliberately the broker status and never a pane-content diff: a finished worker’s pane is just as unchanging as a stuck one’s, so a diff cannot tell “idle because done” from “idle because stuck”. A worker that later leaves the finished state becomes nudge-eligible again — the verdict is deferred, not dropped.

Note this is a narrower set than the one stall detection treats as terminal, which also counts blocked and committed. That is deliberate: those two are exactly the states a worker occupies while it awaits correction — committed and standing by for re-verification, or blocked and not polling its inbox — and they are precisely who the correction loop exists to re-engage. Suppressing them would silently disable it for its most common path. Finished and quiet are different conditions; only the first ends a worker’s eligibility for a nudge.

What the orchestrator does with a judgment call is documented in the bundled supervisor skill under Judgment calls handed to you: derive spawn order from the agents’ agent.intent declarations and the conflict detector’s edges; answer a question from the specs plus cross-agent state; sequence merges after verifying; and declare a worker unrecoverable only per max_cycles / on_exhausted.

The human is the exception handler. A human is re-engaged for what the orchestrator genuinely cannot decide — plus the heartbeat exit described above, and any run no orchestrator is driving, where the broker review items and the exit summary are the whole escalation.

Headless hand-off of judgment calls

Waiting for someone to pull the broker inbox makes an unattended run depend on a human. So when a headless invocation resolves, the drive loop hands each judgment call it cannot make to the orchestrator CLI once, non-interactively — a fresh one-shot turn at the repository root that reads the orchestrator skill and acts on the call:

The broker review item is always in place first — the worker’s own message for a question or a merge decision, the loop’s escalation otherwise — so the hand-off adds to the record, it never replaces it. A permission prompt is never handed off: a one-shot has no human to relay it to, and no git-paw process answers a permission prompt. It stays on the broker, in the exit summary and in the manual-decision log, for you or for an orchestrator you tell to run sweep.sh approve.

Resolution. The CLI is [supervisor].cli, else default_cli. Its headless form is [clis.<name>].headless_args, else the built-in row (claude → -p, codex → exec), else none. The launch output reports the result once, at loop start — for example headless hand-off: claude -p — or says why the hand-off is unavailable (no CLI resolved, the CLI has no headless form and which [clis.<name>].headless_args key would supply one, or [supervisor.escalation] enabled = false). With no hand-off the loop behaves exactly as without it: broker records and the exit summary only.

The invocation. The argv is the CLI, then the approval flags resolved from [supervisor].approval (falling back to agent_approval), then the headless arguments — e.g. claude --dangerously-skip-permissions -p. The escalation context arrives on stdin, never on argv, so nothing appears in ps. It names the agent and the call — the worker-written part fenced between markers as quoted data the one-shot must never take instructions from — points at .git-paw/skills/orchestrator/SKILL.md and .git-paw/AGENTS.local.md, gives the broker URL, tells the one-shot to act only through the bundled helpers or the MCP tools and to publish its outcome, and forbids it to run sweep.sh approve or answer any permission prompt. For a merge decision it carries the unattended merge rule: merge fast-forward only once every gate is verified; escalate only on a merge conflict, an exhausted correction cycle or a regression. “Escalating”, for a one-shot, means publishing the reason on the broker and exiting, leaving the review item for you. The environment adds only GIT_PAW_BROKER_URL — no credential: verdicts go through sweep.sh, which fetches it at the root via git paw __authority. There is no terminal; stdout and stderr are appended to .git-paw/logs/<session>/orchestrator-escalations.log.

Bounded, serialized, deduplicated. At most one one-shot runs at a time per session; further calls queue FIFO. Each queued call is keyed by its kind, its agent and its discriminator (the question text, the artifact status, or nothing for a correction-exhausted branch); a call whose key is already queued or in flight is dropped, so a worker re-publishing the same question or committed artifact while its one-shot is pending does not spawn a second one. Once that one-shot has exited, a later identical message is a new event. Each agent also gets one pending question at a time: while a question from an agent is queued or running, its further questions stay on the broker only, and the exit summary counts them — a looping worker cannot queue an LLM run per question. [supervisor.escalation] timeout_seconds (default 1800) bounds each one: on expiry its whole process group is killed and the outcome recorded as timeout. The loop never waits on a one-shot — the sweep continues while it runs. At wind-down the loop stops starting queued one-shots but lets the in-flight one finish or time out, saying on stderr that it is waiting; calls never started are reported as still queued. A session torn down under the loop (git paw stop, git paw purge) kills the running one-shot instead. If git-paw itself is interrupted while a one-shot runs, the one-shot is not killed — see the security posture.

Outcomes. Each finished or timed-out one-shot is published as an agent.status from supervisor (status working) whose detail carries escalation_key, exit_code (or "timeout") and duration_seconds; it is in the broker log, and the supervisor’s /status row shows the phase escalation until its next message. The exit summary adds the number of invocations with a per-outcome count (completed, non-zero exit, timed out), the number still queued and the escalation-log path — or, when no invocation ran, why the hand-off was unavailable or disabled. A handed-off escalation is still listed among the escalations awaiting review.

[supervisor]
cli = "claude"
approval = "full-auto"      # what the one-shot may do unattended — see below

[supervisor.escalation]
enabled = true              # default
timeout_seconds = 1800      # default; 0 is rejected

What a one-shot can do depends on [supervisor].approval. Nobody answers the one-shot’s own permission prompts, so it can do exactly what its approval level and the CLI’s own allow rules permit. Under auto with the git paw setup-cli grants it can read state and answer a question through the broker helper, but it cannot publish a verdict or merge: sweep.sh verified, sweep.sh feedback-gate and sweep.sh conflict-ack are deliberately never granted, and git merges fall under your own rules. A merge-decision hand-off therefore needs approval = "full-auto" — recommended only inside the sandbox — or allow rules you write yourself. See the security posture for what full-auto means here.

Set enabled = false when you drive the session yourself. Your own interactive orchestrator and a one-shot would otherwise act on the same judgment call at once. Disabling the hand-off restores broker-only behaviour without any other change.

Unattended correction loop

When a supervisor gate fails, git-paw publishes agent.feedback to the branch’s inbox — but a blocked worker is not polling its inbox, so the correction stalls until a human re-engages the pane by hand. That single human hop was the dominant cost measured across the v0.9.0–v0.11.0 dogfoods (4–8 manual verify↔fix cycles per branch).

The [supervisor.correction] table promotes that cycle into the drive loop. Enable it with:

[supervisor.correction]
auto_loopback = true       # default is false, for back-compat
max_cycles = 5
on_exhausted = "escalate"  # or "abandon"
escalate_after_cycles = 3

With auto_loopback = true, each poll the loop:

1. Watches for failing gate verdicts. A gate failure arrives as an agent.feedback from the supervisor whose errors carry a [<gate>] tag naming one of gate_tags (default: [testing], [regression], [spec audit], [doc audit], [security audit], [scope]) — the shape .git-paw/scripts/sweep.sh feedback-gate publishes. A passing gate publishes agent.verified instead, so only failures start a cycle. Other traffic on the same channel — conflict-detector warnings, peer feedback — is never mistaken for a gate verdict. The tag vocabulary is configurable (see gate_tags) so a review process with different gate names can still drive the loop; the five-gate verification framework itself is unchanged.
2. Re-engages the worker’s pane. The branch’s pane is resolved by pane_current_path, re-captured immediately before the send, and typed with the gate-tagged feedback plus a submitting Enter as a separate keystroke. If the fresh capture shows the pane is no longer idle (a permission prompt went up between the sweep and the send), nothing is typed and the correction is retried on the next poll — deferred, never dropped.
3. Counts the cycle. Each delivered re-engagement spends one of the branch’s max_cycles. A branch that reaches a terminal PASS leaves the cycle and its counter resets, so an unrelated later failure starts from a fresh budget.
4. Flags a slow converger once. When the count reaches escalate_after_cycles — and that lands strictly before max_cycles — an early heads-up is surfaced while re-engagement continues.
5. Applies on_exhausted when the budget is spent. escalate flags the branch to the orchestrator/human as unrecoverable; abandon marks it failed and sends no escalation. Neither re-engages that branch again, and the exit summary lists it under Correction budget exhausted.

Cycle counts are held in the drive loop’s memory and are not persisted — restarting the supervisor restarts every branch’s budget.

The feature is opt-in: with auto_loopback = false, or with no [supervisor.correction] table at all, the loop sends no re-engagement keystrokes and the gate feedback is published exactly as it was before this existed.

When [supervisor] learnings = true, exhausting a branch’s budget also appends a correction_exhausted learning carrying the branch, the worker CLI, and the cycle count — the tiered-model tuning signal that tells you a worker’s model is under-powered for a class of task. With learnings off, nothing is recorded.

The orchestrator’s own permission level

No pane runs an orchestrator, so no git-paw launch flag reaches your interactive orchestrator: it runs in your own agent session, under whatever permission mode you started that session with. [supervisor].approval changes no pane command; it is the approval level of the drive loop’s headless one-shot invocations, falling back to agent_approval when unset. When it resolves to full-auto for a CLI with no built-in flag row and no [clis.<name>].approval_args override, the loop prints a warning naming the CLI and the override key and runs the one-shot without flags. Coding agents resolve their flags from agent_approval alone — setting approval never changes a worker pane.

auto resolves to a deterministic permission mode

agent_approval accepts three levels: manual, auto, and full-auto. full-auto maps to the CLI’s native skip-permissions flag (for example claude --dangerously-skip-permissions); manual appends no flags at all. Previously auto also appended no flags, so an auto pane silently inherited whatever default its CLI’s config directory happened to carry — sometimes manual approval, sometimes something else, depending on machine state outside git-paw’s control.

auto now resolves to an explicit, deterministic flag per CLI wherever one exists: for Claude this is --permission-mode acceptEdits — file edits are accepted by the CLI without asking, while shell commands still raise a prompt, which git-paw escalates for you. Codex’s auto already resolved to --sandbox workspace-write. A CLI with no such mode keeps the empty string and runs at whatever its own default is, unless you supply a [clis.<name>] approval_args override.

These resolved flags are git-paw’s only influence on what an agent may run without asking. Everything the chosen mode leaves prompting stays prompting: git-paw escalates it and waits for you. See Agent permissions.

Launch reliability: acceptance dialogs and dead-pane detection

Two failure modes could previously leave an unattended wave silently dead at boot:

• First-run acceptance dialogs. The first time a CLI launches with a bypass-permissions flag against a config directory that has never accepted it, some CLIs show a one-time confirmation dialog before their normal UI appears — for example Claude Code’s bypass-permissions dialog, which defaults its highlighted option to “No, exit”. A pane launched unattended into that dialog exited within seconds without git-paw noticing. The launch-readiness gate now recognises this dialog (and a “trust this folder?” prompt) as a distinct state and answers it by selecting the affirmative option by its text, never by a hardcoded digit or a blind Enter — so the default-to-exit trap is never sprung. A dialog the gate cannot resolve fails the launch loudly instead of silently continuing; a CLI whose dialog the gate does not recognise falls back to the prior readiness/relaunch behaviour unchanged.
• Panes that reverted to a bare shell. git-paw launches every pane as a shell and send-keyss the CLI command into it. When a CLI process exits — whether from an unanswered dialog, a crash, or any other reason — the pane does not close; it reverts to its underlying interactive shell. tmux has-session alone cannot tell a live wave from one where every agent’s CLI has quietly died, because the session (kept up by the dashboard pane) still exists. git paw status and git paw doctor now additionally require at least one agent pane whose foreground process is not a bare shell before reporting a session healthy, so a fully-dead wave is reported stale/stopped rather than active. A session within its first ~30 seconds is exempted from this check — the CLI needs a moment to start.

Pane Layout and Labelling

When you attach to a supervisor session, git-paw styles the tmux panes so the boundary between the top row (the full-width dashboard) and the agent grid below is easy to see. By default each session gets:

• Double-line pane borders (═║) instead of tmux’s default light ─│ lines, so the rows visibly separate even with four or more agents.

• A per-pane label strip above every pane — a reverse-video label bar showing its index and role:

  ╔═ 0: dashboard ══════════════════════════════════╗
  ║ (live agent table)                              ║
  ╚═════════════════════════════════════════════════╝
  ╔═ 1: feat/cold-start ════╗╔═ 2: feat/conflict-det ═╗
  ║ (coding agent)          ║║ (coding agent)         ║
  ╚═════════════════════════╝╚════════════════════════╝
  

  Pane 0 is always dashboard and the agent panes are labelled with their branch id (feat/<branch>). The index shown is the same one you pass to tmux send-keys -t <session>:0.<N> (window 0; the session’s second window, broker, hosts the broker), so you can cross-reference the label strip with the broker’s /status agent listing.

• An active-pane highlight — the focused pane’s border is cyan-bold while inactive panes are dimmed, so you always know which pane has keyboard focus.

These options are applied only to git-paw-managed sessions (paw-*); your other tmux sessions keep their own styling. They apply to plain git paw start sessions too, not just supervisor mode.

Set [layout].border_affordances = false in your config to opt out and inherit your own tmux styling — see the Layout configuration reference. Opting out changes only the styling: git-paw still tags each pane with its role, which is what status and doctor read to tell whether a session’s agents are running. On tmux older than 3.2 the double border lines aren’t recognised; git-paw prints a warning and continues with the remaining affordances rather than failing.

Understanding what the supervisor is doing

You rarely need to read the orchestrator’s own session to know what it is up to. The supervisor tags each status heartbeat it publishes with a phase — a short label for its current lifecycle activity — and a structured detail body. The dashboard’s supervisor row shows the current phase in its status column, and the MCP get_session_status tool returns the same phase and detail so external tooling can read it programmatically. (Both surfaces degrade gracefully: a supervisor that hasn’t published a phase renders with its plain status, exactly as in v0.5.0.)

The supervisor emits these phase-tagged statuses through the bundled .git-paw/scripts/sweep.sh status-publish helper — --phase <phase> sets the label and --detail '<json-object>' carries the structured body, while the plain status-publish <message> form (no flags) publishes the v0.5.0 shape unchanged. The helper shapes the agent.status payload internally, so the supervisor never hand-rolls the JSON. Because the helper always lives at the stable path .git-paw/scripts/sweep.sh, a permission rule in your agent CLI scoped to that exact path covers every phase without a broad HTTP-client rule.

Every sweep.sh publish verb — status-publish, verified, feedback-gate, conflict-ack, learn, answer, advanced-main — checks the broker’s HTTP response. When the broker does not accept the publish (any non-2xx status, or no response at all), the helper prints the broker’s error to stderr and exits non-zero instead of printing its “published” line. A non-zero exit means the event did NOT reach the broker: fix the cause (a malformed target agent id, a stopped broker) and re-publish rather than treating the verb as done. The agent-side broker.sh behaves identically.

The phases, with what each one means:

The phase taxonomy is an open set: the supervisor may publish a value not in this table, and the dashboard renders it as-is. The supervisor emits a status on every phase transition and at most once per ~30 seconds while it stays in the same phase, so the row stays current without flooding the broker log. Phases are surfaced for the supervisor row only — coding-agent rows render as they always have. (The one exception is the supervisor-published stuck-on-prompt alert, which appears on a stalled coding agent’s own row.)

Resolve Pane to Agent via pane_current_path

Before the supervisor tmux capture-panes or tmux send-keyss a specific agent, it needs the pane index for that agent. The bundled supervisor skill is explicit that pane indices are NOT alphabetical by agent_id, NOT in the CLI-argument order from git paw start --specs A B C, and SHALL NOT be inferred from git paw status output or the dashboard’s row order (both of those are sorted alphabetically by the broker, which has no relationship to the launcher’s internal scan order).

The canonical resolution command queries tmux directly:

tmux display-message -t <session>:0.<pane> -p '#{pane_current_path}'

<session> is the session name recorded in .git-paw/AGENTS.local.md; window 0 holds the panes (the session’s second window, broker, hosts the broker). The output is the pane’s working directory. For coding-agent panes that is the agent’s worktree path — <repo>/.git-paw/worktrees/feat-<branch> under the child placement git paw init configures, or <project>-feat-<branch> beside the repo under the sibling placement. Matching it against the worktree_path entries in the per-repo session file (.git-paw/sessions/<session>.json) gives the owning agent’s branch_id — the authoritative agent_id (with the slash form feat/<branch> for git operations). A pane whose pane_current_path is <repo>/.git-paw/worktrees/feat-auth belongs to agent feat-auth. Because the directory name depends on the configured placement, the match is against the recorded worktree_path, never against the directory’s basename.

The session file’s roster also records a pane_index, but that is a launch-time value and is not used for routing — the live pane_current_path match is.

The orchestrator reads the roster when it needs an agent’s pane rather than building a pane map once and reusing it for the session, and in any case re-reads it after git paw add or git paw remove — the roster changes and tmux renumbers panes on layout changes. The roster can also be read through the helpers or the MCP get_session_status tool.

The bundled .git-paw/scripts/sweep.sh invokes this command on every sweep iteration. If the helper is missing for any reason, the supervisor falls back to invoking tmux display-message directly — this is the documented escape hatch.

The supervisor MUST NOT use git paw status output (or the dashboard’s row order) as a mapping source — both are sorted alphabetically by the broker and have no relationship to the launcher’s pane assignment. Always resolve via pane_current_path first.

Pane-driving and cross-worktree git disciplines

The bundled supervisor skill hardens three behaviours so a multi-agent session runs without the human approving the supervisor’s every command:

• Use .git-paw/scripts/sweep.sh for pane work; never inline loops. Ad-hoc for p in <panes>; do tmux send-keys -t ...:0.$p ...; done loops trip the simple_expansion permission gate on each iteration, so one sweep becomes one approval prompt per pane. The helper does the explicit per-pane sends with no variable expansion. A single explicit tmux send-keys -t ...:0.<index> is reserved for pushing one typed reply to one pane.
• Never send-keys to the dashboard (pane 0). It is a TUI, not an agent; keys sent there land in the dashboard, not in any agent. sweep.sh targets coding-agent panes by design.
• Cross-worktree git uses git -C <path>, never cd <path> && git. A bare cd trips the untrusted-hooks warning on some CLIs and leaks the working directory, so a later mutating git command can land on the wrong branch. git -C scopes the directory to the single command.

The skill also nudges any agent whose uncommitted working set exceeds ~10 files to commit its completed section, preserving per-section verification granularity.

Spec audit governance sub-step

When a project’s .git-paw/config.toml lists governance documents under [governance] (adr, test_strategy, security, dod, constitution), the supervisor reads each doc as part of the Spec Audit gate and flags drift between the diff and the doc’s checklist. The five canonical doc-checklist examples are:

• DoD (Definition of Done) — walk each - [ ] item against branch state.
• ADRs (Architectural Decision Records) — verify new architectural decisions (new deps, new patterns) have a matching ADR.
• security.md — walk each security checklist item against the diff.
• test-strategy.md — check that test composition matches the documented strategy.
• constitution.md — check the diff against documented principles (e.g. “no panics in library code”).

Findings surface as standard agent.feedback errors tagged [doc audit] mixed in with other doc-audit gaps. See Governance for the config schema and how the supervisor reads each doc.

Agent permissions

git-paw does not approve permission prompts, and makes no judgement about whether an agent’s command is safe. It has no safe-command list, no danger list and no path-based safety rule. Whether a command runs without asking is decided entirely by the agent CLI’s own permission system:

1. The CLI’s resolved permission mode. [supervisor] agent_approval maps to each coding agent’s native launch flags — see auto resolves to a deterministic permission mode. This is git-paw’s only influence on what runs unprompted.
2. The CLI’s own allow and deny rules. Whatever that CLI reads from its own settings. Pre-approve your routine dev commands there; that is the only place a standing grant can live. A grant is only as narrow as you write it.
3. A sandbox, if you want a kernel-enforced boundary rather than a policy one — see Sandbox and Security Posture.

Anything the resolved mode leaves prompting stays prompting. git-paw’s job starts there: it detects the live prompt and escalates it for a human decision (the broker agent.question the orchestrator reads, the manual-decision log, and the exit summary) without blocking the rest of the wave. Then a human decides, and the approval is typed only by an explicit sweep.sh approve <pane>.

A fully prompt-free unattended run therefore needs the decision made before the prompt exists: either CLI allow rules covering everything the agents do, or agent_approval = "full-auto" inside a sandbox. Without that, expect escalations.

Deprecated: [supervisor.auto_approve] and [supervisor.common_dev_allowlist]. Up to v0.16.0 these configured a git-paw command classifier that answered prompts it judged safe. The classifier is retired: three successive security reviews each found new command shapes it wrongly called safe, and each fix opened the next hole. Both tables still parse and round-trip, so existing configurations load unchanged — but they have no effect, and each configuration file that declares them prints one deprecation warning per process. Delete them at your leisure, and move any safe_commands, stacks or extra entries into your agent CLI’s own allow rules. See the configuration reference.

The classifier used to choose “Yes, and don’t ask again” for prompts it judged safe, and your CLI persisted those as durable grants in its own settings file. Retirement stops new ones; it removes none. Review that file and delete what you did not intend — git-paw never edits or deletes it.

Run dev commands bare — no exit-code-probe wrappers

A CLI allow rule matches a command prefix, so it generalises across argument variants. Wrapping a command in an exit-code probe — <cmd> && echo "EXIT $?", <cmd>; echo $?, RC=$?; echo "$RC" — defeats that: the probe text varies per run, so the CLI’s command-string matching never matches the next invocation and the command re-prompts every time. The bundled supervisor and coordination skills instruct agents to run dev commands bare and read the exit status directly; keep your own commands to the same shape so a grant actually suppresses the prompt.

(git-paw used to normalise the two most common wrappers away before classifying. With no classifier there is nothing to normalise for, and the CLI’s own matching was never forgiving about them anyway. Run them bare.)

The explicit approve action

sweep.sh approve <pane> is the only path by which an approval keystroke reaches a pane, and nothing in git-paw runs it for you. A human runs it, or tells the orchestrator to run it. It answers the prompt once, with option 1, and consults nothing about the command.

Four guards sit between that instruction and the keystroke.

Option 1, never a durable grant. The helper dispatches the digit 1 followed by Enter as two separate keystrokes, reporting approved pane <N> (option 1). It never dispatches a blind cursor-movement sequence — Down + Enter lands on No on a 2-option prompt and takes the permanent “don’t ask again” grant on a 3-option one. Before sending it checks that a numbered option 1 really is on screen (and sends nothing if not), and that option 1 does not itself carry the prompt profile’s broad-grant wording: on some prompt shapes the first option is “Yes, and don’t ask again …”, and pressing it would write a standing permission rule you did not ask for. In that case the helper sends nothing and says why. git-paw never creates a durable grant.

Re-confirm before send. Immediately before dispatching, the helper takes a fresh capture of the target pane and confirms the prompt’s live structural markers still anchor the modal block (the same anchored search and bounded-trailing-region tolerance detection uses, not a fixed ~4-line scan). If the prompt cleared between the decision and the send — the agent moved on, or you answered it in the pane first — no keystrokes are sent, and the helper reports cleared before send, no keys sent. This closes the stray-input race where the option digit would otherwise land in the CLI’s chat box as literal text, polluting context and leaving dangling unsubmitted commands.

Coding-agent panes only. The helper sends keys only to a pane the session’s discovery roster (.git-paw/sessions/<session>.json) lists as a coding agent’s pane_index. sweep.sh approve 0 against a broker-enabled session — pane 0 is the dashboard — sends nothing and reports that the pane is excluded because it is not a coding agent, whatever the capture shows; so does a pane no roster entry claims. In a broker-less session the first coding agent sits at pane 0, and the roster makes it approvable. With no readable roster the helper falls back to refusing pane 0. The drive loop applies the same role-based rule: it never types into the dashboard or an unattributed pane. The refusal cannot be changed by a prompt profile.

One sender per pane, enforced. Keystrokes can come from sweep.sh approve and from the drive loop’s own nudge and buffered-input recovery. If two land on one pane, the second falls through onto whatever appears next. So before sending, every sender takes that pane’s exclusive claim: an atomic create-if-absent of <repo>/.git-paw/tmp/approve-pane-<N>.claim, held across the send and released immediately after. Because the file system decides who wins, exactly one sender can hold a pane at a time, and the exclusion works across processes and languages — the shell helper and the binary compute the same path and honour each other’s claims.

Taking the claim never blocks. A sender that finds a pane already claimed skips it and moves on, retrying later; sweep.sh approve reports pane <N> claimed by another approver, no keys sent and names the claim file. Release is automatic on every exit path, including an error or a crash mid-send. If a sender is hard-killed (SIGKILL) with a claim held, the next one steals it after it has gone untouched for 10 seconds — so a crash costs one pane one sweep, never a permanent wedge. The claim directory is ephemeral and already gitignored; you never need to manage it by hand, though removing a stale file is harmless.

No new broker message is involved in any of this: the trigger that a pane is awaiting approval is the existing agent.status with phase: "stuck-on-prompt", and an escalated prompt uses the existing agent.question.

What detection still does

Prompt detection is the part git-paw keeps, and it is unchanged. The live-prompt gate decides whether a modal is actually on screen: at the capture’s true end, a textual marker (the Do you want to … question or the Esc to cancel footer) within the last ~4 non-blank lines, or a numbered option line anchoring that tail with a textual marker within the last ~15 non-blank lines. The search runs upward over a bounded trailing region, so a CLI that renders a task list or status strip under its input area cannot hide a live modal beneath that chrome; beyond the true end, liveness requires the modal’s actual shape (a footer-shaped line plus an option list), never a bare mention of the footer text in narration or tool output, and a match is rejected outright if the CLI’s idle input box appears below it — a real modal replaces the input box, so seeing one means the footer is a quoted copy.

Detection reports only that a prompt is present, and what command it is asking about (the text between the Bash command / Bash(…) header and the confirmation question, or the target path of a file-operation prompt). That command text is used for the escalation message, the dedup key and the manual-decision log — never to decide anything. A supervisor that merely mentions rm -rf / in prose is not a prompt to run it, and a prompt asking about ls -la gets exactly the same treatment as one asking about rm -rf /.

The window sizes, the trailing bound and the pane-0 refusal are compiled logic. A CLI prompt profile supplies the literals (markers, patterns) and can never widen the gate, change which option approve presses, or lift the pane-0 refusal.

Out-of-worktree write violations

An observed out-of-worktree write attempt by a coding agent — a permission prompt asking to write into operator territory, pane narration describing one, a diff touching operator paths, a stray artifact in the repo-root control dirs — is a boundary violation, and the supervisor skill instructs a two-step response:

git-paw no longer has a mechanical check for this. The protected-path rule existed only to stop the retired classifier auto-approving such a write; with nothing approving automatically, a write prompt into operator territory reaches a human like every other prompt, and the supervisor relays it rather than approving it. The doctrine below is what carries the boundary; for mechanical enforcement use deny rules in your agent CLI’s own settings, or the sandbox.

1. First attempt — scoped feedback. The supervisor sends the agent agent.feedback (via sweep.sh feedback-gate <agent> scope …) naming the worktree boundary and the attempted path, so the agent can rescope: persist inside its worktree, or publish agent.question before any outside write.
2. Repeat by the same agent — operator escalation. A second attempt after the scoped feedback escalates to you via agent.question, naming the agent, both attempted paths, and the feedback already sent — the decision (pause, re-brief, remove) is yours, not the supervisor’s.

The agent-side counterpart is the coordination skill’s memory-isolation briefing (see Agent Coordination): persistent artifacts live inside the agent’s worktree, operator configuration directories are off-limits, and a task that seems to require an outside write becomes a question instead.

Manual approvals

Every prompt the --unattended drive loop escalates is a command that needed you. git paw approvals aggregates them, so you can see which prompts recur and decide which deserve a standing rule in your agent CLI’s own allowlist — closing the loop on repeat friction.

This is written by the drive loop, so it covers --unattended runs only. An attended session (git paw start --supervisor without --unattended) runs no loop and records nothing; git paw approvals still reads any log an earlier unattended run left behind.

What gets recorded

Each time the drive loop escalates a live permission prompt, it appends one JSON line to .git-paw/sessions/<session>.manual-approvals.jsonl:

{ "timestamp": "2026-05-29T12:34:56Z", "agent_id": "feat-auth",
  "pattern": "make integration-test", "first_seen": true }

The loop runs outside the agent’s CLI pane, so it cannot see whether you ultimately pressed Yes or No on the prompt. What it records is the honest, observable signal: a command that required a human decision. A command escalated seven times is a strong allow-rule candidate regardless of each individual yes/no — the friction it causes is what you want to remove.

Exactly one line is written per escalation: a prompt re-seen inside the five-minute dedup window is recorded once, and escalations that are not permission prompts — a cli-unavailable banner, a wedged nudge, a correction-loop signal — are not recorded here at all.

The pattern comes from the escalation’s own prompt slice — the command between the Bash command / Bash(…) header and the confirmation question, or a file-operation prompt’s target path. Surrounding pane text is never scraped, so an accept-edits diff line or a previous command’s output sitting next to the prompt cannot be recorded as if it were the command awaiting a decision. When neither source yields something that parses as a command, no line is written and no permission_pattern learning is emitted — an unusable pattern is worse than a missing one, because it pollutes the promotion report you act on.

Reporting

git paw approvals                       # active session, text table
git paw approvals --json                # machine-readable
git paw approvals --session paw-other   # a specific session
git paw approvals --limit 5             # top 5 patterns by count

The text table sorts patterns by how often each was escalated, with a SUGGEST hint for which of your agent CLI’s own allowlists could absorb it:

PATTERN                       COUNT  SUGGEST
make integration-test             7  user allowlist
./scripts/deploy-staging.sh       3  project allowlist
podman build -t paw-ci .          2  user allowlist

A pattern is suggested for the CLI’s project allowlist when it looks project-specific (a ./-rooted script path, or it contains the project or branch name); otherwise it belongs in your user allowlist, where it benefits every project. Both are rules in the agent CLI’s own settings — the SUGGEST column is a hint, not a rule, and git paw approvals never edits any settings file for you.

When [supervisor] learnings = true, the first sighting of each pattern also emits a permission_pattern learning so it surfaces in Learnings Mode alongside the other patterns.

Opting out

Recording is on by default for --unattended runs. To disable both the log writes and the derived learnings emission for a session:

[supervisor]
manual_approvals_log = false

The opt-out affects writes only — git paw approvals still reads any pre-existing log. See Configuration for the field reference.

Repo-configurable gate commands

The supervisor’s five verification gates each invoke a configurable command substituted from [supervisor] keys at session boot. The eight keys are:

• test_command
• lint_command
• build_command
• fmt_check_command
• doc_build_command
• doc_tool_command — API-doc generator, separate from doc_build_command
• spec_validate_command
• security_audit_command

When a key is missing or empty, the placeholder renders as (not configured) in the supervisor skill and the supervisor gracefully skips the tooling invocation for that gate — the gate’s manual review still applies. doc_tool_command is the one exception: when unset it renders as the empty string (not (not configured)) so the surrounding prose reads naturally for projects that don’t ship an API-doc generator. See Configuration for defaults and examples.

Polyglot bundled skills

The bundled supervisor and coordination skills ship as a single template each, but they render per session against the project’s stack and the resolved spec backend. Two placeholders make this work:

• {{DOC_TOOL_COMMAND}} substitutes the doc_tool_command config value above so doc-audit prose names the actual API-doc tool for your stack.
• {{SPEC_PATH_DOCTRINE}} renders a per-backend path doctrine: OpenSpec sessions see openspec/changes/<name>/... references, Spec Kit sessions see .specify/specs/<feature>/..., Markdown sessions see the flat paw_status: pending shape, Superpowers sessions see docs/superpowers/plans/*.md, and multi-backend sessions list each present backend’s conventions in one paragraph.

A CI no-leak audit asserts that the rendered supervisor skill contains no stack-specific tokens (cargo, rustdoc, .rs:, Cargo.toml, rustc) and no vendor product names outside the explicitly-allowed <!-- allowlist-prose --> span, which carries a deliberate CLI-specific enumeration (the paste-buffer marker wording).

Verification runs the whole suite (never fail-fast)

The supervisor’s testing gate runs the configured test command in a whole-suite / no-fail-fast mode. Most test runners stop at the first failing test group, so a single early failure — typically an environment-specific guard test rather than a code defect — can hide every later suite and produce a false PASS. A run that aborted early is incomplete, not a pass; a testing PASS requires the full suite to have executed.

For git-paw itself, the no-tmux-server guard test trips whenever any paw-* tmux session exists (which it always does mid-session) and sits in an early-alphabetical test binary, so a plain cargo test / just check stops there. The just verify recipe runs the trustworthy gate — GIT_PAW_ALLOW_LIVE_SESSION=1 cargo test --no-fail-fast (the suite is socket-isolated, so the opt-out is safe) plus lint, deny, and audit — and the dogfood config sets [supervisor].test_command = "just verify" so the supervisor uses it automatically.

Per-commit verification

The supervisor verifies each agent’s commit as it lands, not in batches. When an agent publishes agent.artifact { status: "committed" }, the supervisor runs that branch’s five-gate sweep promptly — independent of whether other agents have finished. Waiting for a slower agent so several commits can be verified “together” delays feedback to the agent that already committed and serialises work that is meant to run in parallel; at five-to- eight agents that idles the whole session until the slowest one finishes.

To make the trigger an explicit event rather than something the supervisor has to notice during a pane sweep, the broker posts a supervisor.verify-now message naming the committing branch to the supervisor inbox on every committed artifact. This is on by default; set [supervisor] verify_on_commit_nudge = false to suppress the nudge and rely on the supervisor’s sweep cadence instead.

Per-branch verifications may run concurrently — each gate sweep runs against its own branch in its own worktree, so verifying one agent never blocks starting another’s verification. The supervisor may bound how many sweeps run at once at its discretion. The one legitimate reason to defer a verification is a genuine dependency (one agent’s work needs another’s merge in place first), which the supervisor states explicitly when it defers.

Verdicts go through the helper

The verdict messages — agent.verified, and agent.feedback from supervisor — need the session’s authority credential, so the supervisor publishes them only through the root-side sweep.sh verbs, which fetch it with git paw __authority and send it as X-Paw-Authority:

.git-paw/scripts/sweep.sh verified <agent-id> "<summary>"
.git-paw/scripts/sweep.sh feedback-gate <agent-id> <gate> "<message>"
.git-paw/scripts/sweep.sh conflict-ack <agent-a> <agent-b> <file> ["<note>"]

A raw curl …/publish of either message gets 403 {"error":"authority required"}, and so does the same verb run from inside a worktree (__authority refuses there). See Security Posture.

Recovery from API stream timeouts

The supervisor’s own model stream can time out mid-sweep — most often while it is queueing several agent.feedback or agent.verified publishes in one iteration. Left unhandled, the natural reflex is to fall silent and wait for the next sweep tick, which silently drops the pending feedback: the agent that was about to hear about a regression keeps working unaware, and you get no signal anything went wrong.

The bundled supervisor skill teaches an explicit recovery discipline so a transient timeout no longer loses work:

1. Recognise the failure shape — a mid-stream cutoff, or a transport / stream error in the CLI output. The phrasing is generic so it matches across CLI variants.
2. Checkpoint before risky actions — before any iteration with more than one intended downstream publish, the supervisor publishes a single agent.status “checkpoint” enumerating what it is about to do, giving the recovery path a re-entry point.
3. Replay the missing publishes — on recovery the supervisor re-reads its checkpoint and, for each intended target, polls /messages/<target> since the checkpoint timestamp to see which publishes landed, then re-publishes only the missing ones (the replay is idempotent, so duplicates are safe).
4. Never assume a publish succeeded — a returned publish HTTP call is not proof the record landed; the supervisor confirms by polling or re-publishes idempotently before moving on.

Each successful recovery emits a recovery_cycles agent.learning record, so recurrent timeouts surface in the learnings output. See the “Stream-timeout recovery” section of the bundled assets/agent-skills/supervisor.md skill for the full doctrine, and Learnings Mode for how the recovery_cycles records are aggregated.

Broker-side conflict detector

Starting with v0.5.0 the broker auto-detects three failure shapes between parallel agents and emits agent.feedback (and, where configured, agent.question) on the supervisor’s behalf. All auto-emitted messages begin with the [conflict-detector] token so the supervisor can distinguish detector output from human-typed feedback. The three failure shapes are:

• Forward conflict — two agents publish overlapping agent.intent declarations.
• In-flight conflict — two agents’ filesystem-watched modified_files sets overlap on the same file.
• Ownership violation — an agent’s modified_files include a file inside another agent’s active intent.

See Conflict Detection for the algorithm, configuration, and escalation behaviour.

Learnings aggregator

When [supervisor] learnings = true, the supervisor session records deterministic friction signals (stuck durations, recovery cycles, conflict events, permission patterns) into a markdown file you can review after the run. The supervisor also records qualitative learnings it reasons out over the run — recurring failure shapes, doc gaps, ADR drift, scope mistakes, and tooling friction with git-paw itself — publishing each through the bundled .git-paw/scripts/sweep.sh learn <category> <title> <body-json> helper (never a raw HTTP request). It captures them opportunistically during each sweep and again in a session-end synthesis pass. See Learnings Mode for the file format, the category set, and how to opt in.

When the user types in your session

The orchestrator runs in your own interactive agent session (outside tmux) — you can type at any time while its autonomous monitoring loop is running. The supervisor finishes the current step (spec audit, test run), responds, then resumes the loop. User input is a high-priority interrupt, not a replacement for the loop.

Each kind of user input maps to an existing mechanism — the supervisor does not invent new channels:

1. Status question (“how’s feat-auth going?”, “anything blocked?”) — answered conversationally in the orchestrator’s session using sweep.sh status, sweep.sh inbox, and sweep.sh capture <pane>. Nothing is published to the broker — this is a conversation with the user, not a session-wide event.
2. Directive (“ask feat-auth to use bcrypt”, “tell feat-api to skip the migration”) — published as agent.feedback to the named agent through sweep.sh feedback-gate with the [directive] gate, plus a conversational confirmation to the user.
3. Judgment-call ask (“should we merge feat-a before feat-b?”) — the supervisor applies its normal escalation rules. If the user has already provided enough information to decide, the supervisor answers in its session using its reasoning. agent.question only fires when the call is genuinely ambiguous beyond what the user just provided — typically when the user is asking because they don’t know either.

The mechanisms (sweep.sh status / inbox or the MCP reads, sweep.sh capture, sweep.sh feedback-gate, tmux send-keys, agent.question) are unchanged. The addition is when to use which in response to user input.

Routing through the supervisor

The orchestrator is the single conversational surface: you work in its session and address individual agents through it, rather than tab-switching into each agent’s pane. Two commands you type to the orchestrator drive this.

/agents — the live inventory

Type /agents to the orchestrator, in its own session, and it responds with the current inventory: one row per agent plus the orchestrator’s own supervisor row once it has published a status, each coding-agent row carrying branch_id, status, last_seen, cli, the detected mode, and pane_index. The supervisor row has no pane index — the orchestrator has no pane, and pane 0 is the dashboard:

branch_id   status    last_seen  cli     mode          pane
feat-auth   working   3s         claude  accept-edits  2
feat-api    blocked   90s        claude  unknown       1
supervisor  working   1s         claude  —             —

The inventory is composed from broker GET /status (branch_id, status, last_seen, cli) joined with the live pane_current_path mapping (pane_index). Pane indices are path-resolved, never assumed from ordering — a mid-session git paw add/remove that renumbers the grid is reflected correctly after the next sweep. The mode column is best-effort (accept-edits, interactive, or unknown); unknown is treated as the safe case by /tell.

Known limitation — underscored branches show no pane_index. The join matches an agent’s agent_id against its worktree directory name. A branch containing _ (or a ., or upper case) keeps those characters in its directory while its agent_id maps them to -, so the two no longer agree and the pane goes unmatched: the agent still appears in the inventory with its status and last_seen, but pane_index is empty and mode reads unknown. /tell still reaches it — delivery falls back to the broker agent.feedback path, which is the safe route it uses for unknown mode anyway. Only the send-keys fast path and the pane-mode column are affected. Avoid _ in branch names if you want the pane columns populated.

The supervisor refreshes the inventory at its sweep cadence and caches it in memory. /agents and /tell reuse the cached snapshot while it is younger than [supervisor.tell] inventory_max_age_seconds (default 60), re-polling the broker only when it goes stale. The cache is not persisted — a restarted supervisor rebuilds it on the first command.

/tell <agent> <prompt> — route a prompt

Type /tell feat-auth rebase onto main and the supervisor:

1. Validates feat-auth against the inventory (the slug feat-auth or slash form feat/auth both work). An unknown target is not delivered — the supervisor replies with the candidate list of available agents, e.g. unknown target feat/ghost​; available agents: feat-api, feat-auth.
2. Chooses a delivery mode (see below) and delivers the prompt.
3. Acknowledges in its own session and, when learnings mode is on, records the routing decision (see Learnings).

/tell routes exactly the agent you name and exactly the prompt you type — it never decides the recipient for you and never pipes your prompt into another CLI to generate content. There is no bulk broadcast form in this release; smart, supervisor-decided routing is a future candidate.

Delivery modes

[supervisor.tell] mode selects the default delivery channel:

• feedback (the default) — the prompt is published as an agent.feedback broker message and the agent consumes it on its next inbox poll. Safe for mixed-mode sessions: the prompt is queued and recorded, never raced into a running prompt.
• send-keys — the prompt is injected directly into the target’s pane with tmux send-keys. Faster, but only safe when the target is in accept-edits mode. When you configure send-keys but the target’s detected mode is interactive or unknown, /tell falls back to feedback and prints a note so you can investigate the mode-detection drift. Because of this fallback, send-keys is best reserved for sessions where your agents run in accept-edits mode.

Every /tell is auditable: when [supervisor] learnings = true, each invocation appends a line to a ### Supervisor routing section of .git-paw/session-learnings.md with the timestamp, target, delivery mode, and the prompt (truncated past 200 characters). With learnings disabled, nothing is written.

Proactive routing (opt-in, confirmed)

When a sweep finds an agent blocked on a question you have already answered earlier in the orchestrator’s session, the orchestrator may offer to forward that context — it asks you a yes/no question in its own session and waits. It never routes on its own: no proactive /tell fires without your explicit y. Reply n (or anything else) and the offer is dropped. This keeps the pattern from feeling surveillance-y while it earns trust through dogfooding.

opsx role gating

The bundled skills teach that /opsx:verify and /opsx:archive are supervisor-only, but a coding agent that ignores the prose can still archive a change — the skill is a convention, not a guard. When the session’s spec engine is OpenSpec, git-paw closes that gap with a post-commit role-gating guard.

The guard watches the broker’s agent.artifact { status: "committed" } events. When a commit looks like an archive operation and the committing agent is not the supervisor, it reacts per [opsx] role_gating (see the configuration reference):

• warn (the v0.6.0 default) — publishes an agent.feedback to the offending agent and records an agent.learning with category permission_pattern so the violation surfaces in learnings.
• block — the warn behaviour, plus an agent.feedback to the supervisor requesting a revert. The supervisor performs the revert through its merge-orchestration skill (confirming with the user first unless [supervisor] auto_revert = true); git-paw never runs git revert itself.
• off — the guard is disabled.

Detection heuristic. A commit is archive activity when either signal fires:

1. its subject line matches the canonical archive shape chore(specs): archive <name>; sync deltas to main specs, or
2. its diff moves files into openspec/changes/archive/<name>/ and/or adds a main spec under openspec/specs/<capability>/spec.md.

The two-signal design is deliberately conservative — it would rather trip on the supervisor’s own archive (which the attribution check then clears, since agent_id == "supervisor") than miss a coding-agent archive. An unresolvable worktree is treated as a violation.

Reading the warning. The feedback text names the short SHA, the offending agent, and the trigger so you can spot a false positive at a glance:

opsx-role-gating: detected archive activity on commit abc1234 by agent feat-x
  (not the supervisor).
  Reason: commit message matched the archive heuristic ("chore(specs): archive
  feat-x; sync deltas to main specs").
  /opsx:verify and /opsx:archive are supervisor-only ...

If a warning is a false positive, the named reason tells you which signal fired so you can adjust (or flip role_gating = "off"). The guard is inert under the Spec Kit, Markdown, and Superpowers engines — those have no /opsx: commands or archive paths, so the capability and its skill sections are scoped to OpenSpec only.

v0.6.0 behaviour change. role_gating defaults to warn, so sessions where a coding agent archives a change now see guard feedback. Set role_gating = "off" for the prior (no-guard) behaviour.

Per-CLI setup (consent-only)

Agents call git-paw’s helper scripts constantly, and under most agent CLIs every call raises a permission prompt. The supervisor does not make those prompts go away: a helper call runs without one only through the agent CLI’s own permission system and the rules in its settings.

You can pre-approve git-paw’s own helper calls in that CLI’s allow rules with git paw setup-cli <CLI> --allowlist. It is optional and consent-only — you run it, it prints its plan first, and --undo takes back exactly what it added. Nothing in the supervisor, the drive loop or the MCP surface ever runs it, and it refuses to run from a linked worktree.

The embedded cli-setup skill carries the rules an agent must follow around it. git paw init and git paw start export it to .git-paw/skills/cli-setup/SKILL.md beside the orchestrator skill (main checkout only), and the MCP get_skill tool serves it under the name cli-setup. The supervisor skill restates the three that bind the orchestrator directly: run the writing form only when the human asked in the current conversation, pass --yes only after they approved the exact plan shown, and never run it during an unattended run.

Merge orchestration

Once every spec’d agent has been verified — the orchestrator published agent.verified for it through sweep.sh verified (agents never publish it themselves) — or the user explicitly asks for a merge, the orchestrator runs the merge orchestration loop. v0.5.0 removed the Rust auto-merge loop; merging is the orchestrator’s responsibility, performed with shell, git, the configured test command and the bundled helpers or MCP tools — never a raw HTTP request.

Trigger. Either every spec’d agent has been verified (the orchestrator published agent.verified for it), or the user has explicitly requested the merge.

Unattended runs merge without asking first. When the session context carries the drive-loop directive (--unattended), the orchestrator merges as soon as the trigger holds — fast-forward only — without asking the human first. It holds a branch back and escalates only on:

• a conflict — a non-fast-forward or conflicting branch (skipped, with agent.feedback to its agent), or a dependency cycle (escalated with agent.question);
• an exhausted correction cycle — a branch whose correction budget ran out (escalated with agent.question);
• a regression — a merge that fails the test command (reverted, with agent.feedback to its agent).

Every held-back branch is named in the final summary. In an attended run the orchestrator may still confirm the merge order with you before merging.

Merge order. The orchestrator reads the broker’s message log (sweep.sh inbox / sweep.sh events, or the MCP read tools) and builds a dependency graph from agent.blocked events: each event from agent X with payload.from = Y is an edge “X depends on Y”. The supervisor then topologically sorts the graph: agents with no incoming edges merge first; dependents follow.

Per-branch merge. For each branch in topological order, the supervisor checks out main and runs:

git merge --ff-only feat/<branch>

Never a merge commit — fast-forward only. If --ff-only fails (the branch diverges from main, or there is a conflict), the supervisor SKIPS that branch and publishes agent.feedback to the owning agent asking them to rebase or resolve. On a successful fast-forward, the supervisor runs the configured {{TEST_COMMAND}}; if tests fail, the supervisor reverts the merge with git reset --hard <prev-HEAD> and publishes agent.feedback tagged [regression]. If tests pass, it publishes agent.advanced-main with sweep.sh advanced-main <merged-branch> <summary> — the helper resolves the new default-branch SHA and the base branch name itself — so every dependent agent learns the base moved on its next inbox poll — see When Main Advances — then moves on to the next branch.

Cycle handling. If the dependency graph has a cycle, the supervisor does NOT merge any branch in the cycle. Instead, it publishes agent.question (through broker.sh --agent supervisor question) to the human and waits for guidance before continuing.

Final summary. When the loop completes, the supervisor publishes a final agent.status summarising which branches merged cleanly, which were skipped (and why), and any regressions encountered.

Branch refresh (opt-in)

Over a long wave the supervisor merges peer after peer into the default branch while every other live worker keeps committing on the baseline it started from, so each branch drifts further from what it will eventually be merged into. The only existing recourse is worker-side and advisory — see When Main Advances in Agent Coordination — which correctly tells a worker holding uncommitted work not to auto-rebase, but means refresh only happens when a worker chooses to act.

When [supervisor] branch_refresh = true is set, the supervisor’s unattended drive loop instead performs the refresh itself, at a moment it can prove is safe: after a successful merge (agent.advanced-main), for a branch that is provably idle and clean. This is a supervisor operation, not a worker judgment call — the two disciplines do not conflict, because the supervisor acts only under exactly the condition (no uncommitted work) that makes the worker-side “do NOT auto-rebase” rule unnecessary.

Default off. Rewriting a live agent’s history is opt-in, permanently — set [supervisor] branch_refresh = true to enable it. With the field absent or false, post-merge behaviour is unchanged from every prior version.

Every live worker branch is checked after every merge, and refreshed only when ALL of the following hold. Any single failure leaves the branch untouched — there is no partial or degraded attempt, and the skip is recorded, not retried or escalated:

1. Clean. The worker’s working tree has no uncommitted changes, per the broker watcher’s tracked modified_files — never a fresh probe, so the supervisor and the watcher can never disagree about what “clean” means.
2. Idle. The worker’s pane is not mid-response.
3. Claimed. The supervisor holds the pane’s exclusive approval claim (the same TOCTOU guard approvals use), narrowing the race window between the cleanliness check and the rebase.
4. Conflict-free. A git merge-tree prediction shows the rebase would not conflict — checked BEFORE the rebase starts, so the worktree never enters an in-progress rebase state a live agent could observe. A prediction that proves wrong once the rebase actually runs is recovered with git rebase --abort, leaving the branch at its pre-rebase HEAD.
5. Behind. The branch actually has commits to pull in; an already current branch is left alone.

A branch that has already passed the five-gate supervisor verification and awaits merge is never refreshed — it has been verified at its current base, and rewriting it would silently invalidate that verification.

Notification. After a successful refresh the affected worker receives agent.feedback tagged [branch-refresh] (the same bracket-tag convention as [conflict-detector]) telling it HEAD moved, so it does not keep reasoning about file contents or commit SHAs from before the rewrite. This is deliberately NOT agent.advanced-main — that event means “the base moved” and the worker-side discipline above keys off that exact meaning; conflating it with “your own branch was rewritten” would corrupt that discipline.

Tiered-Model Workflow

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. This chapter is the process — how to set a run up so the cheap fleet actually succeeds. For the mechanics of how the orchestrator drives the wave, see Supervisor → the loop is a pump, the supervisor is the brain.

The two roles

git-paw already gives you both halves:

• Orchestrator — your own agent session outside the tmux session, reading the context a --supervisor launch renders into .git-paw/AGENTS.local.md ([supervisor].cli names its CLI). Its job is judgment: spawn order, answering cross-agent questions, sequencing merges, and deciding when a worker is unrecoverable. Give it your most capable model.
• Worker — an ordinary CLI in a worktree (default_spec_cli / --cli). Its job is execution: implement one change against a concrete task list. This is where a cheaper model earns its keep — if the task list is concrete enough (see below).

Two things make the cheap fleet viable rather than a prompt-storm: the orchestrator handles the judgment calls the loop can’t instead of parking them in an inbox nobody reads, and the self-healing correction loop turns a gate failure into an automatic re-engagement rather than a human hop. Both ship in v0.14.0. What you bring is the two pre-steps this chapter is about: a plan, and a definition of “verified.”

Step 1 — Plan first; planning is not a git-paw command

git-paw does not author your change set — it executes one. Author the plan before git paw start, in any supported spec format: OpenSpec (openspec/changes/<name>/), Spec Kit, Superpowers plan documents, or plain Markdown-with-frontmatter. git-paw starts once those artifacts exist and turns each into a worker session.

Because planning is the one step that most rewards a capable model, do it with your smart model — a planning pass, or an /opsx authoring session — and only then hand the result to the cheap fleet.

Step 2 — Make the tasks task-level concrete (the rule that decides success)

This is the central rule of the whole workflow: a cheaper worker executes reliably only when the tasks artifact is concrete. Vague tasks are where cheap models diverge; concrete tasks are where they succeed — and an under-specified plan costs more in orchestrator correction cycles than a smart worker would have cost in the first place.

Concrete means, per task: the exact files to touch, the per-step verification command, and an explicit acceptance criterion.

# Too vague — a cheap worker will guess, and guess differently each run:
- [ ] Add validation for the config

# Concrete — a cheap worker can execute it deterministically:
- [ ] In src/config/supervisor.rs, reject max_cycles = 0 at load with an
      actionable error (mirror the invalid on_exhausted handling); add a unit
      test asserting 0 fails and 1 is accepted. Verify: cargo test --lib
      config::supervisor.

The OpenSpec/Superpowers task shape (a checkbox list where each item names its file, its verification, and maps back to a spec scenario) is the exemplar. If you find the orchestrator burning correction cycles on a worker, the fix is almost always a sharper task, not a smarter worker.

Step 3 — Define “verified” in your AGENTS.md, not in git-paw

What “verified” means — the exact test/lint/build commands, the acceptance criteria, the definition of done — is a per-project convention, so it lives in your repo’s injected instructions (AGENTS.md / CLAUDE.md), never baked into git-paw. This is the export-agnosticism principle: git-paw ships only the generic five-gate scaffold — testing → regression → spec audit → doc audit → security — and the supervisor follows your concrete gates when it verifies a worker’s branch. Spell them out, or the orchestrator falls back to the scaffold and guesses at your commands.

Wire the gate commands into [supervisor] (test_command, lint_command, build_command, doc_build_command, spec_validate_command, fmt_check_command, security_audit_command) and write the definition of done into AGENTS.md. git-paw’s own AGENTS.md — its “Change Checklist” and “Supervisor verification is a five-gate framework” sections — is the exemplar to model yours on.

Step 4 — Launch, and let the orchestrator drive

With the plan authored and “verified” defined:

# Attended: you watch the panes and answer the permission prompts yourself.
git paw start --specs my-change --supervisor

# Unattended: the in-process loop drives to completion, escalating every
# permission prompt to you rather than answering it.
git paw start --specs my-change --supervisor --unattended

Turn on the self-healing loop so a gate failure re-engages the worker automatically instead of waiting for you:

[supervisor.correction]
auto_loopback = true      # re-engage a gate-failed worker's pane with the feedback
max_cycles = 5            # give up on a branch after this many verify-fix rounds
on_exhausted = "escalate" # escalate | abandon

From here the orchestrator answers questions, sequences merges, and re-engages failing workers on its own; see the correction loop and the pump-to-brain hand-off for exactly what it handles.

Where the human still comes in

You are the exception handler, not the operator. A human is re-engaged only for what the orchestrator genuinely cannot decide, plus two structural cases: the heartbeat exit after ~25 minutes without progress, and a run with no orchestrator session at all (a pure --unattended run nobody orchestrates leaves every judgment call as a broker review item for you, exactly as it did before). Everything the fleet can resolve — safe approvals, cross-agent questions, verify-fix cycles, merge sequencing — resolves without you.

Dashboard

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). That is the same layout in a supervisor-mode session, a bare one and a spec-driven one — every session git-paw builds uses the agent grid. It renders the same live status table that refreshes about once a second (and immediately on a key press), giving you an at-a-glance view of what each agent is doing. A supervised session builds the dashboard pane even with the broker off.

The dashboard is observation-only — it never sends actions back to agents, and no git-paw keystroke sender ever types into it. Beyond q to quit, its keystrokes drive the Broker log panel (toggle, filter, inspect). Human input (questions, directives, replies to agent.question events) happens in the orchestrator’s own agent session, outside tmux; the dashboard simply renders broker state. There is no inbox panel.

What the Dashboard Pane Shows

The dashboard renders a table with one row per agent. Once the orchestrator has published its own agent.status (as supervisor), its row is pinned to the top with a horizontal-line divider beneath it; coding-agent rows follow in alphabetical order:

┌────────────┬────────┬────────────┬─────────────┐
│ Agent      │ CLI    │ Status     │ Last Update │
├────────────┼────────┼────────────┼─────────────┤
│ supervisor │ claude │ 🔵 watching│ 12s ago     │
│ ────────── │ ────── │ ────────── │ ─────────── │
│ feat-api   │ claude │ 🟡 blocked │ 1m ago      │
│ feat-auth  │ claude │ 🔵 working │ 3m ago      │
│ fix-typo   │ codex  │ 🟢 done    │ 8m ago      │
└────────────┴────────┴────────────┴─────────────┘

When no orchestrator has published (e.g. broker-only mode — broker on, no --supervisor — or a supervised session before your orchestrator session has picked up its context), the divider is not rendered and coding agents fill rows alphabetically from the top.

Status Symbols

The Last Update column shows elapsed time since the agent’s last status update (30s ago, 3m ago, 1h 15m ago).

Supervisor row, cli field, and phase field

The supervisor row’s Status column does not show the wire-message type label that a coding-agent row shows. Instead the supervisor publishes a phase field on its agent.status messages (e.g. baseline, watching, approving, answering, merging, summary), and the dashboard prefers that label when rendering its row. This avoids the misleading status=feedback label the supervisor would otherwise show when it publishes agent.feedback to a coding agent.

The orchestrator has no pane and no worktree, so it is not a watch target and the broker cannot infer its cli from the watch-target map. To populate the CLI column for the supervisor row, the supervisor self-registration agent.status includes a cli field (e.g. "cli":"claude"). The broker upserts that value into its internal CLI map when it receives the message.

The CLI column is populated for every agent row, not just the supervisor. git-paw knows each pane’s CLI at launch and pre-fills it authoritatively — coding agents from the watch-target map (the per-repo session JSON), the supervisor from [supervisor].cli/default_cli. Agents do not self-report their CLI (they would only be guessing). A row appears once its pane publishes a status, and its CLI column shows the pre-filled value; if a CLI somehow can’t be resolved it shows a ? placeholder rather than a blank cell.

A coding-agent row can also show stuck-on-prompt in its Status column: the bundled sweep.sh helper’s stuck detector publishes this phase directly on the stalled agent’s own agent.status when its pane shows a permission-prompt marker and its heartbeat has stopped advancing (see Agent permissions). This is the one coding-agent phase outside the generic working/done/blocked/committed set in Status Symbols above.

The roster holds only real agents

The /status agent roster — and therefore the dashboard table — is built only from agents that publish agent.status. The from/target/verified_by identity fields on agent.feedback, agent.question, and agent.verified messages are routed and stored but never mint a roster row. This means a human- or supervisor-originated feedback can no longer create a phantom human agent that never heartbeats. The roster is in-memory, so any pre-existing phantom from an older broker also clears on the next git paw start.

When the supervisor row appears

The supervisor row appears after the orchestrator — your own agent session, outside tmux — publishes its first agent.status as supervisor, its first action on picking up .git-paw/AGENTS.local.md. The launcher never publishes on its behalf, and the drive loop’s escalations (published as agent.question from supervisor) never create the row either, so a session no orchestrator drives shows no phantom supervisor row.

Stalled-wave indicator

Agent rows answer “is this agent alive?” The status line at the bottom of the dashboard answers the question they cannot: “is the wave getting anywhere?” Whenever the broker reports the wave as stalled, the status line carries an indicator naming how long it has been idle:

wave stalled 1h

The reading comes straight from the broker’s wave staleness state, so the same two things clear it that count as progress anywhere else — a wave phase advancing or a branch tip moving. The indicator disappears on the first refresh that reports stalled = false; nothing is shown while the wave is progressing. Tune (or disable) the threshold with [broker] wave_stall_minutes — see the configuration reference.

This is the dashboard’s view of a session that looks healthy row by row and is not moving: every pane alive, every agent working, and nothing having actually advanced since the unanswered prompt.

Controls

Broker log panel

The Broker log panel fills the screen region freed when v0.5.0 removed the prompt inbox. It renders a scrolling, type-filterable list of the broker messages observed during the current dashboard session, newest at the top, so you can watch the session’s wire-level activity at a glance instead of tailing /messages/<id> over curl.

The log is in-memory only — closing the dashboard drops it — and bounded by [dashboard.broker_log] max_messages (default 500). Older messages fall off the top as new ones arrive. The panel is read-only: replying to a question or directing an agent happens in the orchestrator’s own session.

When visible, the panel occupies a fixed 20 rows by default — materially more than its original 12 — so more coordination traffic is visible without constant scrolling. Tune it with [dashboard.broker_log] height_lines. The agent-status table keeps a positive minimum height and absorbs the terminal’s slack, so on a tall terminal the table grows while the panel stays at its configured height; on a terminal too short to grant both, the panel yields space before the table shrinks below its minimum.

Showing and hiding the panel

The panel is visible by default. Toggle it with l, or set the launch default and height in .git-paw/config.toml:

[dashboard.broker_log]
max_messages = 500
default_visible = true
height_lines = 20

When the panel is hidden the dashboard layout is identical to its v0.5.0 post-inbox-removal shape (title, agent table, status line) — the agent table expands to fill the freed space, and the status line gains a broker log hidden — press l to show hint. See the configuration reference for the table’s fields.

Filter chips

A header row of chips sits above the message list, one per broker message type plus an All reset. All is active by default (every message shows). Pressing a digit hotkey (1–9, then 0 for the tenth chip) narrows the view to that type; pressing more digits adds types inclusively; pressing an active chip again removes it (emptying the selection returns to All). Press a to reset to All at any time. Filtering is a view operation — the ring buffer always retains every message regardless of the active chips.

agent.answer messages have no chip of their own; they show in the default All view.

Row format

Each row is a single line: HH:MM:SS · type · agent · summary, where the summary is a per-type one-liner derived from the message body (the status message, the first modified file of an artifact, the blocking need, the intent summary, and so on). Summaries that overflow the panel width are truncated with an ellipsis (…); the full body is available in the details overlay.

┌─ Broker log (7 shown / 7 held) — l hide · a all · 1-9·0 filter · ↵ details · Esc close ─┐
│  All  1:status 2:artifact 3:blocked 4:verified 5:feedback 6:question 7:intent 8:verify-now 9:advanced-main 0:learning │
│ 14:35:09 · status   · feat-auth · working: rebasing onto main                          │
│ 14:34:58 · intent   · feat-auth · wire AuthClient                                       │
│ 14:34:12 · blocked  · feat-api  · needs auth token format from feat-auth               │
│ 14:33:40 · artifact · fix-typo  · done: src/typos.rs                                    │
└────────────────────────────────────────────────────────────────────────────────────────┘

Status activity phrases

An agent.status payload may carry an optional activity field — a short phrase naming what the agent is doing right now. When present it is appended to the status summary in parentheses, so a heartbeat conveys the work rather than just a bare working:

│ 14:35:09 · status   · feat-auth · working (running the test suite)                     │

The field is optional and additive. A status that omits it renders exactly as it did before the field existed, and agents are never required to set one.

Heartbeat collapsing

Agents heartbeat often, and a wall of identical working lines buries the real state transitions between them. The panel therefore collapses a run of consecutive status rows that are identical in every rendered field — same agent, status, activity, and message — into one row carrying the run’s latest timestamp and a ×N repeat count:

│ 14:35:09 · status   · feat-auth · working ×12                                          │
│ 14:33:40 · artifact · fix-typo  · done: src/typos.rs                                    │

Anything that differs breaks the run and starts a new row — a changed status, a changed activity phrase, a different message, another agent, or any non-status message arriving in between. So a real transition such as working → verified always gets its own row, and two distinct working phases separated by other traffic are never merged.

Like filtering, the collapse is a view operation: the ring buffer still retains every individual message, the count in the panel title reflects the rows drawn, and opening the details overlay on a collapsed row shows the newest message of that run.

Details overlay

Highlight a row with the arrow keys (or j/k) and press Enter to open a modal overlay showing that message’s full, pretty-printed JSON in a scrollable view. Press Esc to close it and return to the panel. While the overlay is open, q still quits the dashboard.

Resilience across broker restarts

The panel never clears its buffer when the broker is unreachable, paused or restarted. Historical messages stay visible across the outage, and new messages resume appearing at the top once the broker answers again. A restarted broker host numbers its log from 1 again; the dashboard notices from the host’s uptime going down, re-reads the new log from the start, and appends each new entry once — nothing it already shows is duplicated. A gap in the timestamp column is the only visible sign that messages briefly stopped flowing.

Legacy messages panel

The earlier [dashboard] show_message_log flag rendered a simpler, unfiltered messages list. It is superseded by the Broker log panel and retained only for config compatibility.

Relationship to the Broker

The dashboard is a thin client of the broker. The broker runs in its own process, git paw __broker, in a detached tmux window named broker (outside the pane grid, so pane numbering is unchanged; switch to it to see the host’s stderr). The dashboard (git paw __dashboard, pane 0) holds no broker state: it reads the broker URL from the saved session and polls GET /status and GET /log?since=<seq> on its idle cadence. Closing the dashboard pane has no effect on the broker, its watchers, conflict detection or learnings.

When the broker is unreachable

If a poll cannot reach the broker — git paw pause stopped it, the host is restarting, or a fresh launch has not finished bringing it up — the status line shows ⚠ broker unreachable, the agent table keeps the last snapshot, and the dashboard keeps polling. The indicator is independent of the stalled-wave indicator, and it clears on the first successful poll. An unreachable broker never makes the dashboard exit.

Lifecycle and exit conditions

The dashboard process is bound to its session: when the session ends, the dashboard exits on its own rather than lingering and busy-rendering to a dead terminal (a leaked __dashboard process pegging CPU). Its draw loop checks a single lifecycle gate on every iteration — including any error or degraded path, so no branch can bypass it — and exits when any of the following holds:

• Clean shutdown. tmux delivers SIGHUP when it kills the session or pane, which ends the process.
• Orphaned to init. On Unix, if the parent process is gone the dashboard has been reparented to init (getppid() == 1) — the tell-tale of a session torn down without SIGHUP (an abrupt tmux kill-server, a crash, or the machine sleeping). The loop notices the reparent and exits. On non-Unix platforms this check is inert and only the SIGHUP shutdown path applies.
• Controlling terminal gone. If the pane’s terminal hangs up, reading input (event::poll) errors, or a write to the terminal fails, the dashboard treats its controlling terminal as gone and exits. This catches the case where the pane was killed but the dashboard was reparented to a lingering shell (a live but unrelated parent), so the orphan-to-init check alone would miss it.

An unreachable broker is deliberately not on this list (see above). The broker host has its own lifecycle: it flushes the broker log and exits on SIGHUP (when pause closes its window or stop kills the session), when orphaned to init, or when its terminal hangs up, and it exits non-zero with a diagnostic naming the port if it cannot bind — it never retries in a loop.

Because the dashboard is cheap to relaunch (git paw start re-attaches to the session), exiting eagerly on any of these signals is preferred over risking a leaked, busy-looping process.

Replying to agent questions

Earlier dashboard versions included a “Questions” panel and a “Reply to” input field for human-typed answers to agent.question events. The panel was removed in v0.5.0; the dashboard has no inbox. Questions and replies go through the orchestrator — your own agent session, outside tmux — and its helpers, not through the dashboard.

agent.question messages still flow through the broker. The orchestrator reads incoming questions from the broker (through sweep.sh, the broker helper or the MCP server) and replies with sweep.sh answer (an agent.answer on the broker) plus tmux send-keys to the asking agent’s pane. See the Orchestrator mode chapter and the exported orchestrator skill (.git-paw/skills/orchestrator/SKILL.md) for the reply flow.

See the v0.5.0 changelog for the removal note.

Pause and Resume

git paw pause is the soft-stop verb for short breaks (lunch, a meeting, end-of-day). It freezes the running session without losing agent state, so you can resume mid-conversation an hour later by running git paw start.

The three teardown verbs

git-paw v0.5.0 ships three verbs for taking a session down:

What pause does, mechanically

When you run git paw pause:

1. Every tmux client attached to the session is detached (tmux detach-client -s <session>).
2. When the broker is enabled, the broker host’s broker window is closed, which delivers SIGHUP to the __broker process, which drops the BrokerHandle, which gracefully shuts down the broker and flushes the session’s <session_name>.broker.log. The dashboard pane stays and shows ⚠ broker unreachable until you resume. (A session started by a git-paw from before the broker host split has no broker window — its dashboard pane is the broker — so pause kills that pane instead, as it always did.)
3. The session state file flips from status: active to status: paused.
4. Every coding-agent CLI pane keeps running. Their in-memory conversation, their CLI process, and the worktree they’re working in are untouched.

git paw status shows the paused state with a blue indicator and a “run git paw start to resume” hint.

The RAM trade-off

Pause is fast and state-preserving, but the CLI processes stay allocated. A typical Claude Code instance holds ~300 MB, so a 10-pane session is roughly 3–5 GB of RAM sitting idle while paused.

Pick the right verb based on duration:

• Pause is right for short breaks where instant resume matters more than RAM.
• Stop is right for long breaks where you’d rather get the RAM back. Resuming via git paw start spawns fresh CLI processes — you lose conversation context but the worktrees and branches carry over.
• Hibernate (future v1.0.0) will be both: state preserved AND RAM released.

Resuming a paused session

git paw start

When git paw start detects a paused session that’s still alive in tmux, it takes the restart-from-pause path:

1. Re-creates the broker host in its broker window and waits (up to 10 seconds) for it to answer.
2. Re-creates the dashboard pane at its saved index only if none is running — normally the paused dashboard is still there and simply reconnects.
3. Flips session status back to active.
4. Re-attaches your tmux client.

Cost: one broker boot (plus a dashboard pane only for a session paused before the broker host split). No worktree creation, no CLI process spawn, no boot-prompt injection (beyond submitting the held boot prompt of any agent added with git paw add while paused — and, when that agent’s spec format declares a workflow entry point, the held entry point after it, once its pane goes idle). The agent panes are exactly as you left them — open conversations intact, prompt buffer intact.

If the tmux server died while paused (rare — typically only happens on machine reboot or tmux kill-server), git paw status shows the session as stopped instead, and git paw start falls through to the normal cold-recovery path (fresh CLI processes, resuming each conversation where the CLI supports it — see Per-CLI cold resume).

Idempotency

git paw pause is safe to run repeatedly:

• Pausing an already-paused session prints “Session ‘NAME’ is already paused.” and exits 0 without changing state.
• Pausing a stopped session prints “Session ‘NAME’ is already stopped; pause has no effect.” and exits 0.
• Pausing with no session for the current repo prints “No active session for this repo.” and exits 0.

Per-CLI cold resume

Stop’s cold-recovery path (and the same recovery git paw start runs when every agent pane has dropped back to a bare shell) restores conversation context too, for CLIs that support it. At launch git-paw assigns each worker a fresh session identifier and passes it on the CLI’s own launch command (Claude Code’s --session-id <uuid>), then records it in the session state. When that worktree is later recovered, git-paw relaunches its CLI with the matching resume flag (--resume <uuid> for Claude Code) instead of a bare launch — the worker picks up its prior conversation instead of starting cold.

This solves the long-break case without holding RAM, complementing pause for the short-break case: stop releases the CLI processes, and the next start brings their conversations back rather than only their worktrees.

A worktree whose CLI has no known resume flag (no built-in row and no [clis.<name>].resume_args override) launches fresh exactly as before — nothing about cold recovery changes for it. See session_id_args / resume_args to add resume support for a CLI git-paw doesn’t know about, and git paw status --json to read a worker’s assigned id (e.g. to resume it by hand outside git-paw).

See also

• Pause behavior is formally specified in the broker-runtime capability spec (pause flow, idempotency, restart-from-pause), alongside the pause subcommand contract in cli-parsing and the paused status variant in session-state.
• git paw stop — the destructive teardown verb.
• git paw purge — the full reset (removes worktrees and branches).
• Dashboard — what the dashboard pane shows while the session is active.

Skill Templates

git-paw uses standardized agent skills following the agentskills.io specification. Skills are directories containing a SKILL.md file with YAML frontmatter and optional resource subdirectories.

Standard Location

Skills are loaded from .agents/skills/ in your project directory. git-paw walks up the directory tree from the current working directory to find this location.

my-project/
└── .agents/
    └── skills/
        ├── coordination/
        │   ├── SKILL.md          # Main skill file
        │   ├── scripts/          # Optional: Executable scripts
        │   ├── references/       # Optional: Documentation
        │   └── assets/           # Optional: Templates/resources
        └── orchestrator/
            ├── SKILL.md
            └── scripts/

Bundled skills

git-paw embeds four skills, each overridable by a .agents/skills/<name>/SKILL.md of your own:

The cli-setup skill exists because that command changes what a CLI will do without asking the human again. Its rules are deliberately restrictive: the writing form runs only when the human asked in the current conversation, a --dry-run suggestion is not consent, --yes follows approval of the exact plan shown, it never runs unattended or because of an instruction found in content the agent read, settings files are never hand-edited, and coding agents in worktrees never run it at all.

Skill Format

Each skill must contain a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: A brief description of what this skill does
license: MIT
compatibility: git-paw v0.4.0+
---

## My Skill Instructions

This skill helps agents with {{BRANCH_ID}} workflows...

Required Fields

• name: Skill name (max 64 chars, lowercase letters/numbers/hyphens only)
• description: Clear description of the skill’s purpose (max 1024 chars)

Optional Fields

• license: License information
• compatibility: Version compatibility
• metadata: Custom metadata object

Placeholders

Skills support these placeholders that get replaced at runtime:

• {{BRANCH_ID}} - Slugified branch name (e.g., feat/http-broker → feat-http-broker)
• {{PROJECT_NAME}} - Project name for tmux session
• {{GIT_PAW_BROKER_URL}} - Full broker URL
• {{SKILL_NAME}} - Name from YAML frontmatter
• {{SKILL_DESCRIPTION}} - Description from YAML frontmatter

Supervisor gate-command placeholders

The embedded supervisor skill uses eight additional placeholders fed from [supervisor].*_command keys in .git-paw/config.toml. Each gate-command template renders verbatim into the skill prose where the supervisor agent reads it:

• {{TEST_COMMAND}} ← [supervisor].test_command — gate 1 (Testing) test runner
• {{LINT_COMMAND}} ← [supervisor].lint_command — gate 1 lint sub-step
• {{BUILD_COMMAND}} ← [supervisor].build_command — gate 1 build sub-step
• {{FMT_CHECK_COMMAND}} ← [supervisor].fmt_check_command — gate 1 formatter check
• {{DOC_BUILD_COMMAND}} ← [supervisor].doc_build_command — gate 4 (Doc audit)
• {{DOC_TOOL_COMMAND}} ← [supervisor].doc_tool_command — gate 4 API-doc generator (renders empty when unset, not (not configured))
• {{SPEC_VALIDATE_COMMAND}} ← [supervisor].spec_validate_command — gate 3 (Spec audit)
• {{SECURITY_AUDIT_COMMAND}} ← [supervisor].security_audit_command — gate 5 (Security audit)

(not configured) graceful skip. When a key is omitted from [supervisor], the matching placeholder substitutes to the literal string (not configured) in the rendered skill. The supervisor agent treats that sentinel as “skip the tooling invocation for this gate” and continues with the gate’s manual review only (e.g. the OWASP-category diff scan still runs for the security gate, the spec scenario coverage check still runs for the spec gate). Pre-v0.5.x configs that only set test_command continue to render the remaining gates as (not configured) and the supervisor agent runs them as manual-only — no behavior change for those configs.

The one exception is {{DOC_TOOL_COMMAND}}: when the underlying key is unset, the placeholder renders as the empty string rather than the (not configured) sentinel. The supervisor skill template is authored so the surrounding prose reads naturally without it for projects that don’t ship an API-doc generator.

Backend-aware and constant-driven placeholders

Two more placeholders make the bundled supervisor skill polyglot:

• {{SPEC_PATH_DOCTRINE}} — substitutes a per-backend paragraph that names where specs live and the matching workflow. The variants:
  • OpenSpec: openspec/changes/<change>/{proposal,specs,tasks}.md plus openspec validate.
  • Spec Kit: .specify/specs/<feature>/{spec,plan,tasks}.md plus the Spec Kit checklist convention.
  • Markdown: flat .md files with paw_status: pending frontmatter.
  • Superpowers: plan files under docs/superpowers/plans/*.md, worked ### Task N step by step with - [ ] → - [x] checkboxes.
  • Multi-backend: one sentence per present backend, introduced by a “This session spans multiple spec backends” clause.
  • No backend resolved: a sentinel sentence pointing the supervisor at the project’s documentation.
• {{CHANGE_ID}} — see the per-invocation discussion below.

{{CHANGE_ID}} is per-invocation, not per-render. Spec validators typically take a change name as argument (e.g. openspec validate my-change-id --strict). To support that, the spec_validate_command template MAY embed the literal substring {{CHANGE_ID}}. git-paw does not substitute {{CHANGE_ID}} at session boot — it passes through the render verbatim. The supervisor agent expands it at verification time using the change name it is currently auditing. This matches how {{BRANCH_ID}} behaves for coding agents (per-agent, not per-render).

Resource Subdirectories

Skills can include optional resource subdirectories:

• scripts/ - Executable scripts referenced by the skill
• references/ - Detailed documentation and references
• assets/ - Templates, configuration files, and other resources

Example structure:

.agents/skills/my-skill/
├── SKILL.md              # Main instructions (< 500 lines)
├── scripts/
│   └── setup.sh          # Executable helper script
├── references/
│   └── api-reference.md  # Detailed API documentation
└── assets/
    └── config-template.json

Creating Custom Skills

To add a custom skill:

# Create skill directory structure
mkdir -p .agents/skills/my-skill

# Create SKILL.md with proper frontmatter
cat > .agents/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Custom workflow for our team
license: MIT
compatibility: git-paw v0.4.0+
---

## Custom Team Workflow

Follow these steps for {{BRANCH_ID}}:
1. Analyze requirements
2. Implement solution
3. Test thoroughly
4. Document changes
EOF

# Add optional resource directories
mkdir -p .agents/skills/my-skill/scripts
mkdir -p .agents/skills/my-skill/references

Skill Resolution

git-paw searches for skills in this order:

1. .agents/skills/<name>/SKILL.md (walking up directory tree from current directory)
2. Embedded defaults (compiled into git-paw binary)

The first match wins. If no skill is found, resolution fails with an error.

supervisor is an alias of orchestrator: both names resolve to the same skill, and an override directory under either name applies to both. When .agents/skills/orchestrator/ and .agents/skills/supervisor/ both exist, the orchestrator one wins, so an override written under the old name keeps working until you rename it.

Exported skills

git paw init (and every git paw start) also writes two bundled skills into the main checkout for the agent that drives the session, in the same standardized layout:

• .git-paw/skills/orchestrator/SKILL.md — the orchestrator skill, rendered with your [supervisor] gate commands and configured spec format. It holds no session value (no broker URL, no session name); those live in the session context .git-paw/AGENTS.local.md.
• .git-paw/skills/cli-setup/SKILL.md — the cli-setup skill, as embedded.

Each opens with name / description frontmatter whose name equals its directory name, so a skill-aware agent CLI can load the directory directly. .git-paw/skills/ is gitignored and binary-managed: a re-run overwrites it, and an override under .agents/skills/ is what the export renders from. See Supervisor → Driving the session from your own agent.

Validation

Skills are validated against the agentskills.io specification:

• Required name and description fields must be present
• Frontmatter must parse within the supported subset (below)
• Skill directory must contain SKILL.md file
• Clear error messages for validation failures

Supported frontmatter subset

git-paw parses SKILL.md frontmatter with a small, dependency-free parser rather than a full YAML library, so it supports a bounded subset rather than arbitrary YAML:

• Top-level key: value pairs, where the value is a plain, single-quoted, or double-quoted scalar (surrounding whitespace is trimmed from plain scalars).
• Literal (|) and folded (>) block scalars, including their strip (-) and keep (+) chomping indicators.
• Full-line and trailing # comments outside quoted scalars.
• A one-level metadata mapping of string keys to scalar values — every value is read as a string.
• A key git-paw doesn’t consume (for example allowed-tools: followed by a list) loads fine; it’s skipped along with any indented content beneath it.

This parser does not silently misparse. If name, description, license, compatibility, or metadata uses a construct outside this subset — a flow mapping or list ({ a: 1 }, [a, b]), an anchor or alias (&foo, *foo), a YAML tag (!!str), or a nested mapping inside metadata — the skill fails to load with a validation error naming the field, rather than silently producing a different value. This applies to your own override skills too: a SKILL.md you hand-write under .agents/skills/ is held to the same subset as the embedded skills git-paw ships.

Examples

See the agentskills.io specification for more examples and best practices.

Migration from Older Versions

If you’re upgrading from git-paw v0.2.x or earlier:

1. Move skills from ~/.config/git-paw/agent-skills/ to .agents/skills/
2. Convert single .md files to directory structure with SKILL.md
3. Add required YAML frontmatter to each skill
4. Organize related resources into subdirectories

The new standardized format improves interoperability and enables skill sharing across different AI systems that support the agentskills.io standard.

When Skills Are Not Injected

Skill templates are only injected when the broker is enabled ([broker] enabled = true). If the broker is disabled, no coordination instructions are added to AGENTS.md.

Boot-Prompt Injection

In addition to skill template injection, git-paw automatically injects a standardized boot instruction block into every agent’s initial prompt. This ensures reliable agent self-reporting even if skill templates are not used or if agents don’t read the AGENTS.md file thoroughly.

The boot-prompt injection covers every essential coordination operation (register, done, blocked, question) with the agent’s id pre-expanded, as calls to the bundled .git-paw/scripts/broker.sh helper — or, for CLIs known to speak MCP (the built-in set is claude, codex, cursor-agent, agy), as MCP publish-tool calls — and is active in both supervisor and manual broker modes. Set [clis.<name>] mcp = true|false to override that set for a given CLI identity. See the Coordination documentation for details.

Docs Fetch Skill

git-paw bundles a docs-fetch skill and a matching helper script so an agent can consult git-paw’s own documentation on demand — pulling exactly the convention or example it needs, when it needs it, instead of carrying doc content in its boot prompt or guessing.

The design mirrors the other bundled helpers (broker.sh, sweep.sh): the skill teaches when and why to consult the docs, and the helper does the fetch. The agent invokes one stable script path rather than hand-rolling curl, so one permission rule in your agent CLI scoped to that exact path can cover every call, and the behaviour stays deterministic.

What the agent gets

When the docs-fetch skill is rendered into an agent’s instructions, the agent is told to reach for the helper — .git-paw/scripts/docs-fetch.sh — whenever a git-paw fact is unclear (a subcommand’s behaviour, a config field, a coordination or governance convention, a workflow). Documentation is fetched live and only when asked; none of it is embedded in the binary or injected wholesale into the boot prompt.

The two operations

The helper is a thin, dependency-free wrapper (curl + Python 3, the same primitives the broker helper uses). It exposes a discover-then-retrieve flow that matches the machine-readable surface published by the agent-friendly docs site (llms.txt and per-page anchors).

find <query> — fetch the site’s llms.txt index and print the pages that best match the query, each as a title, absolute URL, and one-line summary:

.git-paw/scripts/docs-fetch.sh find "worktree placement"

get <page-or-url> [anchor] — fetch a page (by the URL or path from find) and print its documentation content. Pass a section anchor to narrow the output to just that section instead of the whole page:

.git-paw/scripts/docs-fetch.sh get user-guide/worktree-placement.html
.git-paw/scripts/docs-fetch.sh get user-guide/worktree-placement.html child-vs-sibling

Configurable docs source

The docs base URL defaults to git-paw’s published documentation site and is overridable so a fork or mirror can point the skill at its own docs. Set the top-level docs_base_url field in .git-paw/config.toml:

docs_base_url = "https://docs.example.com/git-paw"

The helper resolves the base URL from config, falling back to the built-in default when the field is absent. Both find and get target the configured URL.

Best-effort by design

Documentation lookup is an aid, never a hard dependency of the agent’s task. If the docs site is unreachable, a page does not exist, or an anchor is unknown, the helper exits non-zero with a short diagnostic (and never hangs — every fetch is time-bounded). The skill instructs the agent to continue its task without the docs in that case rather than block or retry in a loop.

Least-privilege install

git paw init installs docs-fetch.sh into .git-paw/scripts/ alongside broker.sh, sweep.sh, and the shared _paw_common.sh preamble they source. Nothing is seeded into the agent CLI’s settings file, and git-paw approves no prompt for it. The point of the stable path is that you can write one permission rule naming .git-paw/scripts/docs-fetch.sh — invoked directly or as bash <path> / sh <path> — instead of a broad curl wildcard. That one by-path rule covers every subcommand, so an agent consults the docs without any wildcard network permission. Without such a rule the helper simply prompts like any other command, and the prompt is escalated to you.

Governance

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. You point at the docs in .git-paw/config.toml; git-paw does not generate or vendor any of them.

Why governance docs

The supervisor is an LLM. It does the right thing more often when it can see the rules the team has already written down: which architectural decisions are settled, what tests are expected, what security review looks like, what “done” actually means. Without that context the supervisor has to infer from the diff alone, and inference drifts.

git-paw’s stance on governance is deliberately thin:

• You own the documents. Their structure, format, and rubric are whatever your team already uses (Scrum, XP, OWASP, adr-tools, Spec Kit, hand-rolled). git-paw does not template them.
• You opt in per doc. Empty [governance] table, all fields None, no behaviour change from v0.4. Add only the docs you have.
• The supervisor applies judgment. There is no [governance.gates] table and no per-doc enforcement switch. The supervisor reads each configured doc as context during its audit and surfaces relevant findings via agent.feedback.

Pointing at your docs

Add [governance] to .git-paw/config.toml:

[governance]
adr = "docs/adr"
test_strategy = "docs/test-strategy.md"
security = "docs/security-checklist.md"
dod = "docs/definition-of-done.md"
constitution = ".specify/memory/constitution.md"

All five fields are optional. List only the docs you have. Paths are resolved relative to the repository root; absolute paths are accepted as-is. A missing file does not break config-load — the runtime flags it if the supervisor tries to read it.

[governance] also accepts two more optional pointers, readme and docs (your README and documentation root). They feed the MCP server’s documentation tools rather than the supervisor’s audit.

For Spec Kit projects, governance.constitution auto-wires to .specify/memory/constitution.md when [specs] type = "speckit". You only need to set constitution explicitly if you keep it somewhere else, or want to disable the auto-wiring (set it to "").

At launch, the configured paths reach the orchestrator as a ## Governance documents section in its context — the gitignored repo-root sidecar .git-paw/AGENTS.local.md that git paw start --supervisor writes and names, and that your orchestrating agent session (outside tmux) reads — placed after the supervisor skill content so the orchestrator reads them in the same context as its own instructions. The tracked AGENTS.md is never modified, and the context carries no per-agent spec or file-ownership content. A path left unset — or set to the empty string, as with the constitution = "" opt-out above — contributes no bullet, and a [governance] table with no paths at all adds no section.

See Configuration → Governance for the full field reference and merging rules.

Illustrative examples

The shapes below are examples, not templates. git-paw never reads structure — only the content of the file you point at. Use whatever format your team already uses.

ADR-0001 — Adopt PostgreSQL for the primary store

# ADR-0001: Adopt PostgreSQL for the primary store

Status: Accepted
Date: 2026-02-14
Deciders: backend team

## Context

We need a primary datastore for user, session, and billing tables.
Options considered: PostgreSQL, MySQL, CockroachDB, DynamoDB.

## Decision

We will use PostgreSQL 16 hosted on our existing managed service.

## Consequences

- All new schema lives in PostgreSQL; we will not introduce a second
  relational store without a follow-up ADR.
- Migrations go through `sqlx-migrate`; ad-hoc DDL in code review is
  rejected by default.
- Read replicas are an operational concern, not an application one —
  applications connect through the connection pool, not directly to
  replicas.

A typical ADR directory has one file per decision (0001-postgres.md, 0002-event-bus.md, …). Whether you use Nygard, MADR, or your own headings does not matter — git-paw passes the directory pointer to the supervisor, which reads the files it finds.

Definition of Done

# Definition of Done

A change is "done" when every box below is checkable:

- [ ] All new behaviour has at least one test covering the happy path
      and one covering the failure mode.
- [ ] `just check` passes locally and in CI.
- [ ] Public functions have rustdoc comments.
- [ ] If a config field was added, the configuration docs section
      that owns it is updated.
- [ ] If a CLI flag was added, `--help` text and `cli-reference.md`
      are updated.
- [ ] If user-visible behaviour changed, the changelog has an entry.
- [ ] The PR description names the spec/issue it implements and
      lists any deviations.

Anything left unchecked goes in the PR description as a known
follow-up with an owner.

Security checklist

# Security Checklist

For every change touching authentication, authorisation, network I/O,
or persisted data:

- [ ] User input is validated at the boundary (HTTP handler or CLI
      arg parser), not in the business logic.
- [ ] Secrets never appear in logs, error messages, telemetry, or
      stack traces. The redaction helpers in `crate::log::redact`
      are applied at the producer side.
- [ ] No new dependency on `unsafe` crates without a written
      justification in the PR description.
- [ ] If the change introduces a new external request, the URL is
      built with a typed builder, never with `format!` over user
      input.
- [ ] Authorization checks happen before side effects — never after.

Test strategy

# Test Strategy

## Pyramid

We invest most heavily in fast, deterministic tests:

- **Unit tests** (`#[cfg(test)] mod tests {}`) — pure logic, no I/O.
  Every public function in `src/` has at least one.
- **Integration tests** (`tests/`) — exercise CLI boundaries with
  `assert_cmd`. Use real filesystems via `tempfile`, never mocks.
- **End-to-end smoke tests** (`tests/e2e/`) — kicked off in CI for
  the happy path of each subcommand. Slow and few; tagged with
  `#[ignore]` so contributors can opt in locally.

## What we do not test

- Generated output of `--help` strings (already covered by clap).
- Rendering loops in the TUI — covered manually via the smoke list
  in `docs/src/user-guide/dashboard.md`.

## Test data

Always synthesise — never copy production data, even anonymised, into
fixtures. Fixtures live under `tests/fixtures/` and are kept small
enough to read at a glance.

Constitution (Spec Kit-style)

# Project Constitution

## Spec-driven

No behaviour ships without a spec. The spec is the contract; the
implementation matches the spec; the tests assert the spec. If the
implementation drifts from the spec, the spec is updated first and
re-reviewed.

## Behavioural tests, not implementation tests

Tests assert observable inputs and outputs. Tests do not assert
internal struct field values, internal function calls, or mock
interactions.

## One commit per logical change

Every commit builds, passes `just check`, and is independently
revertable. PRs may contain multiple commits, but no commit may leave
the tree broken.

Spec Kit users typically keep this file at .specify/memory/constitution.md; git-paw auto-detects it when [specs] type = "speckit".

What the supervisor does

When the supervisor verifies an agent’s change, it reads the configured governance documents alongside the diff. Findings flow through the existing agent.feedback channel — the supervisor does not crash or block on governance, it surfaces what it sees and lets the agent respond.

How the supervisor audits against these documents is described in the bundled supervisor skill, and the MCP server’s governance tools serve the same documents to MCP clients. This chapter and the [governance] config table (the core-governance-config capability) are the path-pointer slot only.

Rollout suggestion

Adopt incrementally — there is no requirement to fill in all five paths at once:

1. Start with the doc you already have. Point governance.dod at your existing DoD, or governance.constitution at your principles doc.
2. Run a supervised session. Note which findings feel useful and which feel noisy.
3. Add the next doc. Each pointer narrows the gap between what the supervisor knows and what the team already agreed on.
4. If the team does not have one of these docs at all, write the smallest version you can live with rather than copying a template. The supervisor reads what you wrote — not a generic checklist.

You do not need a full governance framework to benefit from this. A two-paragraph DoD pointed at by governance.dod is more valuable than a perfect-but-empty [governance] table.

Learnings Mode

Learnings mode records deterministic friction signals from a supervisor session into a markdown file you can review after the run. It is an opt-in feature: it requires supervisor mode to be active and the [supervisor] learnings = true flag to be set explicitly. The markdown file is always written; when the broker is enabled, each record is additionally published as an agent.learning broker message (see Programmatic consumption).

Contents

• Why
• Privacy & Sharing
• Enabling Learnings Mode
• Output File
• The Deterministic Categories
• Qualitative signals (v0.6.0)
• Sample Output
• Flush Cadence
• Programmatic consumption: agent.learning (v0.6.0)

Why

Supervisor runs absorb a lot of recurring friction silently: sandbox warnings the agent retries past, approvals you reflexively click, brief stuck states, conflicts caught and resolved before they hit your eyes. Each event is too small to interrupt for, but the pattern is the most useful signal git-paw can surface for tool, prompt, or process improvement.

Learnings mode aggregates those events into four deterministic categories (plus the supervisor’s qualitative signals) and writes them to a markdown file you can read between sessions — turning silent friction into something you can act on.

Privacy & Sharing

Learnings mode performs no telemetry. The aggregator writes to exactly one place — the local .git-paw/session-learnings.md file in your repo. The broker it observes binds to 127.0.0.1 by default, and git-paw ships no outbound HTTP client: nothing about your session is collected, uploaded, or phoned home under any configuration. The feature is also fully opt-in — it runs only when you set [supervisor] learnings = true (default false), and a session that has not opted in behaves exactly as if the feature did not exist.

That makes the learnings file yours: a purely local artifact you can read, keep, or delete. When a session starts with learnings enabled, git-paw prints a one-line reminder of where the file lives and that nothing leaves your machine, so the privacy stance is visible at the point of use, not just here.

Optional sharing. If a session surfaces a recurring rough edge that looks worth fixing in git-paw itself, the most useful thing you can do is share that context with the maintainers. This is a deliberate, manual action — there is no “share now” command and no automatic upload. To contribute, open an issue on the git-paw issue tracker and attach (or paste) the relevant part of your session-learnings.md.

Review before you share. The file contains repo-specific details — branch names, file paths, spec IDs — that you may not want public. Read it first and strip or anonymise anything sensitive. git-paw deliberately does not scrub the file for you: only you know what is sensitive in your repo. Your own LLM or agent CLI can help here — ask it to redact paths and identifiers before you paste the result into an issue.

Enabling Learnings Mode

Set the master switch on the [supervisor] table (default false):

[supervisor]
enabled = true
learnings = true

The subsystem only activates when supervisor mode itself is active. With [supervisor] enabled = false (or no [supervisor] section), the learnings = true value is parsed and ignored — no aggregation runs and no file is written.

Output File

When active, the learnings subsystem writes to:

.git-paw/session-learnings.md

The file lives in the repository root’s .git-paw/ directory. It is:

• Append-only across sessions. Each session’s first flush adds a ## Session Learnings — <ISO-8601 UTC start time> heading, and later flushes and later sessions append below it; nothing is overwritten or pruned.
• Human-readable markdown. No JSON or binary; you can tail, grep, or open it in any editor between sessions.
• Not committed by default. git paw init adds it to the project’s .gitignore alongside the other .git-paw/ runtime files.

The Deterministic Categories

The aggregator tracks four deterministic categories, each written under its own ### heading in the session’s block. Each bullet is a one-line summary; a category with nothing to report is omitted from that flush.

Conflict events

One bullet per conflict the broker conflict detector reported via a [conflict-detector]-tagged agent.feedback or agent.question, classified as:

• Forward conflicts — two agents’ agent.intent declarations overlap (recorded with a forward-conflict-… label). Use these to spot specs that were decomposed too coarsely (two parallel agents both expected to own the same file). A forward conflict is labelled forward-conflict-intra-spec when both agents were launched from the same spec and forward-conflict-cross-spec when they came from different ones, using the spec each agent was launched from. The broker host learns that mapping from real launch data: a fresh launch registers every agent with the host together with its spec id, git paw add --from-spec does the same for a hot-added agent, and a recovered or resumed session’s host reads it from the saved session. An agent started without a spec (a bare git paw start, or git paw add without --from-spec) has no recorded spec, so its forward conflicts classify cross-spec; only the specs that are known are named in the bullet.
• In-flight conflicts — two agents are modifying the same file at once.
• Ownership violations — an agent edited a file claimed by another agent’s active agent.intent. Records the violator, the owner, and the file. Use these to spot agents that drifted out of their declared scope.

The detector’s symmetric warnings (one per agent in the pair) collapse into a single bullet.

Where agents got stuck

Stuck duration: the time between an agent’s agent.blocked (naming the agent it waits on in from) and its next agent.artifact. A block still open when the session ends is recorded as unresolved, with the duration measured up to shutdown.

Recovery cycles

The recovery-cycle count: how many agent.feedback messages an agent received before its agent.verified (or before session end, if it never verified). A high count marks an agent that needed many correction rounds. Zero cycles is not recorded.

Conflict acknowledgements are excluded from the count. A [conflict-ack] feedback (see Conflict Detection) tells an agent that an overlap it was warned about has been adjudicated — it asks the agent for nothing, so counting it would report correction rounds that never happened.

Permission patterns

Commands that repeatedly needed a human decision. git-paw approves no permission prompt, so this is not a count of automatic approvals: under --unattended, the first time the drive loop escalates a given command it emits a permission_pattern learning (when manual_approvals_log is also on). The list shows which commands your agents trip on most, so you can pre-approve them in your agent CLI’s own allow rules. git paw approvals reports the same patterns with their full counts.

Qualitative signals (v0.6.0)

The four categories above are deterministic — the broker derives them mechanically from message traffic. As of v0.6.0 the supervisor also records qualitative signals: observations that require reasoning over the whole session, which only the supervisor LLM can make during its normal sweep and audit work. They ride the same agent.learning wire format and land in their own sections of session-learnings.md. The supervisor publishes them through the bundled .git-paw/scripts/sweep.sh learn <category> <title> <body-json> helper — a least-privilege, by-path publish path, never a raw curl.

Because these are LLM judgments, the supervisor skill gates each one behind a heuristic and a “do not publish unless…” rule, and suppresses near-duplicates within a session. The aim is a short, high-signal list, not an exhaustive log — if a category is empty in a run, the supervisor simply didn’t see a confident instance.

Recurring failure shapes

The same error shape recurring across multiple feedback cycles from different branches (e.g. three branches all hitting the same import-cycle pattern). What to do: treat it as a systemic signal — a missing lint, an undocumented constraint, or a fixture/scaffold gap — rather than fixing each branch in isolation.

Documentation gaps

A spec audit found a convention the spec assumes but no checked-in doc explains. The record names the convention, the doc paths checked, and a suggested home for it. What to do: add the convention to the suggested doc (git-paw does not write docs for you — see Non-goals below).

ADR / architectural drift

Code introduced an architectural decision — a new dependency, framework, or boundary — not reflected in your configured ADRs. The record names the decision_area, the observed pattern, and a candidate ADR title. What to do: decide whether the drift is intentional (write the ADR) or accidental (revert or rework it).

Scope-mistake signals

Two or more branches coordinated heavily because the original spec scope drew the boundary in the wrong place. The record names the branches, the shared files, and a suggestion. What to do: consider re-cutting the scope for the next change so the same work lands in one branch.

Tooling friction

Friction the supervisor absorbed about git-paw itself — a tool behaviour that made it repeat work or work around the tool (a permission prompt cleared on every sweep, a helper too narrow so it fell back to raw curl, a detector that over-escalated) — as distinct from the four project-scoped categories above. The record names the friction, the occurrences (how many times it was absorbed this session), and a suggestion. The supervisor publishes it only when the same friction was absorbed at least twice in the session, so a one-off is never recorded. What to do: treat it as the prime tool-improvement signal — fold it into a git-paw issue or a config/allowlist change.

Correction-budget exhaustion

Emitted by the --unattended drive loop (not by the supervisor skill) when a branch spends its whole [supervisor.correction] max_cycles budget without converging on a passing gate. The record carries the branch, the worker cli, and the cycles spent, under category correction_exhausted. What to do: read it as a tiered-model tuning signal — a branch that burns its whole budget is usually a task whose worker model is under-powered for that class of work, so re-assign it to a stronger CLI or split the spec. Like every learning it is emitted only when [supervisor] learnings = true.

Unknown categories

Records whose category the aggregator doesn’t recognise (e.g. a category added by a newer supervisor skill) are never dropped — they appear under an Other learnings section so nothing is lost across version skew. The correction_exhausted category above renders there too, as a title plus its JSON body.

Non-goals. Qualitative signals flag issues; they do not fix them. git-paw does not auto-generate docs or ADRs, and it does not scan past sessions for cross-session patterns — each observation belongs to the session that saw it. The detection thresholds live in the supervisor skill prose, not in config (see below); if a category is too noisy or too quiet for your project, edit your local copy of the supervisor skill.

Sample Output

A short illustrative excerpt (agent names, paths, and counts are made up; headings and bullet shapes are the ones the aggregator writes):

## Session Learnings — 2026-05-13T14:30:05Z

### Conflict events
- forward-conflict-cross-spec: feat-api and feat-auth
- in-flight-conflict: feat-api and feat-billing
- ownership-violation: feat-api edited `src/auth/jwt.rs` owned by feat-auth

### Where agents got stuck
- feat-api: blocked 11m12s waiting on feat-auth
- feat-billing: blocked 4m03s waiting on feat-api (unresolved at session end)

### Recovery cycles
- feat-auth: 3 feedback cycles before verifying

### Permission patterns
- `cargo test` escalated for a human decision (first seen; see `git paw approvals` for counts)

### Recurring failure shapes
- import cycle between the auth and session modules: 3 instances across feat-auth, feat-api, feat-billing

### Documentation gaps
- agents run the linter before committing — add a Conventions section to AGENTS.md naming the pre-commit lint step
## Session Learnings — 2026-05-13T16:05:41Z
...

The exact bullet wording may evolve across releases; the category set and the underlying triggers above are stable.

Flush Cadence

The aggregator buffers entries in memory and flushes to disk on an interval (default 60s):

[supervisor.learnings_config]
flush_interval_seconds = 60

A shorter interval makes the file fresher (useful when you want to tail -f the file in another terminal); a longer interval batches more entries per write. The file is also flushed once more at broker shutdown so nothing is lost between sessions even if the interval has not elapsed.

See Configuration → Learnings mode tuning for the field reference.

Programmatic consumption: agent.learning (v0.6.0)

v0.5.0 shipped learnings as file output only. As of v0.6.0 the aggregator also publishes each flushed entry to the broker as an agent.learning message, so tools no longer have to re-parse the Markdown. The file output is unchanged — it remains the source of truth for cold-repo / no-broker scenarios — and the broker publish is purely additive.

Each agent.learning record carries:

The id is a 64-bit FNV-1a hash (16 lowercase hex characters) of the canonical form (category, branch, body sorted, UTC hour bucket). FNV-1a is stable across Rust toolchain versions — each id is deterministic regardless of when or where it is computed. It is a dedup key, not a security primitive. Re-publishing the same logical record within one hour yields the same id, so a consumer can dedupe re-emissions; a genuine recurrence in a later hour gets a fresh id. This lets the aggregator re-run a sweep idempotently without flooding consumers with duplicates.

The bundled sweep.sh learn helper uses the same scheme. The supervisor publishes qualitative learnings through .git-paw/scripts/sweep.sh learn <category> <title> <body-json>, and that helper computes its id with exactly the form above — over the category, an empty branch id (supervisor learnings are cross-cutting), the canonical body, and the current UTC hour bucket. The two publishers therefore assign the same id to the same logical record, and a consumer can dedupe across both. The title is NOT part of the canonical form, so rephrasing it does not mint a new record.

Because the canonical form has to render byte-identically on both sides, the helper accepts only numbers it can reproduce exactly: 64-bit integers. A body carrying a non-integer number (0.5, 1e16) or an integer beyond the 64-bit range is refused with a diagnostic and nothing is published — the two serialisers disagree on those (1e+16 against 1e16), and a record published under an id the aggregator cannot reproduce would silently defeat the dedup. Learning bodies carry counts and labels, so this costs nothing in practice.

Note: record ids changed once in this release (v0.17.0): the aggregator’s hash moved from platform-dependent DefaultHasher to stable FNV-1a, and sweep.sh learn — which had been computing a truncated SHA-1 over a different canonical form, giving the same record two different ids depending on which publisher emitted it — moved onto the shared scheme. Existing ids from v0.16.x are now invalid; re-run your aggregator to regenerate them.

Branch-scoped records (stuck_duration, recovery_cycles) are routed to that branch’s inbox and are retrievable with:

curl -s http://127.0.0.1:9119/messages/<branch-id>

Cross-cutting records (conflict_event, permission_pattern) carry no branch_id and land in the supervisor inbox. Every record is also retained in the broker’s full message log (/log).

The MCP get_learnings() tool reads the Markdown file, not the broker: it returns each ### section as a { category, entries } record, and returns the four deterministic sections with empty entries when no file exists yet.

Publication is controlled by the broker_publish knob (default auto, which follows [broker] enabled); see Configuration → Learnings mode tuning.

Conflict Detection

When supervisor mode is active, the broker runs an in-process conflict detector that watches for three failure shapes across parallel agents. Detected conflicts surface as [conflict-detector]-tagged agent.feedback delivered to the involved agents, and — for unresolved in-flight shapes — as agent.question escalations to the supervisor inbox. The detector is automatic; you only opt out by setting [supervisor] enabled = false (or tuning the knobs in [supervisor.conflict]).

Contents

• The Three Failure Shapes
• The [conflict-detector] Tag
• Supervisor Inbox Routing
• Interaction with the Filesystem Watcher
• Configuration Knobs

The Three Failure Shapes

git-paw’s own managed bookkeeping — everything under a worktree’s .git-paw/ directory (config, bundled scripts, session state) — is excluded from the overlap computation for forward and in-flight conflicts. Every worktree shares this untracked scaffolding, so its presence in modified_files is not evidence of a code conflict: two agents both reporting .git-paw/config.toml never fabricates a warning, while a genuine source overlap alongside it (src/a.rs present in both) still conflicts on the source path.

Forward conflict

Two agents publish agent.intent payloads whose files arrays overlap. The conflict is forward because it surfaces before either agent commits — intent is the early-warning channel.

Trigger. Any non-empty intersection between two active intents (an intent stays active until its valid_for_seconds TTL expires or the agent publishes a fresh intent, which replaces it). Each pair is warned once; the warning can fire again only after one side’s intent changes its file set or expires.

Action. Each agent receives an agent.feedback with the [conflict-detector] tag in its errors[0], naming the peer and listing the overlapping paths. Neither side blocks; the receiving agents decide how to retract or reshape their plans.

Region granularity (v0.6.0). When both intents declare regions for a shared file (function / class / block / range — see Declaring regions), the detector triggers only when the declared regions intersect, and the warning names the intersecting regions. When either side omits regions it falls back to the file-level trigger above, preserving v0.5.0 behaviour. Cross-kind comparisons (a named region vs a line range) intersect conservatively and append a hint.

Toggle. [supervisor.conflict] warn_on_intent_overlap (default true). When false, the detector still records intents (so in-flight classification and ownership detection keep working) but no agent.feedback fires for forward shape.

In-flight conflict

Two agents’ current agent.status modified_files sets overlap on the same file. The conflict is in-flight because both sides are already writing.

Trigger. Any non-empty intersection between one agent’s latest agent.status modified_files and another agent’s latest agent.status modified_files (each new status replaces that agent’s previous set). agent.artifact does not feed this check, and declared intents only decide how an unresolved overlap is classified (below).

Action. Both agents receive [conflict-detector]-tagged agent.feedback. The detector starts a window_seconds timer; if no side retracts before it elapses, the detector classifies the overlap from the two agents’ declared intent regions for the shared file and acts:

• True collision — the declared regions intersect (same named region, same insertion anchor, overlapping line ranges, or a conservative cross-kind match), or either side declared no regions for the file (a file-level intent, or no active intent at all). The detector escalates to the supervisor inbox via agent.question (see Supervisor Inbox Routing).
• Additive overlap — both agents declared regions for the file and the region sets are disjoint (well-separated hunks or differently named regions). The detector downgrades to a single informational [conflict-detector]-tagged agent.feedback delivered to both agents (“shared file, additive — resolve at merge”) and does not escalate to the human. The overlap is still recorded: the triple is marked decided so it neither re-escalates nor re-emits the downgrade on later ticks, and it clears only when one agent stops touching the file — so an additive overlap is never silently dropped.

The downgrade requires both sides to have declared regions; whenever the region data is insufficient to prove the hunks are disjoint, the detector escalates, preserving the conservative default.

Window. [supervisor.conflict] window_seconds (default 120).

Escalations persist across commits. The overlap is as volatile as modified_files: an agent commits, the watcher publishes an empty set, and the overlap vanishes for a tick or two before the file reappears. The decision — that this pair and this file have already been put to a human — is not volatile, and the detector keeps it separately from the live overlap view. So a commit does not re-escalate a conflict that has already been escalated, and it does not rewind the window timer for one that has not: an overlap first seen 100 seconds ago still escalates at the 120-second mark, not 120 seconds after the commit. A decision is discarded only once its conflict is genuinely over — the overlap has been continuously absent for the escalation window (at least 60 seconds) — or when the two agents’ declared regions for the file describe a materially different overlap.

Acknowledging an escalation. Once you have adjudicated an escalation, record it so the detector stops asking:

.git-paw/scripts/sweep.sh conflict-ack <agent-a> <agent-b> <file> "optional note"

This publishes a [conflict-ack]-tagged agent.feedback from supervisor to both agents. A note you pass rides along as a second errors entry so the agents see your reasoning; if you pass none, the helper supplies a default one — agents are taught that errors are problems to fix, and a bare tag line would read as a cryptic error.

While the acknowledgement stands, no further agent.question is emitted for that pair and file — but the detector keeps tracking the overlap rather than dropping it, so a later escalation can still be built on it. Acknowledging suppresses the question, not the fact. (No view currently renders the in-flight tracker, so “keeps tracking” means exactly that: the detector’s own state, not something you can read off the dashboard.)

The acknowledgement is invalidated automatically when the two agents’ region declarations for that file change materially — judged by the same intersection rules that drive the additive-versus-true classification above. A conflict that genuinely changes shape can therefore escalate again: an agent re-declaring agent.intent with a range that now overlaps its peer’s, or widening its claim from a named region to the whole file. An intent merely expiring is not a change — otherwise every settled conflict would re-open one TTL later.

What the supervisor-only rule does and does not do. The detector honours an acknowledgement only when the carrying agent.feedback has from = "supervisor". That filter stops an agent’s ordinary feedback from being mistaken for an adjudication. It is not an authentication boundary: the broker does not authenticate senders, from is self-asserted, and sweep.sh is present in every worktree — so an agent that set out to do so could publish conflict-ack for a conflict it is party to. What limits the damage is visibility, not prevention: an acknowledgement published through the helper reaches both named agents, and every acknowledgement — however it was published — stays in the broker message log. (The detector honours one whatever its envelope agent_id, so a hand-rolled one need not have been delivered to both; the log is what you audit.) Sender authentication is part of the v0.18.0 broker-authority work.

Ownership violation

An agent’s modified_files (from its agent.status) touches a file that another agent has claimed in its active agent.intent. Ownership is intent-based: a file is owned by whichever agent’s non-expired intent declares it.

Trigger. Any path in the agent’s modified_files that lies outside its own active intent (or the agent has no active intent) and inside another agent’s active intent.

Action. The violator receives agent.feedback naming the touched file and the agent whose intent claims it; each violator/file pair is warned once. When [supervisor.conflict] escalate_on_violation = true (default), the supervisor inbox also receives a follow-up agent.question so a human can decide whether to override the boundary or block the work.

Exemption. The shared spec-task-tracking artifact — the tasks file git-paw directs every agent to update with its own checkbox (a Spec Kit specs/<feature>/tasks.md or the OpenSpec tasks.md) — is exempt from ownership-violation detection. git-paw’s own writeback protocol has every agent tick its own line in that single shared file, so a writeback there is expected coordination, not a collision. The exemption only covers that designated task-tracking artifact; ownership violations on source files are still reported.

The [conflict-detector] Tag

Every auto-emitted agent.feedback from the detector carries a single errors entry that starts with a fixed tag:

{
  "type": "agent.feedback",
  "agent_id": "feat-auth",
  "payload": {
    "from": "supervisor",
    "errors": [
      "[conflict-detector] forward conflict: agent feat-api also intends to modify: src/auth/middleware.rs"
    ]
  }
}

The [conflict-detector] prefix distinguishes detector output from human-typed supervisor feedback. Agents (and dashboards) that filter or classify feedback can match on the tag without parsing payload semantics.

One further tag travels the other way. An agent.feedback from supervisor whose errors entry reads [conflict-ack] <agent-a> <agent-b> <file> is read by the detector as an acknowledgement of that conflict (see In-flight conflict); sweep.sh conflict-ack shapes it for you. The file path runs to the end of its errors entry, so the tag line carries nothing after the path — add any prose as a separate entry. The detector never emits [conflict-ack] itself.

The detector publishes from the "supervisor" agent ID (the from field in the payload) — same source as human-authored supervisor feedback — because routing and display logic already specialise on the supervisor identity. The tag, not the source, is the discriminator.

Supervisor Inbox Routing

When an in-flight conflict has not resolved within window_seconds and is classified a true collision (see In-flight conflict), the detector escalates to the supervisor by publishing an agent.question addressed to the supervisor (not to either of the conflicting agents). Additive overlaps are downgraded to an agent.feedback and never land in this inbox. The orchestrator (your own agent session outside the tmux session) sees the question in its broker inbox and can:

1. Type a reply, which the supervisor skill forwards to both involved agents via tmux send-keys (the same dual-write pattern documented in Agent Coordination § Supervisor Acknowledgement).
2. Resolve the conflict directly by editing one agent’s intent or pausing the offending agent until the other side commits.

Ownership-violation escalations follow the same routing. Forward conflicts never escalate — they are advisory.

Interaction with the Filesystem Watcher

The broker’s filesystem watcher polls git status --porcelain in each worktree every ~2 seconds and publishes agent.status (with a fresh modified_files array) whenever the set of reported paths — modified, staged, or untracked — changes. The conflict detector consumes these auto-published status messages, so in-flight conflicts surface as soon as edits land on disk — no manual agent.status curl required from the agent.

The watcher only reads git status — it never stages or commits — so the detector sees overlaps within one poll of a file being modified, even before git add or git commit. This is the mechanism that makes “in-flight” meaningfully earlier than the post-commit hook’s agent.artifact { status: "committed" }.

Configuration Knobs

All knobs live under [supervisor.conflict] in .git-paw/config.toml:

[supervisor.conflict]
window_seconds = 120
warn_on_intent_overlap = true
escalate_on_violation = true

The [supervisor.conflict] table is fully optional. Setting [supervisor] enabled = false (or omitting the section) disables the detector subsystem entirely — no auto-emitted feedback fires regardless of the values above. See Configuration → Conflict detector tuning for the canonical field reference.

MCP Server

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.

It exposes the same information git-paw already tracks as deterministic, read-only tools, beside a bounded write surface (publish tools, and session lifecycle and verdict tools for a root session only — see below). The read-only tools cover:

• Coordination — active agent intents and detected conflicts
• Governance — your configured ADRs, test strategy, security checklist, Definition of Done, and constitution
• Project knowledge — discovered specs and tasks (OpenSpec, Markdown, Spec Kit, Superpowers), the spec dependency graph, and rendered agent skills
• Session state — the active session’s status/summary and the session-learnings file
• Git context — branches, recent commits, and branch diffs
• Source/Files — browse the local working tree, read a file, and search code contents (gitignored paths excluded; reads confined to the repo root)

Alongside those, the server exposes a bounded write surface: the Publish tools for every session, and — for a root session only (a server started in the repository’s main working tree) — the Session lifecycle tools and the two verdict publish tools, plus — only once the repository opts in with [mcp] allow_repo_writes — the Spec authoring write tools. validate_spec is read-only and every session gets it.

The server is standalone: it does not need a tmux session, broker, or supervisor for the read-only categories (the publish tools do need a reachable broker — see below). When a data source is unavailable (no broker, no session, no governance config) read tools return well-formed empty/null results rather than errors — so the client always gets an unambiguous answer.

Read/write boundary. Every tool category except Publish tools, Session lifecycle and the two Spec authoring write tools is read-only, deterministically sourced from files, git, and broker state. The write surface is a fixed set of tools: the four worker publish tools (the same four events the bundled broker.sh helper covers), each publishing only as the calling session; and, for a root session only, the session lifecycle tools (exactly what git paw start / pause / stop / purge do) and the two verdict tools (publish_verified, publish_feedback, exactly what sweep.sh verified / feedback-gate do). The spec-authoring write tools, for a consenting repository’s root session, write only inside one spec change directory. There is no tool that writes a file outside a spec change directory, runs a caller-supplied git or shell command, or writes configuration, and no generic “publish anything” tool. A server in an agent’s worktree never lists or runs the root-only tools, so a coding agent cannot verify its own work through MCP — see Publish tools. The server also never invokes an agent CLI (claude, codex, …) as an inference backend; every result comes from files, git, and broker state.

How it works

The MCP client spawns git paw mcp as a child process and talks to it over the process’s stdin/stdout using newline-delimited JSON-RPC 2.0. The client owns the lifecycle: the server starts when the client launches it and exits cleanly when the client closes its stdin.

git paw mcp [--repo <PATH>] [--log-file <PATH>]

Verbosity follows the standard RUST_LOG convention (default warn):

RUST_LOG=debug git paw mcp --repo /path/to/repo

Repository resolution

1. If --repo <PATH> is given, the server uses that path (it must be inside a git repository).
2. Otherwise the server walks up from the current directory to the nearest enclosing git repository. Inside a git worktree, it resolves to the worktree’s own root.

If no repository can be found, the server prints a clear error to stderr and exits non-zero — it never silently serves nothing.

Finding the session and its broker from inside a worktree. File-serving tools keep the resolution above: inside a worktree, the repository IS that worktree. The session lookup is deliberately wider — a worktree root never equals the repository root, so matching it directly would leave a server started by an agent’s CLI (its working directory is the agent’s worktree, and it is given no --repo) with no session and no broker URL. The server therefore resolves a worktree to the repository that owns it before looking the session up, trying the exact path first and falling back to the owner only on a miss. get_session_status and the broker URL in the server’s context come from that lookup.

This widening is confined to the MCP server’s read-only view. Every git paw command that mutates session state — stop, purge, add, remove, pause, and start’s recover/resume dispatch — keeps the exact match, so running one inside an agent worktree never acts on the parent session.

Server identity

In the MCP initialize handshake the server advertises serverInfo.name = "git-paw" and its real crate version. To distinguish several repositories that each run git paw mcp, set a custom name in the repo’s .git-paw/config.toml:

[mcp]
name = "my-project"   # advertised as serverInfo.name; defaults to "git-paw"

This is the server’s own advertised identity. It is distinct from the display label some clients show, which comes from the mcpServers key in the client config (e.g. "git-paw" in the snippet below) — that key is yours to rename per client entry regardless of [mcp].name.

Per-client setup

Each client needs its own entry pointing at this server. The command is git with args paw mcp … (git-paw installs as a git subcommand). If you prefer, git-paw mcp … works too.

Claude Desktop

Claude Desktop spawns MCP servers from its own application-support directory, not your project — so current-directory discovery cannot work. You must pass --repo with an absolute path.

1. Open the config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add a server entry:

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

3. Restart Claude Desktop completely (quit and reopen).

4. Verify: open a new chat, click the tools/🔌 icon, and confirm git-paw is listed with its tools. Ask “what specs are pending in this repo?” and confirm a tool call runs.

Cursor

Cursor is workspace-aware and spawns from the workspace root, so bare git paw mcp works (or pass --repo to be explicit).

1. Create .cursor/mcp.json in your project (or edit the global ~/.cursor/mcp.json):

   {
     "mcpServers": {
       "git-paw": {
         "command": "git",
         "args": ["paw", "mcp"]
       }
     }
   }
   

2. Reload Cursor (or toggle the server in Settings → MCP).

3. Verify: open Settings → MCP and confirm git-paw shows a green status with its tools listed.

ChatGPT Desktop (macOS)

ChatGPT Desktop supports local MCP servers in Developer Mode. (ChatGPT Web in a browser is not supported — see Known limitations.)

1. Enable Settings → Connectors → Advanced → Developer mode.
2. Add a connector with command git and args paw mcp --repo /absolute/path/to/your/repo (ChatGPT Desktop, like Claude Desktop, does not run from your project directory, so pass --repo).
3. Restart ChatGPT Desktop.
4. Verify: start a new chat, open the connector/tools menu, and confirm git-paw and its tools are available.

Windsurf

1. Open Settings → Cascade → MCP Servers → Add Server (or edit ~/.codeium/windsurf/mcp_config.json):

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

2. Refresh the MCP server list (or restart Windsurf).

3. Verify: the MCP panel shows git-paw connected with its tools.

VS Code (MCP)

VS Code (1.102+) supports MCP servers. It is workspace-aware, so bare git paw mcp works from a workspace folder.

1. Create .vscode/mcp.json in your workspace:

   {
     "servers": {
       "git-paw": {
         "type": "stdio",
         "command": "git",
         "args": ["paw", "mcp"]
       }
     }
   }
   

2. Run MCP: List Servers from the Command Palette and start git-paw (or reload the window).

3. Verify: in Agent mode, open the tools picker and confirm the git-paw tools appear.

Known limitations

• ChatGPT Web is not supported. The browser version of ChatGPT cannot spawn local processes, which stdio MCP requires. ChatGPT Desktop on macOS works (with Developer Mode). The server speaks stdio only — there is no HTTP transport.
• Per-repo configuration is required. Each repository needs its own entry in the client config (with its own --repo path where the client spawns from a fixed directory). For many repos this is repetitive; one server instance serves exactly one repository.
• Claude Desktop (and ChatGPT Desktop) need --repo. They spawn MCP servers from their own app-support directory, not your project, so current-directory discovery cannot find your repo. Workspace-aware clients (Cursor, VS Code MCP, Windsurf) work with a bare git paw mcp.

Tool reference

Every category below is read-only except Publish tools, Session lifecycle and the two write tools of Spec authoring. For the read-only categories, collection results are empty ([]) and single-record results are null when the underlying data is unavailable. Governance tools return a protocol error only when a configured document path exists but cannot be read.

Coordination

wait_for_events is the MCP form of the broker’s long-pollable event log. since is a broker log sequence number (default 0) and timeout_seconds defaults to 30, capped at 60. The tool long-polls GET /log, so it returns as soon as an entry newer than since is appended, or when the timeout elapses — whichever comes first. The wave object reports wave staleness, so a call that times out with no entries still tells the caller whether the wave has stalled.

epoch identifies the broker instance that answered. Sequence numbers restart at zero whenever a broker does — a pause + start cycle, for instance — so a cursor is only meaningful against the epoch it came from. Record the epoch with your cursor and pass since: 0 on the next call whenever it changes, or you will hold a cursor above everything the new broker appends and time out on every call. See The broker epoch.

With no reachable session broker it returns at once with empty entries, last_seq equal to the since it was given, and no_session: true. It mutates nothing: like every tool outside Publish tools, it only reads broker state.

Governance

Project knowledge

source is one of standard (.agents/skills/), user_override, or embedded. An unknown skill returns skill: null with a message — not an error. The orchestrator skill is served under the name orchestrator (supervisor is an alias returning the same content) — the same procedure git paw init exports to .git-paw/skills/orchestrator/SKILL.md.

Session state

get_session_status includes the broker’s wave object — the session’s wave-staleness reading (last_progress_unix_secs, idle_seconds, stall_threshold_seconds, stalled) — whenever a broker is reachable, and omits the field entirely otherwise.

Git context

Source/Files

Browse and read the repository’s local working tree — tracked files plus untracked-but-not-ignored files. Gitignored paths (build artifacts, secrets) are excluded throughout, and read_file is confined to the repository root (canonicalise + starts_with guard, the same as get_doc): a path escaping the root (../, an absolute path, a symlink target outside the root) is refused, and a gitignored path is refused, both with null content and a message rather than a read. Reads return the on-disk working-tree content, so uncommitted/branch state shows. Implemented over git ls-files / git grep, so a non-git directory or a no-match search degrades to an empty result.

Documentation

Read-only access to the repository’s own documentation, driven by the bring-your-own [governance].readme and [governance].docs config paths (see below). Locations are configured, never hardcoded — unset paths degrade to null/empty results.

The documentation tools read two optional [governance] paths in .git-paw/config.toml:

[governance]
readme = "README.md"   # path to the repository README
docs   = "docs/src"     # path to the documentation root directory

Both default to unset, in which case get_readme returns null, list_docs returns an empty list, and get_doc returns null — identical to the pre-v0.7.0 surface. list_docs walks the docs directory recursively for *.md files; the relative paths it returns feed directly back into get_doc.

Publish tools

Four worker tools, one per agent boot event, each publishing the same message the bundled broker.sh helper does — this is the MCP tool form of the boot block for a CLI that speaks MCP — plus two verdict tools for a root session only, each publishing the same message sweep.sh verified / feedback-gate does.

There is no inbox or poll tool: an agent reads its broker inbox with .git-paw/scripts/broker.sh poll, whichever form its boot block uses.

Three properties are structural, not incidental:

• Bounded, not generic. These are distinct tool definitions, not one publish(type, payload) tool. A message type is never an accepted parameter, so the set of things a client can publish cannot grow by passing a new string — it can only grow by this server shipping a new tool.
• Session-scoped identity. No publish tool accepts an agent_id or publisher parameter. In an agent’s worktree, each derives the publishing id from the worktree’s branch (the same conversion the broker.sh poll/status path uses), so a session can only ever publish as itself. In the repository’s main working tree — the orchestrator’s — every publish tool publishes as the root identity supervisor, never as an agent named after the default branch. The verdict tools take the target agent as agent, as the helpers do, and set the verifier / sender to supervisor themselves.
• Verdicts belong to the root session only. agent.verified is what authorises a branch to be merged; agent.feedback from the supervisor is its corrective channel. The broker accepts either only with the session’s authority credential, which lives outside the repository. publish_verified and publish_feedback are registered only for a server started in the main working tree, which attaches the credential itself (it is never a tool parameter and never appears in a result or an error). A server in an agent’s worktree does not list them, and a by-name call returns an MCP-level error naming the restriction, so a coding agent cannot self-verify through MCP.