Stagecoach documentation¶
Stagecoach writes your commit messages using the AI agent you already have installed. It auto-detects pi, Claude Code, opencode, Codex, Cursor, or agy, snapshots your staged changes atomically via git plumbing, and commits only what was staged when it started — so you can keep staging while it thinks.
See the README for the quick start, feature overview, and FAQ.
Note
The docs/ directory tracks the shipped binary. If anything here disagrees with stagecoach --help, the binary is authoritative — open an issue.
Install¶
# Homebrew (macOS / Linuxbrew)
brew install dabstractor/stagecoach/stagecoach
# Go install (anywhere with Go)
go install github.com/dabstractor/stagecoach/cmd/stagecoach@latest
# Direct binary (curl|sh one-liner from GitHub Releases)
curl -fsSL https://github.com/dabstractor/stagecoach/raw/main/install.sh | bash
# Windows (Scoop)
scoop bucket add stagecoach https://github.com/dabstractor/stagecoach-bucket
scoop install stagecoach/stagecoach
# Debian/Ubuntu (apt repo)
curl -fsSL https://github.com/dabstractor/stagecoach/raw/main/apt-archive-keyring.asc | sudo gpg --dearmor -o /etc/apt/keyrings/stagecoach.gpg
echo "deb [signed-by=/etc/apt/keyrings/stagecoach.gpg] https://dabstractor.github.io/stagecoach/apt stable main" | sudo tee /etc/apt/sources.list.d/stagecoach.list >/dev/null
sudo apt update && sudo apt install stagecoach
# Fedora/RHEL (dnf repo)
sudo curl -fsSL https://dabstractor.github.io/stagecoach/rpm/stagecoach.repo -o /etc/yum.repos.d/stagecoach.repo
sudo dnf install stagecoach
Documentation index¶
| Page | Description |
|---|---|
| CLI reference | Synopsis, all global flags (incl. decompose + per-role), subcommands, exit codes, examples, and the flag↔env↔git-config map. v2.1 additions: hook (install/uninstall/status/exec), integrate (git-alias/lazygit + no-mangle protocol), models, and the global flags --exclude, --format, --locale, --context, --template, --edit, --push. |
| Configuration | 7-layer precedence, config file format, environment variables, git-config keys, built-in defaults, and paths. v2.1 additions: exclusion globs + .stagecoachignore, [generation] shaping keys (format/locale/template), STAGECOACH_PUSH, and config init --interactive (guided setup). |
| Provider manifests | 22-field manifest schema, command rendering, the 6 built-in providers (incl. agy), and adding a new agent. |
| How Stagecoach works | Snapshot-based architecture, multi-commit decomposition pipeline, stage-while-generating, the safety and rescue protocol, binary filtering, and prompt engineering. v2.1 additions: payload exclusions, format modes & locale, the hook-vs-snapshot trade-off, and stage-while-editing (--edit). Lock reclamation (–K7): the parent-death watchdog, SIGHUP, lock status, and the no_parent_watchdog opt-out. |
Capability index¶
Each v2.1 capability maps to a specific doc anchor:
- Payload exclusions → configuration.md#exclusion-globs-generationexclude · how-it-works.md#payload-exclusions-stagecoachignore
- Message shaping → how-it-works.md#format-modes-and-locale
- Git hook mode → how-it-works.md#trade-off-inversion-fr-h7 · cli.md#hook-install
- Tool integrations → cli.md#integrate-install-target
--edit/--push→ cli.md (global flags)- Discovery → cli.md#models-provider · cli.md#config-init
- Concurrency & lock reclamation → how-it-works.md#per-repo-run-lock-fr52 · cli.md#lock-status · configuration.md#environment-variables (
no_parent_watchdog) - Chrome-disable (v2.9) → providers.md#tools-disable-asymmetry — every provider renders chrome-less where the agent CLI allows it.
Contributing¶
See the README for build instructions. For the manifest format, see providers/*.toml in the repo root — providers/pi.toml is the cleanest template.