README
¶
loupe
loupe collects a review agent's findings into a local draft so you decide each one and publish a single GitHub review.
Why loupe
- Nothing posts under your name unread. You accept or drop each finding yourself. You write the review's opening, and one confirmation sends one review.
- Any review agent works. loupe has no opinion on how findings are found. The agent files them through a CLI, and a plugin for Claude Code, Codex and Pi teaches it the workflow.
- Findings are files on disk. One directory per run. No daemon, no database, no service to sign up for.
- Human and bot reviews read the same. A CI job can publish through loupe too. Its review uses the same comment format. It is marked unattended and never approves or blocks a merge.
How it works
- Your agent captures the pull request into a run and files its findings into the draft.
- You decide each finding in
loupe review. A finding you send back with a note goes to the agent, which answers it. loupe publishshows the exact review. You write its opening, and one key posts it.
This is what a published review looks like. A CI review uses the same format. See Comment format.
Install
mise use -g github:eriksaulnier/loupe@latest
claude plugin marketplace add eriksaulnier/loupe
claude plugin install loupe@loupe
The first line installs the binary. The other two add the agent plugin to Claude Code. Install covers Codex, Pi, release archives and GitHub Actions.
To try the interface without a pull request, run mise run demo in a clone. It opens loupe review on seeded runs against an in-memory GitHub, so nothing leaves the machine.
Documentation
- Install: the binary, the agent plugin for each host, and updating the two together.
- Comment format: what a published review looks like on GitHub.
- The review workflow: the attended loop, the pane hand-off, adapting a review skill you already have, and the command and environment reference.
- Unattended reviews in CI: the GitHub Action, the pipeline steps, sticky rounds and the rules an unattended review follows.
- CLI contract: commands, input, results and errors, for scripting against loupe.
- Constitution: the seven principles every change answers to.
- Contributing: setup, local development, tests, commits and releases.
License
MIT. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
loupe
command
|
|
|
loupe-demo
command
Command loupe-demo runs loupe against seeded review runs and an in-memory GitHub, so the review interface and the whole publish flow can be tried by hand without a pull request, credentials or network.
|
Command loupe-demo runs loupe against seeded review runs and an in-memory GitHub, so the review interface and the whole publish flow can be tried by hand without a pull request, credentials or network. |
|
internal
|
|
|
cli
Package cli maps loupe's commands onto cobra and turns domain results and refusals into the output contract.
|
Package cli maps loupe's commands onto cobra and turns domain results and refusals into the output contract. |
|
diff
Package diff is the parsed pr.diff that both location validation and the review interface read.
|
Package diff is the parsed pr.diff that both location validation and the review interface read. |
|
draft
Package draft holds the review draft: findings, human decisions, send-back notes and replies.
|
Package draft holds the review draft: findings, human decisions, send-back notes and replies. |
|
findingid
Package findingid orders ids like f-001 so that f-999 sorts before f-1000.
|
Package findingid orders ids like f-001 so that f-999 sorts before f-1000. |
|
gitenv
Package gitenv filters the environment handed to git, shared by gitx and the test repositories.
|
Package gitenv filters the environment handed to git, shared by gitx and the test repositories. |
|
github
Package github is loupe's narrow view of the GitHub REST API, behind an interface so tests can fake it.
|
Package github is loupe's narrow view of the GitHub REST API, behind an interface so tests can fake it. |
|
gitx
Package gitx runs the few git commands loupe needs against the user's clone.
|
Package gitx runs the few git commands loupe needs against the user's clone. |
|
markdown
Package markdown checks authored Markdown against the allowlist in docs/comment-format.md, so a body or summary cannot restructure the <details> wrapper the renderer puts around it.
|
Package markdown checks authored Markdown against the allowlist in docs/comment-format.md, so a body or summary cannot restructure the <details> wrapper the renderer puts around it. |
|
pane
Package pane opens loupe review for the human in a new terminal pane beside the agent's, in Herdr or Orca.
|
Package pane opens loupe review for the human in a new terminal pane beside the agent's, in Herdr or Orca. |
|
publish
Package publish runs the publication state machine: gates, envelope, confirmation, one review request, receipt.
|
Package publish runs the publication state machine: gates, envelope, confirmation, one review request, receipt. |
|
refusal
Package refusal is a leaf so every domain package can return refusals without importing internal/cli.
|
Package refusal is a leaf so every domain package can return refusals without importing internal/cli. |
|
render
Package render composes what loupe shows and sends.
|
Package render composes what loupe shows and sends. |
|
run
Package run owns the on-disk layout of review runs: paths, references, atomic writes and locking.
|
Package run owns the on-disk layout of review runs: paths, references, atomic writes and locking. |
|
section
Package section places a finding in the review body's sections, so that every surface presents findings in the order the published review will.
|
Package section places a finding in the review body's sections, so that every surface presents findings in the order the published review will. |
|
severity
Package severity orders loupe's four severity words so that every surface ranks findings the same way.
|
Package severity orders loupe's four severity words so that every surface ranks findings the same way. |
|
style
Package style is the one place terminal appearance is decided: colors, glyphs and the small layout helpers every human-facing surface shares, so the review interface and the one-shot commands look like one program.
|
Package style is the one place terminal appearance is decided: colors, glyphs and the small layout helpers every human-facing surface shares, so the review interface and the one-shot commands look like one program. |
|
testutil/fakegh
Package fakegh is an in-memory GitHub REST and GraphQL server for the endpoints loupe calls, reached through the production client so request encoding is exercised end to end.
|
Package fakegh is an in-memory GitHub REST and GraphQL server for the endpoints loupe calls, reached through the production client so request encoding is exercised end to end. |
|
testutil/gitrepo
Package gitrepo builds a local stand-in for a GitHub repository: a bare remote, a user's clone of it, and a pull request head published at refs/pull/<number>/head.
|
Package gitrepo builds a local stand-in for a GitHub repository: a bare remote, a user's clone of it, and a pull request head published at refs/pull/<number>/head. |
|
tui
Package tui is the human review interface: a full-screen Bubble Tea program and a line-by-line plain mode.
|
Package tui is the human review interface: a full-screen Bubble Tea program and a line-by-line plain mode. |
Click to show internal directories.
Click to hide internal directories.