PR Shepherd

Auto-fix CI failures with AI coding agents.

Watches your PR's CI checks. When they fail, it grabs the logs, hands them to your coding agent, and lets it fix, commit, and push. Loops until green or you hit the attempt limit.

Works with Claude Code, Aider, Codex, or any custom agent.

                    ┌─────────────┐
                    │  Push PR    │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
              ┌────►│ Poll Checks │
              │     └──────┬──────┘
              │            │
              │     ┌──────▼──────┐
              │     │  Classify   │
              │     └──┬───┬───┬──┘
              │        │   │   │
              │   Pass │   │   │ Pending
              │   ─────┘   │   └──────┐
              │            │ Fail     │
              │     ┌──────▼──────┐   │
              │     │ Gather Logs │   │
              │     └──────┬──────┘   │
              │            │          │
              │     ┌──────▼──────┐   │
              │     │  AI Agent   │   │
              │     │ Fix + Push  │   │
              │     └──────┬──────┘   │
              │            │          │
              └────────────┴──────────┘
                           │
                    ┌──────▼──────┐
                    │   Green!    │
                    └─────────────┘

Install

curl -fsSL https://raw.githubusercontent.com/SilasReinagel/pr-shepherd/main/pr-shepherd.sh \
  -o /usr/local/bin/pr-shepherd && chmod +x /usr/local/bin/pr-shepherd

Quick Start

cd your-repo
git push -u origin my-branch
gh pr create --fill

# Start the shepherd — walk away
pr-shepherd

That's it. It auto-detects the repo and PR from your current branch.

Supported Agents

Agent	Flag	Requires	Notes
Claude Code	-a claude (default)	claude CLI	Uses --dangerously-skip-permissions for non-interactive mode
Aider	-a aider	aider CLI	Uses --yes-always for non-interactive mode
Codex	-a codex	codex CLI	Uses --approval-mode full-auto
Custom	--agent-cmd "cmd {prompt_file}"	Your tool	{prompt_file} is replaced with a temp file containing the fix prompt

Examples

# Claude Code (default)
pr-shepherd

# Aider with GPT-4o
pr-shepherd -a aider -m gpt-4o

# Codex
pr-shepherd -a codex -m o3

# Custom agent
pr-shepherd --agent-cmd "my-tool fix --from-file {prompt_file}"

All Options

Flag	Default	Description
-r, --repo	auto-detect	GitHub repo (OWNER/REPO)
-p, --pr	auto-detect	PR number
-a, --agent	claude	Agent preset: claude, aider, codex
--agent-cmd	—	Custom agent command (use {prompt_file} placeholder)
-m, --model	opus	Model to pass to the agent
-b, --budget	5.00	Max USD budget per fix attempt (Claude Code only)
-n, --max-attempts	10	Max fix attempts before giving up
-i, --interval	30	Poll interval in seconds (while checks are pending)
-w, --post-push-wait	90	Seconds to wait after a push before re-polling
-l, --max-log-chars	12000	Max chars of failure log per check run
--dry-run	off	Show what would happen without running the agent
-v, --verbose	off	Verbose output

How It Works

1. Poll — Fetches check status via gh pr checks
2. Classify — Buckets each check into pass / fail / pending / skipped
3. Decide
   • All pass: exit success
   • Any fail: gather logs, launch agent
   • Only pending: wait and re-poll
4. Fix — Writes a detailed prompt with failure logs, hands it to your agent. The agent analyzes the logs, fixes the code, lints, commits, and pushes.
5. Loop — Waits for new checks to run, then re-polls from step 1.

The Fix Prompt

The prompt sent to your agent includes:

• PR number, repo, branch name
• Full failure logs from each failing check run (truncated to --max-log-chars)
• Instructions to make minimal fixes, lint, commit with fix(ci): format, and push
• Rules: no new branches, no unrelated changes, no skipping tests

Requirements

• gh — GitHub CLI, authenticated
• jq — JSON processor
• A coding agent CLI — claude, aider, codex, or your own
• Run from inside a git repo with a PR open on the current branch

Safety

• Each agent run is budget-capped (default $5 for Claude Code)
• Max 10 fix attempts by default to prevent infinite loops
• --dry-run lets you see exactly what would happen before committing
• The prompt explicitly forbids creating new branches, making unrelated changes, or modifying CI config (unless that's the actual problem)

License

MIT