Wingman
A second pair of eyes from a model that didn't write your code. On every
push, a different AI (codex, gemini, or claude) reviews your diff and hands you a
findings table to act on — nothing blocks the push. Fixes you accept get written
back into your project's rules and linter config, so the same issue never comes
back.
Cross-model review + a learning loop + convergence tracking, in one pre-push hook.
Why cross-model?
The model that writes your code has blind spots — it follows its own patterns and won't catch its own mistakes. A different model reviews from first principles, catching things the first model would never flag on itself.
For example: if Claude Opus writes your code, use Codex (GPT) as the reviewer. If Gemini writes your code, use Claude as the reviewer. The point is the reviewer is a different model than the writer — that's where the value comes from.
Wingman ships with Codex as the default reviewer. /review-setup will install it for you if it's not already present.
Install
As a Claude Code plugin (recommended):
/plugin marketplace add ashbrener/wingman
/plugin install wingman
/wingman:review-setup
As skills for any agent (45+ supported):
npx skills add ashbrener/wingman
/review-setup
Either way you get three review capabilities:
| Skill | Plugin command | Skills-CLI command | Purpose |
|---|
review-setup | /wingman:review-setup | /review-setup | Install git hook, .reviews/ dir, and patterns rule file |
review-loop | /wingman:review-loop | /review-loop | Review → categorize → fix → encode learned patterns |
review-retro | /wingman:review-retro | /review-retro | Weekly retrospective — trends, pruning, automation recs |
Quick start
# 1. Install skills (supports 45+ AI coding agents)
npx skills add ashbrener/wingman # all agents
npx skills add ashbrener/wingman -a <agent> # specific agent only
# 2. Run setup — installs git hook, .reviews/, rules file
# Checks for reviewer CLI and installs if missing
/review-setup
# 3. Work on your feature branch, commit, push
# Cross-model review runs in background after push — you keep working
# The agent auto-surfaces the findings table in chat ~60-120s later;
# no need to invoke /review-loop manually.
# 4. If the agent misses the auto-surface (or you want to re-open findings):
/review-loop
# 5. Weekly, run a retrospective
/review-retro
/review-setup is idempotent — safe to run multiple times. It detects your hooks directory (.git-hooks/, .githooks/, .husky/, or .git/hooks/) and appends to existing pre-push hooks rather than overwriting.
Upgrades
Wingman has two things that version independently:
- The plugin / skills (Claude Code) — updated via
/plugin update wingman when the plugin version is bumped. Community-marketplace installs pick this up automatically: the catalog re-pins on each release and syncs nightly.
- The
pre-push hook (installed in each repo) — updated by re-running setup. Updating the plugin does not touch an already-installed hook — re-run /wingman:review-setup in the repo to upgrade it. (The review-loop skill also warns you when your hook is behind.)
The Wingman block in your pre-push hook carries a # wingman-hook-version: N stamp (currently 4). Re-running the installer — /wingman:review-setup, bash scripts/install.sh, or npx skills add ashbrener/wingman — compares the installed version against the version shipped in the pack:
- older installed → strips the old block and appends the new one (in-place upgrade)
- same version → skips, leaves the hook untouched
--force / --reinstall → unconditionally replaces the block (use this when you want to force a re-stamp without bumping the version, e.g. recovering from a hand-edited hook)
This means bug fixes to the hook propagate the next time you re-run setup. Any older install — no stamp (treated as v1), v2, or v3 — is upgraded to v4 in place, leaving exactly one Wingman block and preserving your .reviews/ data.
What's new in v4
Pluggable reviewer — WINGMAN_REVIEWER selects who reviews: codex (default), gemini, or claude. The codex path is unchanged; gemini/claude get a constructed diff plus a uniform [P1/P2/P3] prompt so the rest of the loop is reviewer-neutral. A missing or unknown reviewer writes a reviewer_missing record instead of blocking the push, and choosing claude in a Claude-authored repo adds a non-blocking cross-model note. See the WINGMAN_REVIEWER row under Configuration.
What's new in v3
Four upgrades, all driven by lessons from a 12-round wingman convergence on project-arc spec 004 — see docs/wingman-v3-features.md for the full write-up.
