Tulip

Tulip explains GitHub PRs - categorizing and prioritizing the changes - and presenting them on a web page as prose, diagrams, and code.

Every code change appears somewhere in the explanation, so nothing slips past you. Yet you don't have to wade through it all: instead of digging through piles of code to find the logic that matters, you can focus on the algorithms, the design choices, the core functionality. The explanations are top-down: a high-level overview first, then down into the code.

And if you don't know the codebase at all, the prose and the generated diagrams may be enough on their own to understand the PR well enough to accept or reject it.

Tulip uses the headless claude CLI to do the analysis. No API key needed, just a logged-in Claude Code.

Click a screenshot to view it full size.

How it works

Tulip fetches the PR and runs it through a few LLM passes, each using a model sized to the job (Haiku, Sonnet, or Opus):

1. Fetch & check out. Get the PR (title, description, diff) via gh (or the GitHub API), check out its head revision, and write the full diff plus the before-versions of changed files into the checkout, so later passes can read the real code.
2. Categorize (Sonnet). Split the changes into a few self-contained groups by concern — tests and docs ride along with the code they belong to. Each group gets an attention rating (Read closely / Read through / Skim); groups are ordered most-important first. A second Sonnet pass reviews the groups and amends them if the split is off.
3. Split large changes (Sonnet). For each change over a size threshold, decide whether it spans more than one group's concern and, if so, where to cut it — turned into an exact partition in code, so no line is lost. This lets the next step route the pieces of a big multi-concern file to different groups.
4. Classify (Haiku). Assign every change to one or more groups and mark it as production or test code. Unfitting changes can propose a new group; generated files and lockfiles are dropped; every change is checked to be covered. A change that lands in several groups is owned by one — its highest-attention group — and only linked from the others.
5. Explain (Opus, one session per group; Sonnet review). Write a top-down prose explanation grounded in the real code: open with the overall shape and an orienting diagram — a dependency graph, data flow, class, state, ER, or sequence diagram, as the change calls for — then drill into each change, leading with its interface, folding routine code by default, and showing in full only what the group's attention rating and the must-see cases demand. A change owned by another group is linked, not re-explained. A Sonnet pass reviews each explanation; every referenced snippet is checked to appear and every diagram validated to render.
6. Render. Assemble everything into one self-contained HTML page: light/dark theme, foldable sidebar table of contents, syntax-highlighted side-by-side diffs, and the attention badges.

The result is a temporary directory with the page; Tulip logs the file:// path to open.

Prerequisites

• Node.js LTS (>= 24) — its bundled npm installs Tulip; pnpm is only needed to build from source
• A logged-in claude CLI on PATH — Tulip drives it to analyze the PR
• Optionally, the gh CLI, logged in — used to fetch PR data when available; Tulip falls back to the GitHub REST API otherwise (set GITHUB_TOKEN to raise the unauthenticated rate limit)

Private repositories also need credentials for git fetch. If your git config rewrites the host to SSH (insteadOf), git uses your SSH key and nothing else applies. Otherwise git uses the first credential helper that answers: your own setup first (such as the OS keychain or gh auth setup-git), then a logged-in gh, then GITHUB_TOKEN. If your own helper answers with a credential the host rejects, fix or clear that credential. Tulip fails with a hint instead of asking for a username and password on the terminal.

Self-hosted GitHub Enterprise Server URLs (e.g. https://git.example.com/owner/repo/pull/7) work too. Authenticate that host once with gh auth login --hostname git.example.com; the REST fallback uses the host's /api/v3 endpoint with GITHUB_TOKEN.

Install

npm install -g @virtuslab/tulip
# or: pnpm add -g @virtuslab/tulip

This puts a tulip command on your PATH. To run from source instead, see Development.

Usage

tulip <PR URL> [options]

Example:

tulip https://github.com/owner/repo/pull/123

Flags: --diff-threshold <n>, --verbose, --serve, --no-open. Run tulip --help for details, or tulip --version for the build.

On success, Tulip logs a file://... path to the generated HTML page — open it in a browser.

Reviewing on the page

tulip <PR URL> --serve

--serve runs a local server that hosts the page and opens it (unless --no-open), adding a box under each category. Type a note and click Post to GitHub to post it as a PR comment, prefixed with the category name. Each box posts its own comment. Ctrl+C stops the server.

This needs an authenticated gh CLI for the PR's host (self-hosted included) — gh auth login --hostname <host>; Tulip checks this before starting. Comments are posted via gh, so they come from your GitHub account.

Development

pnpm build        # compile TypeScript + copy rendering assets
pnpm test         # run the test suite (vitest)
pnpm lint         # check formatting/lint rules (biome)
pnpm lint:fix     # auto-fix formatting/lint issues
pnpm dev <PR URL> # run the CLI from source, no build step (tsx)

To put your local build on PATH as tulip, run pnpm add -g . after pnpm build.

Design decisions are recorded as ADRs in docs/adr/; the LLM prompts live as plain text in src/prompts/.