Shepherd

A CLI tool for managing graphs of dependent pull requests.

Shepherd analyzes open PRs in a GitHub repository, identifies dependency chains between them, groups related PRs into sets, and orchestrates merging them in the correct order. It's designed for workflows where large changes span multiple PRs that must be merged sequentially — a common pattern with AI-generated code.

Installation

npm install -g @sentry/shepherd

Or run directly with npx:

npx @sentry/shepherd status

Requires Node.js >= 20 and the GitHub CLI (gh) authenticated.

Commands

shepherd status

Show all open PRs grouped by dependency relationships. Displays build status, review state, and merge order for each PR set.

shepherd deps --pr N --add REF

Add a dependency to PR #N. REF can be #123 (same repo) or owner/repo#123 (cross-repo).

shepherd deps --pr N --remove REF

Remove a dependency from PR #N.

shepherd guide <setId> [--auto] [--dry-run] [--non-interactive]

Run the convergence loop for a PR set. Shepherd will:

1. Identify the merge frontier — PRs whose dependencies are all merged
2. Evaluate readiness — check CI status, merge conflicts, and review threads
3. Merge ready PRs in topological order
4. Rebase dependent PRs onto the updated base branch
5. Delegate fixups to an AI agent for CI failures, conflicts, or unresolved feedback
6. Repeat until all PRs are merged or progress stalls

Use --auto to skip interactive merge prompts. Use --dry-run to simulate without making changes. Use --non-interactive to output context and stop instead of prompting (useful for AI agent skills).

shepherd "<prompt>"

Natural language queries routed through an AI agent for PR graph analysis.

How it works

Dependency detection

Shepherd detects PR dependencies in two ways:

• Explicit annotations: Depends on #1, #2 lines in PR bodies
• Branch-based: When PR A's base branch is PR B's head branch

PR sets

Related PRs are grouped into sets using a union-find data structure. Any PRs connected through dependencies (directly or transitively) form a single set. Each set gets a topological merge order computed via Kahn's algorithm, with cycle detection.

Guide loop

The guide command runs a convergence loop that progressively merges a PR set:

• Frontier: PRs with all dependencies already merged
• Readiness: Each frontier PR is classified as ready, ci_pending, ci_failing, has_conflicts, or unresolved_threads
• CI polling: If checks are pending with no actionable PRs, polls every 30s (up to 30 min)
• Agent fixup: For failing CI, conflicts, or unresolved review threads, an AI agent attempts automated fixes
• Rebase cascade: After each merge, dependent PRs are rebased onto the updated base

Agent Skills

Shepherd ships with agent skills that let AI coding agents manage PR dependency graphs. Install them with dotagents:

npx @sentry/dotagents add getsentry/shepherd --all

Or install individual skills:

npx @sentry/dotagents add getsentry/shepherd/manage-pr-sets
npx @sentry/dotagents add getsentry/shepherd/pr-graph

Included skills

| Skill | Description | |-------|-------------| | manage-pr-sets | Run shepherd commands — check status, add/remove dependencies, guide PR sets to merge | | pr-graph | Analyze open PRs, detect dependency relationships, and build a disjoint set forest |

Writing your own skill

Skills live in the skills/ directory following the agent skills spec. Each skill is a folder with a SKILL.md file:

skills/
  my-skill/
    SKILL.md           # Required: frontmatter + instructions
    scripts/           # Optional: executable scripts
    references/        # Optional: additional docs loaded on demand

The SKILL.md must have YAML frontmatter with name and description, followed by markdown instructions:

---
name: my-skill
description: What this skill does. Use when <trigger phrases>.
allowed-tools: Bash Read
---

# My Skill

Step-by-step instructions for the agent...

Key tips:

• Use npx @sentry/shepherd (not bare shepherd) so the skill works without global install
• Use --non-interactive for agent workflows to avoid blocking on prompts
• Use --json for structured output that's easier to parse
• Reference scripts with ${SKILL_ROOT}/scripts/my-script.mjs for portable paths

Options

| Flag | Description | |------|-------------| | -v | Verbose output | | -vv | Debug output | | -q | Quiet mode (errors only) | | --json | JSON output (status command) | | --non-interactive | Output context and stop (guide command) | | -h | Show help | | -V | Show version |

Development

pnpm install
pnpm build
pnpm test          # Run tests
pnpm dev           # Watch mode compilation
pnpm lint          # Lint
pnpm typecheck     # Type check

License

FSL-1.1-ALv2 — see LICENSE for details.