pr-shepherd

for agents finishing pull requests

Get your agent's PRs to merge-ready

Your coding agent fixes the code. Shepherd tells it what GitHub wants next: every review comment, every failing check, and the merge requirements GitHub reports, in one call.

About 42% cheaper per PR than gh and 77% cheaper than the GitHub MCP server. Waiting on CI costs about 60 GraphQL points an hour instead of 360.

$ pr-shepherd 123

# PR #123 [TRIAGE]

status UNRESOLVED_COMMENTS · repo owner/repo
summary 3 passing

## Review threads

### src/commands/iterate/index.mts:42 (@alice · MEMBER)

> The variable name is misleading.

## Failing checks

- CI › lint / typecheck / test (22.x) [conclusion: FAILURE]
  > oxfmt

## Instructions

1. Fix each warranted item.
2. Triage ## Failing checks. Playbook: "CI failure triage".
3. Commit and push any changes.
4. Journal key decisions or rejections with URLs or IDs: pr-shepherd apply journal 123 '- <decision>'
5. $DISMISS_MESSAGE: one sentence on what changed. Run even if no code changed: pr-shepherd apply review 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha HEAD
6. Rerun Shepherd now.

What you get

  • It sees the whole PR One call returns review threads, comments, CI failures with log excerpts when available, and the real merge requirements. It handles 60 GitHub edge cases, like a cancelled run that needs a rerun rather than a code fix.
  • It costs less to run An estimated 42% lower cost per PR session than gh, and 77% lower than the GitHub MCP server.
  • Your agent knows what to do next Every tick ends in one action, and every action but CANCEL comes with numbered steps. On tricky GitHub cases, eval scores rise from 0.82 to 0.94, about two-thirds fewer misses.
  • It's easy on your rate limit Waiting on CI costs about 60 GraphQL points an hour, against about 360 for gh pr checks --watch. Unchanged idle waits can cost as little as 4.
  • It never touches your git Shepherd runs zero git mutations and never merges on its own. For a single PR, it hands off to a human only for 10 specific reasons.
  • It works with your agent Plugins for Claude Code, Codex, and Grok, a local stdio MCP server for other clients, and a CLI for shells and CI. Native stacked PRs are supported.

How it works

Your agent asks Shepherd about a PR. Shepherd reads GitHub and answers with exactly one action:

A stack poll can also return SHEPHERD, which starts a session for each stack layer you own.

The agent follows the printed steps, pushes, and asks again. READY means a clean PR is settling; the loop ends at CANCEL, or at ESCALATE when a human is needed. The agent still decides what each comment deserves.

Install

Claude Code

claude /plugin marketplace add jonathanong/pr-shepherd
claude /plugin install pr-shepherd

Codex

codex plugin marketplace add jonathanong/pr-shepherd

Then install and enable the pr-shepherd plugin in Codex.

Grok

grok plugin marketplace add jonathanong/pr-shepherd
grok plugin install pr-shepherd --trust

MCP only

npx --yes --package pr-shepherd@latest pr-shepherd-mcp

CLI, for shells and CI

npm install -g pr-shepherd

Then ask your agent to shepherd a PR, for example /goal /pr-shepherd:pr-shepherd 42 in Claude Code.

Where to go next

  • README The outcomes in detail, with the evidence behind each number.
  • Principles The beliefs behind the design.
  • GitHub Source, issues, and releases.