Skip to content

About

Deterministic PR creation and merging for agents via Code Mode-style Plugin

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

725 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pr-shepherd

Take pull requests from scratch to merge-ready with a coding agent as a Code Mode-style plugin. It works with Claude Code, Codex, Grok, and any stdio MCP client.

Benefits

  • Better decisions: across 56 PR states, the agent scores 0.97 with the plugin vs. 0.47 with gh + the GitHub MCP server (outcome evals, 2026-11-15).
  • Lower cost: modeled cost per PR session is about 36% lower than gh and 76% lower than the GitHub MCP server, with 20% / 69% fewer turns (token bench; assumes a warm prompt cache).
  • More PRs on one GitHub quota: 65% fewer GraphQL points than gh per PR session. While CI runs, one 5,000-point hourly budget covers about 80 waiting PRs, vs. about 13 with gh pr checks --watch (GitHub API, GraphQL usage). A GitHub App and webhook events cut it further.
  • 72 GitHub edge cases handled: for example, outdated or resolved threads are still shown once, comments edited after the agent read them come back, and conflicts that GraphQL reports as CLEAN are caught (handled cases).
  • Tidy PRs: bot and outdated comments are triaged and resolved, human reviews get replies, and known bot noise is minimized.
  • Review hygiene: Shepherd never answers its own replies, skips a denied reply once instead of retrying, hands a repeatedly rejected fix to a human, and never minimizes human comments (comments and reviews).
  • Less context: resolved comments and configured bot noise are filtered out before they reach the agent.
  • CI failures, pre-read: each failing check comes with its failed step, summary, and a log excerpt, so the agent can usually skip fetching logs. Superseded runs, required checks that never started, and approval gates are recognized (failing checks, CI cases).
  • Cheaper CI: names the in-progress runs a fix push would cancel anyway, so the agent cancels them early.
  • Why a PR can't merge: reads branch protection and rulesets and prints the actual requirements, such as Approvals: None [Required] (merge requirements). Merges are pinned to the head the agent checked, review nits wait so a push doesn't eject a queued PR, and a PR a maintainer pulled from the queue is not requeued (merge and queue).
  • Full flow: from scratch to draft, mergeable, and through the merge queue, including stacked PRs.
  • Review suggestions: applies suggested changes as commits that credit the reviewer.
  • Safe by construction: the CLI never mutates git or merges by itself, and human handoff is limited to a short escalation list.

Use cases

  • Autonomous agents. An agent opens a PR and drives it to merge-ready, or merged when you allow it. Nobody has to watch CI and reviews.
  • Exhaustive AI code review. Some PRs get many bot reviews (CodeRabbit, Codex, Copilot, and others). Shepherd shows every thread and comment once and tracks first-look, edited, and outdated items. It pre-filters comments, batches the replies, resolves, and minimizes.
  • High-velocity teams. Supports stacked PRs, merge queues, and merge queue ejections, and directs agents to rebase or stack as needed, so work keeps moving even with many conflicts.

How to use

Install the plugin, then ask your agent:

  • "make PRs, /pr-shepherd:pr-shepherd" makes one PR per change that can be reviewed alone, stacks a PR on an earlier one when it needs that PR's code or edits the same lines, and shepherds every PR until it is mergeable.
  • /pr-shepherd <PR> takes a PR, including a draft, to mergeable. It does not merge. Leave out the PR to use the current branch.
  • /pr-shepherd <PR1> <PR2> shepherds several PRs and returns when any has an actionable step.
  • /pr-shepherd --merge <PR> takes the PR to mergeable and merges it.
  • /pr-shepherd stack <stack#> --merge shepherds a native stack and merges it all at once when it is ready. Use --merge-through <PR> instead to merge up to that layer, or --merge-ready to merge the bottom layers as they become ready. Listing PR numbers instead of the stack number owns only those layers.

In Codex, use $pr-shepherd. In a shell or CI, run pr-shepherd <PR>. /goal is generally not needed.

Then configure .pr-shepherdrc.yml (configuration):

  • turn on the bundled classification rules to hide known bot comments;
  • add your own classification rules;
  • list code-review workflows in checks.never-cancel so they always finish.
version: 1
classify:
  standard:
    all: true
checks:
  never-cancel:
    - "*review*"

Optionally, write your policy ("reply instead of fixing nits", "never merge") into a skill that wraps the shipped one (skills).

What it does

Shepherd gathers the full PR context (reviews, CI failures, merge requirements) in one call and returns one action with numbered instructions and exact commands. The agent spends fewer reasoning tokens, tool calls, and turns, and rarely has to investigate on its own.

$ pr-shepherd 123

# PR #123 [TRIAGE]

## Review threads

### `threadId=PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice · MEMBER)

> The variable name is misleading.

## Instructions

1. Fix each warranted item.
2. Commit and push any changes to the PR head.
3. `$CHANGE_MESSAGE`: one sentence on what changed. Run even if no code changed: `pr-shepherd apply review 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$CHANGE_MESSAGE" --require-sha HEAD`
4. Rerun Shepherd now.

More features are in docs/features.md.

Install

The plugin ships the skills, which drive the CLI, so install both.

# Claude Code
claude /plugin marketplace add jonathanong/pr-shepherd
claude /plugin install pr-shepherd

# Codex (then enable the pr-shepherd plugin)
codex plugin marketplace add jonathanong/pr-shepherd

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

# CLI, for shells and CI
pnpm i -g pr-shepherd

Use one package manager for global installs, because a second global copy shadows the first (which -a pr-shepherd lists every copy).

The plugin is the CLI plus skills; it does not start the MCP server. For why, and to register the server yourself, see docs/mcp.md.

Requirements:

  • Node.js >= 22.19.0, Bun, or Deno
  • git
  • A GitHub token or an authenticated gh CLI with the required access

Documentation

docs/README.md indexes every doc. Start with:

Harness ecosystem

  • hook-harness: GitHub webhook relay that agents poll for events instead of polling GitHub
  • agent-blackboard: session-scoped telemetry for autonomous agents
  • no-mistakes: deterministic AST-based codebase intelligence, test selection, and linting for agents

About

Deterministic PR creation and merging for agents via Code Mode-style Plugin

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages