pr-shepherd

for agents finishing pull requests

Deterministic Draft → Merged PRs for agents

An agent finishing a PR should think about code, not reconstruct GitHub state or invent a next-step policy each tick.

Without Shepherd it fans out across GitHub MCP, gh, and GraphQL, then guesses what to do with the result. Shepherd does two jobs instead: gather all context for a PR in one invocation, then emit exactly one deterministic action for the calling agent to run.

$ pr-shepherd 123 --merge

# PR #123 [FIX_CODE]

status  UNRESOLVED_COMMENTS · merge  CLEAN · state  OPEN
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]

## Instructions

1. Review each item under Review threads and Failing checks and decide
   whether it needs a code change.
2. Apply every warranted fix, then push to the PR head branch.
3. Run the generated review-mutation command, then iterate again.

The agent still decides whether a comment or a CI failure needs a code change — Shepherd does not classify signal vs. noise, and it never mutates git itself. It only tells you what happened and what to run next.

Six actions, nothing else

Every iterate tick — CLI, MCP, or the programmatic API — collapses to exactly one of these. There is no seventh action and no "it depends."

FIX_CODE is the only action that means a code change is needed. MERGE also hands work back — it emits a head-pinned merge or enqueue command for the agent to run, rather than merging itself — so iteration continues after both. Only ESCALATE hands the PR to a human; CANCEL just stops polling — merged, closed, or a clean PR that settled through its ready-delay.

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/enable pr-shepherd from Codex — adding the marketplace alone doesn't install the plugin.

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

Where to go next

  • Principles — the beliefs behind the design: why full context beats streaming, and why deterministic orchestration and agentic judgment are a split, not a hierarchy.
  • Full documentation — the exhaustive, agent-facing spec every page on this site links out to for the details.
  • GitHub — source, issues, and releases.