Local AI review bundles for GitHub, GitLab, Bitbucket Cloud, and local branches — with humans in control of what gets published.
revpack turns a GitHub PR, GitLab MR, Bitbucket Cloud PR, or local branch range into a local review bundle for coding agents. The bundle contains the diff, commit messages, unresolved review discussions, previous review state, and valid line-comment positions.
Your agent can perform a formal review or use the bundle as context for another task, such as discussing or fixing existing review threads. Formal reviews write proposed findings, replies, summaries, and review notes. Nothing is posted to the provider until you publish it.
prepare review context → run your agent → inspect pending output → publish intentionally
Use revpack when you want AI-assisted review that is conversation-aware, agent-neutral, and human-controlled.
Install the CLI:
npm install -g @stefanvictora/revpackOpen the repository you want to review, then set up provider authentication:
revpack auth setup
export REVPACK_GITHUB_TOKEN=ghp_xxxxxxxxxxxx
# or
export REVPACK_GITLAB_TOKEN=glpat-xxxxxxxxxxxx
# or
export REVPACK_BITBUCKET_EMAIL=you@example.com
export REVPACK_BITBUCKET_TOKEN=ATBBTxxxxxxxxxxxx
revpack auth doctorauth setup stores provider settings such as the provider type, host URL, and token environment variable name. It does not store your provider token directly.
Add review guidance and instructions for your agent:
# Pick one:
revpack setup --agent claude
revpack setup --agent codex
revpack setup --agent cursor
revpack setup --agent copilotThis creates REVIEW.md when missing and writes project-level instruction files, such as an agent command, skill, or prompt. It does not install or run the agent.
Use --dry-run to preview generated files before writing them.
Rerunning setup refreshes unmodified generated adapters. Customized adapters are preserved with a command hint; use --force when you intentionally want to replace them. Setup never replaces REVIEW.md.
Prepare, use the context, review, inspect, and publish:
revpack prepare
# Perform a formal review:
# Claude, Copilot, or Cursor: /revpack-review
# Codex: $revpack-review
# Or ask any agent to perform a revpack review.
#
# Use the bundle for another task:
# Claude, Copilot, or Cursor: /revpack-context
# Codex: $revpack-context
# For example: "Fix the active review threads."
revpack status
revpack publishrevpack prepare creates or refreshes .revpack/ for the current PR/MR or local branch range.
The bundle gives the agent the review context it needs:
.revpack/
CONTEXT.md # agent entry point
description.md # PR/MR description
commits.md # commit messages as intent context, when available
threads/ # active review discussions
resolved-threads/ # resolved review discussions kept as context
diffs/
latest.patch # full diff
incremental.patch # follow-up changes, when a checkpoint exists
files.json # changed-file index and per-file artifact paths
patches/by-file/ # standard per-file diffs
anchor-maps/ # compact per-file positional anchors
schemas/ # read-only schema references for JSON outputs
outputs/
new-findings.json # agent-created new line comments, when needed
replies.json # agent-created replies to existing threads, when needed
summary.md # agent-created PR/MR summary
note.md # agent-created optional review note, when needed
The bundle is local and disposable. Use revpack clean to remove it, then run revpack prepare to recreate it. Published checkpoints are stored with the PR/MR, so cleaning the local bundle does not reset incremental review history.
CONTEXT.md explains two task paths. A formal revpack review follows the generated Review Contract and writes draft material only to .revpack/outputs/. Bundle context use instead follows the developer's task and repository instructions, so the agent may discuss threads, edit source or documentation, and run appropriate verification. Fixing or addressing active threads also drafts useful replies in .revpack/outputs/replies.json. Missing conditional draft files mean there is nothing pending for that output.
You decide what goes back to the provider.
Agent-authored findings and replies carry per-item model attribution when the agent can report its exact runtime model. Revpack appends AI-generated via revpack · Model: … during publishing, falls back to a generic AI attribution when model metadata is unavailable, and shows the result in Guided Publish. Review notes retain the generic AI footer. A reply supplied directly with revpack publish replies <thread> --body <text> is labeled Published via revpack instead of being presented as AI-generated.
Run bare revpack publish in an interactive terminal to open Guided Publish. It shows every category in a keyboard-navigable list and a complete preview of the highlighted item before anything is published. Findings and replies can be selected individually.
- Use Up and Down to navigate.
- Press Space to toggle an item or group header, or
ato toggle every selectable item in the focused group. - Use Page Up and Page Down to scroll the preview.
- Press Enter to review a confirmation of what will publish and what will remain, or Escape to cancel or return to the selection screen.
Pending material starts selected. If you leave out a finding or reply, it remains unchanged as a deferred draft for a later run. Deselecting pending material also turns off the checkpoint; you can explicitly re-enable it after reviewing a warning that drafts will remain.
Guided Publish will not publish from a stale bundle. It offers to refresh the bundle, preserving pending drafts, or cancel. If freshness cannot be determined, publishing stops rather than proceeding with potentially outdated previews.
Bare revpack publish requires interactive input and output terminals. On Windows, Guided Publish refuses to start
inside JetBrains terminals because their terminal emulator can terminate the PowerShell session when the TUI closes;
run it in Windows Terminal instead. The
investigation record preserves the reproduction and
removal criteria. Explicit publish subcommands remain available in JetBrains terminals. Use the explicit commands
below in scripts, CI, and other non-interactive environments.
| Output | Command |
|---|---|
| Guided preview and selection | revpack publish |
| All pending outputs | revpack publish all |
| New line comments | revpack publish findings |
| Replies to existing threads | revpack publish replies |
| PR/MR summary | revpack publish summary |
| Review note | revpack publish note |
| Review checkpoint | revpack publish checkpoint |
Useful variants:
revpack publish findings --dry-run
revpack publish replies T-001Important
When publishing selected outputs, publish checkpoint last. It records the reviewed PR/MR state used for future incremental reviews.
revpack is useful when the agent should review more than a patch.
It helps when you want to:
- include unresolved PR/MR discussions in the agent run
- use PR/MR changes and discussions as context without starting a formal code review
- avoid repeating already-raised feedback
- draft replies to reviewer or author questions
- focus follow-up reviews on what changed since the last checkpoint
- inspect AI-generated output before it reaches the PR/MR
- use your preferred agent instead of a fixed review bot
You may not need revpack for quick local changes, reviews where the PR/MR discussion does not matter, or teams that prefer fully automatic bot comments.
revpack does not replace CI or human review judgment. It prepares the review context; your agent reviews it; you decide what gets published.
revpack prepareIf a checkpoint exists, revpack includes the latest code and thread changes since that checkpoint so the agent can focus its follow-up review.
revpack prepare --local
revpack prepare --local main
revpack prepare --local main...HEADLocal mode reviews committed branch changes against an inferred or explicit base branch. Uncommitted working-tree changes are not included.
revpack checkout https://gitlab.example.com/group/project/-/merge_requests/42
revpack checkout !42 --repo group/project --profile myGitlab
revpack checkout 58 --repo user/project --profile myGithubInside a repository, checkout fetches and switches to the review branch. Outside a repository, it creates a shallow clone. In both cases, it prepares the bundle after checkout.
After revpack prepare, ask the agent:
Perform a revpack review. Start at `.revpack/CONTEXT.md`.
Or use the bundle for another task:
Use `.revpack/CONTEXT.md` as context and fix the active review threads.
For repeated use, add project-level instructions for your agent with revpack setup agent <target>.
npm install
npm run dev -- prepare !42
npm test
npm lint:fix
npm formatrevpack is early but usable for local AI-assisted PR/MR reviews. Expect CLI details and bundle internals to evolve while the provider workflows stabilize.