pr-split

Decompose large PRs into a DAG of small, reviewable stacked PRs

Why pr-split?

Vibe coding with AI assistants can produce massive PRs that no one wants to review. A 2,000 line PR with changes across dozens of files is a review bottleneck: teammates skim it, rubber stamp it, or just ignore it. pr-split turns that monolith into a stack of focused, bite-sized PRs your team can actually review with confidence. Each sub-PR has a clear purpose, minimal scope, and explicit dependencies, so reviewers know exactly what changed and why.

How it works

pr-split takes a large pull request (local branch, fork PR number, or user:branch), sends the diff to an LLM for analysis, and produces a split plan: a set of smaller, focused PRs arranged in a dependency DAG. Each sub-PR gets its own branch, commit, and GitHub PR targeting the correct base.

Installation

# With uv (recommended)
uv tool install pr-split

# With pip
pip install pr-split

Prerequisites

• Python 3.12+
• GitHub CLI (gh) authenticated via gh auth login
• ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable set

Usage

Split a local branch

pr-split split feature-branch --base main

Split a fork PR by number

pr-split split '#42' --base main

Split a fork PR by user:branch

pr-split split someuser:feature-branch --base main

Options

Flag	Default	Description
--base	main	Base branch for the diff
--max-loc	400	Soft limit on diff lines per sub-PR
--priority	orthogonal	Grouping priority (orthogonal or logical)

Other commands

# Show status of an existing split
pr-split status

# Clean up all pr-split branches and close PRs
pr-split clean

Configuration

Settings can be set via environment variables with the PR_SPLIT_ prefix:

Variable	Default	Description
PR_SPLIT_PROVIDER	anthropic	LLM provider (anthropic or openai)
ANTHROPIC_API_KEY	(required for Anthropic)	Anthropic API key
OPENAI_API_KEY	(required for OpenAI)	OpenAI API key
PR_SPLIT_MODEL	auto per provider	Model name (defaults to best available model for the chosen provider)
PR_SPLIT_MAX_LOC	400	Default soft limit on diff lines
PR_SPLIT_PRIORITY	orthogonal	Default grouping priority

What it does

1. Extracts the merge-base diff between your branch and the base (same view as GitHub's PR page)
2. Sends the diff to the configured LLM, which groups hunks into logical sub-PRs with dependency ordering
3. Validates the plan: full coverage (every hunk assigned exactly once), no cycles, no merge conflicts between independent groups
4. Shows you the plan (table + dependency tree) and asks for confirmation
5. Creates branches, commits, pushes, and opens GitHub PRs in topological order
6. For diffs exceeding the model's context window, automatically chunks the diff and processes sequentially, carrying forward the group catalog across chunks

License

MIT