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.
```text
$ 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."
- WAIT
- MARK_READY
- FIX_CODE
- MERGE
- CANCEL
- ESCALATE
`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**
```bash
claude /plugin marketplace add jonathanong/pr-shepherd
claude /plugin install pr-shepherd
```
**Codex**
```bash
codex plugin marketplace add jonathanong/pr-shepherd
```
Then install/enable `pr-shepherd` from Codex — adding the marketplace alone doesn't
install the plugin.
**Grok**
```bash
grok plugin marketplace add jonathanong/pr-shepherd
grok plugin install pr-shepherd --trust
```
**MCP only**
```bash
npx --yes --package pr-shepherd@latest pr-shepherd-mcp
```
## Where to go next
- [**Principles**](/pr-shepherd/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**](https://github.com/jonathanong/pr-shepherd/blob/main/docs/README.md) — the exhaustive, agent-facing spec every page
on this site links out to for the details.
- [**GitHub**](https://github.com/jonathanong/pr-shepherd) — source, issues, and releases.
## Canonical spec
- [Full documentation index](https://github.com/jonathanong/pr-shepherd/blob/main/docs/README.md)