Documentation

What is grsp?

grsp is a native macOS app that opens a pull request and tells you what it actually does. You point it at a PR. It checks the PR out into a read-only worktree, lets the Claude Code or Codex you already have explore the change, and checks every claim the agent makes against git before showing it to you.

You get three views of the same change: a Gist that compares what the author says with what the code does, a Walkthrough that steps through the changed behaviour like a debugger, and a Review you can edit and post back to GitHub.

Why

A diff is ordered by file name, not by what happens. It shows the lines that changed and hides everything else: the callers, the other code that writes to the same table, the job that should have been updated and wasn't. Reviewing by reading means rebuilding all of that in your head and trusting the description for the rest.

grsp starts from behaviour instead. Which entry points act differently now? What path does a request take? Does the code do what the description says?

Getting Started

You need a Mac, a coding agent you're already signed in to, and (for GitHub pull requests) the GitHub CLI. There are no API keys to create and nothing to configure per project.

Install

Download the .dmg for your Mac from the home page, open it and drag grsp into Applications. The app updates itself.

Or build it from source:

git clone https://github.com/ghvstcode/grsp.git
cd grsp
pnpm install
pnpm tauri:dev

Building needs Node.js 22+, pnpm and stable Rust.

Onboarding

The first launch walks you through five short steps.

Agents

grsp doesn't talk to a model API. It runs the agent CLI you already use, headless and read-only, with its working directory set to the PR's worktree.

Detection checks your PATH and then the usual install locations (~/.local/bin, /opt/homebrew/bin, node version managers). If the agent isn't installed or isn't signed in, grsp says so in onboarding and in Settings and tells you what to run:

# Claude Code
claude            # then /login

# Codex
codex login

GitHub via gh

grsp uses the GitHub CLI for everything it does on GitHub: listing open PRs, reading PR metadata, CI status and review threads, and posting your review. It uses the account gh is signed in to, so grsp itself stores no GitHub token.

brew install gh
gh auth login

Without gh you can still compare two branches of any repository, on any git host. That mode has no discussion and no posting, and the app says so where those features would appear.

Your first review

Press New review in the sidebar. There are three ways to start a session:

• Paste a URL. https://github.com/owner/repo/pull/123, with or without /files on the end. If you haven't added that repo's folder yet, grsp asks you to.
• Pick an open PR from the list for a repo you've added.
• Choose two branches, local or remote, as base and head.

grsp fetches the refs, creates the worktree, works out what changed against the merge base, and starts the first analysis. Each step is shown in plain language as it happens, and each section of the Gist appears as soon as it's ready.

If the author pushes while you're reviewing, the session shows a bar like “3 new commits since you started. Refresh analysis.” Nothing re-runs until you press it.

How it works

Agent-first

All of the understanding is done by your coding agent. It explores the worktree, finds the entry points, traces paths, spots gaps, answers questions and reviews. grsp itself has no language parser and no framework detection, which is why it works on any repository your agent can read, in any language, with no per-project setup.

Around the agent, grsp's Rust core provides three things:

• Git facts. What changed and exactly where, computed from the merge base so changes on the base branch don't leak into the PR.
• Verification. Every claim about the code is checked against the worktree and the diff.
• Orchestration. Worktrees, caching, progress, cancellation and GitHub.

build the prompt → run the agent → parse JSON → verify → save → show

Verification

The agent is asked to back every claim with a code reference: a file, a line, and a short anchor copied from that line, such as a function name or order.total > THRESHOLD. grsp then checks each one.

A mismatch, a gap or a review finding with no verified reference is never shown. Softer claims that are still useful without one stay visible and are marked unverified.

The same goes for everything else you see about the code:

• Change status is computed from the diff, not reported by the agent: New Changed Unchanged Not covered. A “gap” that turns out to be part of the diff isn't a gap.
• Code excerpts are read from the worktree by grsp. The agent never supplies code text.
• Edges between walkthrough blocks are spot-checked: if block A is said to call block B, A's code has to mention B. Edges that can't be confirmed are drawn dotted.
• Discussion and CI come from the GitHub API. The agent only summarises them.

Under “Code does” the Gist shows one quiet line with the result, for example Agent explored 23 files · 41 references verified · 2 unverified.

What runs when

Each analysis is one headless agent run, called a pass. grsp runs as few as it can, and at most two at a time.

While a pass runs, its section shows what the agent is doing (“Reading orders/services.py”, “Searching for bulk_create”) rather than a bare spinner. A pass that fails shows the error and a Retry button and never blocks the other sections. Passes time out after 5 minutes and can be cancelled.

Very large PRs (more than 60 changed files or 3,000 changed lines) are analysed in up to four parts by top-level directory and then merged. The Gist says so: “Large PR: analysed in 4 parts.”

What's cached

Everything is stored locally in SQLite and keyed by the PR's head commit. Reopening a session, or switching tabs, never re-runs an agent. A result computed for one commit is never shown for another.

• Kept: every analysis, your Ask history, which questions you've opened, your edits to findings, and the reviews you've posted.
• On a new push: the session is marked stale. Refreshing builds a new worktree and re-runs only the analyses that had already run. Older Ask answers stay, marked “from an earlier version”.
• Worktrees live in grsp's app data folder, not in your clone. They are removed when you archive a session or leave it untouched for 14 days, and recreated on demand.

Cost

grsp is free and has no usage of its own. Every pass runs on your Claude Code or Codex subscription and counts against its limits the same way a session in your terminal would. So grsp is frugal:

• Results are cached by commit.
• Walkthroughs and the review run only when you ask for them.
• Nothing re-runs when the window gets focus. Only Refresh and Retry start a pass.
• The session footer shows how many agent passes the session has used.

A typical PR is one discovery pass, one questions pass, one discussion pass, a walkthrough or two, and a review.

The three tabs

Every session has the same header (PR number and title, author, branches, CI status, files changed, a mismatch pill, your posted verdict) and three tabs.

Gist

The Gist answers “what is this PR, really?” in one screen.

• Author says / Code does. The PR description beside a short plain-language summary of the behaviour, written from the code.
• Mismatch. Shown only when the description makes a checkable claim that the code contradicts or doesn't fully implement. Walk through it jumps to the step where it goes wrong. An empty description produces no mismatches.
• What's affected. Up to 12 entry points whose behaviour changes: HTTP routes, UI actions, jobs, consumers, scheduled tasks, CLI commands, public APIs. Each has a one-line effect and a tag. Entry points with gaps come first.
• Not covered. For everything the PR writes to (a table, a model, a file, a state field), the agent searches the repo for other code that writes to it and bypasses the new behaviour. Those are gaps, and they are the part of a change a diff can't show you.
• Can you answer these? Three to six questions about behaviour a reviewer should be able to answer: edge cases, failure modes, permissions, migrations, concurrency. Opening one reveals the answer with its references and marks it checked.
• Discussion on GitHub. Collapsed to a one-line digest; expanded, a “Where it stands” summary and the threads, open ones first. Suggested changes render as diffs.

Ask

The panel on the right of the Gist answers questions about the change. The agent can read anything in the worktree, not just the diff, and follow-ups take the last few questions into account.

Each answer comes with a trace line (how many files were explored and how many references verified), an optional code excerpt with the key line highlighted, and file:line chips.

When a question can't be answered from the code, the answer says so plainly and names the closest relevant code. grsp never answers from general knowledge as if it were about your repo. Shaky answers carry a quiet “Low confidence” label.

Walkthrough

A debugger for behaviour. Pick an entry point and step through what happens, one block at a time:

POST /orders → CreateOrderSchema.validate → OrderService.create
  → ApprovalPolicy.check → orders.insert → emit approval.requested → Mailer.send

Each block shows what kind of step it is, whether it's new, changed or unchanged, a one or two sentence note on what happens there, its code at the PR head with diff markers, and, where the code branches, the decision: the condition and which side is taken.

When a changed decision depends on an input, the walkthrough offers a What if with two or three values. Choosing another value re-routes the rest of the chain. This is reasoning over the code, not execution, and it's labelled “Based on reading the code.”

Paths are at most 12 blocks and only follow branches that reach changed code, a gap, or an external effect such as a payment or an email. Turn off Show unchanged blocks in Settings to step only through what the PR touches.

Review

Press Run to get an AI review using your review prompt. It knows what discovery found and what the discussion has already settled, so it doesn't repeat resolved points.

• Findings are grouped as Blocking, Should fix or Nit. Each has a title, why it matters, the code with the line highlighted, and a comment you can edit.
• Untick Include in review to leave a finding out.
• Choose Comment, Approve or Request changes, edit the summary, and post.

GitHub only accepts inline comments on lines that are part of the PR's diff. A finding on such a line posts inline. A finding about code the PR didn't touch (often the most important kind) is marked “Posts in summary” and goes into the review body under “Not in this diff” with its file:line written out.

On your own PR, GitHub doesn't allow Approve or Request changes, so grsp disables them and says why. If the PR has moved on since the review was generated, grsp warns you before posting. And it checks for an existing review of yours on the same commit first, so a retry after a network error can't post twice.

Settings

Open Settings from the bottom of the sidebar. Two optional files in a repository let a team share its configuration: .grsp/prompt.md and .grsp/config.toml.

Review prompt

The instructions the AI review follows. It's global, plain text, and yours to rewrite. Reset to default restores this:

You are reviewing a pull request. Prioritise correctness and data
integrity over style. Flag any path where state changes without the
checks the PR description promises. Group findings as Blocking,
Should fix or Nit. Keep each comment under 80 words and say what to
change, not just what is wrong.

.grsp/prompt.md

Commit a .grsp/prompt.md to a repository to give every agent pass in that repo extra context: the architecture in a paragraph, what your team cares about in review, what to ignore. It is appended to your review prompt for that repo, and the Review tab shows “Repo prompt active” when one is in use.

This is a payments-adjacent backend. Money moves in orders/ and payments/.

- Anything that changes an order's status must go through OrderService.
- Flag new writes that skip the audit log.
- We don't care about import order or docstring style.

The file is read from the PR's head, so a PR that changes it is reviewed with the new version.

.grsp/config.toml

grsp leaves vendored, generated and lock files out of the analysis so the agent spends its time on code people wrote. Out of the box it skips:

• paths marked linguist-generated or linguist-vendored in .gitattributes;
• node_modules, vendor, dist, build, *.min.* and lockfiles.

Add your own globs with an exclude list in .grsp/config.toml:

exclude = [
    "api/generated/**",
    "**/*.snap",
    "fixtures/**",
]

Excluded files don't count towards the changed files and aren't included in the diff the agent is given. They are still in the worktree, so the agent can read them if a path leads there.

Agent

Switch between Claude Code and Codex. The status card shows whether the agent was detected, where its binary is, whether it's signed in, and the command grsp runs it with. Re-check runs detection again. Switching agents takes effect on the next pass; existing results stay.

Analysis

Hosts & repositories

Git hosts. GitHub is supported for PR sessions. GitLab and Bitbucket are marked “Coming soon”; until then, comparing two branches works with any host.

Repositories. The folders grsp knows about. Adding one requires a git repository; the GitHub owner and name come from its origin remote. Removing a repo archives its sessions and never touches the folder itself.

Privacy

• Your code is read locally, from a worktree on your disk. The only place it goes is to Claude Code or Codex, running under your account, under the terms you already have with that provider.
• The agent is read-only. Claude Code is limited to read, search and list tools; Codex runs in its read-only sandbox. Neither can edit files or run commands that change state, and the worktree is separate from your working copy.
• No API keys. grsp never asks for, uses or stores model API keys.
• GitHub is reached through gh with the account you signed in to. Nothing is posted until you press Post.
• Analyses and history are stored in a SQLite database in the app's data folder on your Mac.
• grsp's own server handles sign-in and anonymous usage metrics: which features are used and whether analyses finish, tagged with a random install id (and your grsp account if you signed in). Never repository names, code, diffs, PR titles, questions, comments or agent output. Turn it off in Settings → General.

FAQ