pr-shepherd weekly downloads statistics

pr-shepherd

Drive a pull request to merge-ready with a coding agent. It works with Claude Code, Codex, Grok, and any stdio MCP client.

Estimated per PR session: −42% cost and −19% turns vs. gh, −77% cost vs. the GitHub MCP server. While waiting on CI: ~60 GraphQL points an hour vs. ~360 for gh pr checks --watch.

What it does

• Gathers the PR's review items, CI failures, and merge requirements in one call. • Returns one action with numbered instructions and exact commands. CANCEL ends the loop and carries none. • Never mutates git. The agent edits, commits, pushes, and decides what each comment deserves.

More features are in docs/features.md.

Outcomes

| Outcome | Headline | Evidence |

| Context and correctness | 60 GitHub edge cases cataloged, backed by 147 scenario fixtures; on 8 of them, evals show the agent does worse without the plugin | Handled cases | | Fewer tokens, lower cost | Cost −42% vs. gh and −77% vs. MCP per PR session; turns −19% / −70% (estimates) | Token bench | | Clearer agent direction | GitHub gotchas (cancelled runs, merge queues, stacks): eval score 0.82 → 0.94, about two-thirds fewer misses | Behavior evals | | Lower GitHub API quota use | ~60 GraphQL points per CI-wait hour vs. ~360 for gh; ~4 when idle. REST core per PR session 4.8 vs. 9 (gh), 78.3 (MCP) | GitHub API, GraphQL usage | | Safe by construction | 0 git mutations; human handoff limited to 10 escalation triggers for a single PR | Escalations | | Works across agents and stacks | 3 agent plugins plus any stdio MCP client; GraphQL and REST transports; native stacked PRs | MCP, cloud |

jongleberry.com/pr-shepherd covers the why and the design principles.

Outcome details

Context and correctness

One iterate call returns everything the agent needs about the PR:

• review threads with replies, PR comments, and review summaries; • each CI failure, with its failed step and a log excerpt when triage can fetch them; • mergeability and the actual merge requirements; • first-look, outdated, and edited items, and stack topology.

One exception: a COMMENTED review that was already minimized before the first tick is not fetched.

The agent reasons less and misses less. docs/handled-cases.md catalogs the GitHub edge cases this covers. These are the gotchas where the behavior evals measured the agent going wrong without the plugin (score with vs. without):

| GitHub gotcha | With | Without |

| On a stack layer, the latest run of a required check was cancelled while an older run passed. GitHub still blocks the merge (#567, gh-stack#466) | 1.00 | 0.44 | | A bot CHANGES_REQUESTED review and a human thread arrive together | 0.89 | 0.33 | | A cancelled run needs a rerun, not a code fix | 1.00 | 0.50 | | Every stack layer is merged, so the loop must stop | 1.00 | 0.50 | | GitHub denied a reply: skip it once instead of retrying | 0.72 | 0.33 | | A maintainer removed the PR from the merge queue | 1.00 | 0.67 | | A required run was cancelled in the merge queue: escalate, don't requeue | 0.75 | 0.42 | | The REST transport cannot run the queue recovery | 1.00 | 0.83 |

Fewer tokens and lower cost

Batching, noise filtering, fingerprint skips, seen markers, and lean output cut tokens and agent turns. Estimated cost per session from the token bench (report):

| Session | Cost vs. gh | Cost vs. GitHub MCP |

| Single PR | −42% | −77% | | PR stack | −45% | −63% |

These are offline estimates at 3.5 characters per token over recorded sessions, not measured billing. Two cases do not save money:

• A single fresh read-and-reply tick is roughly even with gh. • Confirming an already-merged PR costs about 5% more (report).

Clearer agent direction

For a single PR, each tick returns exactly one action: WAIT, READY, MARK_READY, FIX_CODE, MERGE, CANCEL, or ESCALATE. A --stack poll can also return SHEPHERD, which starts one-PR sessions for owned layers. Every action except CANCEL comes with numbered ## Instructions and exact commands, so the agent does not invent policy. In the behavior evals, Sonnet 5.5 at low effort scores 0.94 with the plugin and 0.82 without it on the 36 GitHub-gotcha cases, so it misses about two-thirds fewer graded checks (0.18 → 0.06). On the eight gotchas listed under Context and correctness it goes from 0.50 to 0.92. Weighted toward those gotchas, the mean Δ over all 52 cases is +0.14, and no case has a regression whose interval excludes 0. See docs/actions.md for the output contract.

Lower GitHub API quota use

GitHub meters two tiers (details):

• Primary hourly budgets: GraphQL points and REST core requests. • Secondary limits: per-minute points, where each GraphQL query or REST GET costs 1 and each mutation costs 5, plus concurrency and content-creation limits.

Waiting is where most quota goes, and where Shepherd saves the most. By default gh pr checks --watch refreshes every 10 seconds, at 1 GraphQL point per refresh. That is about 360 points an hour for each watched PR, so a few agents waiting on CI can drain the shared 5,000-point hourly budget. Shepherd polls every 60 seconds by default:

• A typical tick is one batched GraphQL query (1 point). Large or paginated PRs add supplement queries. When nothing changed, the fingerprint skip returns the stored report from that same query. • While CI runs, that is about 60 points an hour for a typical PR, against about 360 for gh pr checks --watch at its default interval. The token bench models gh refreshing every 60 seconds, which ties Shepherd at 60 (report). • When no check is running, conditional REST change detectors run first. A 304 consumes no primary quota. An hour of unchanged idle waiting costs about 4 GraphQL points instead of 60 (graphql-usage.md). That holds only when the stored report is eligible for the detectors. Native-stack layers, READY reports, incomplete snapshots, and detector failures still run the batched query each tick (graphql.md).…

Description from the npm listing.