Review code and pull requests
Gaunt Sloth reviews are stateless — nothing carries over between runs, so a verdict can’t be
argued down across a conversation — and a failing review exits non-zero. That combination is
what makes gth usable as an on-prem review gate: run it in CI, and a bad diff fails the job the
same way a failing test would.
The main use case: gate every pull request in CI
Section titled “The main use case: gate every pull request in CI”Goal: every PR gets reviewed automatically against its linked issue, and the result blocks the merge if the review fails.
In your CI job, after checking out the PR branch:
export ANTHROPIC_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}"gth pr 42gth pr 42 fetches PR #42’s diff with the GitHub CLI (gh), finds the issue linked in the PR
description, and reviews the diff against that issue as the requirements. If the review fails, the
command exits non-zero and the CI step fails.
Two prerequisites for gth pr:
- the GitHub CLI (
gh) is installed and authenticated (in CI,ghpicks upGH_TOKEN); - the provider key is exported, exactly as in the Quickstart.
Run with no arguments — gth pr — and it discovers the current branch’s PR and its requirements
for you, which is handy in a job that already knows its own branch.
When a large PR’s diff comes back truncated, the reviewer can pull a whole changed file from the
PR’s own repository over the GitHub API rather than review a hunk blind — the gth_gh_read_file
built-in tool, on by default for gth pr and using the same gh login. Turn it off, or cap how
much one call may return, through
builtInTools.
(It follows the content source: gth review gets it too whenever that run’s content source is
github, whether your config sets it or you pass --content-source github for the one run.)
Review a local diff before you push
Section titled “Review a local diff before you push”You don’t need a PR to review. Pipe any diff in:
git --no-pager diff | gth reviewOr let the git content source run the diff for you:
gth review --content-source gitAdd requirements to check against, and focus the reviewer:
gth review --content-source git -r requirements.md -m "focus on security implications"To review everything your branch will put in its pull request, uncommitted edits included, point
the git source at the branch you will merge into:
{ "commands": { "review": { "contentSource": "git" } }, "contentSourceConfig": { "git": { "mergeBase": "origin/main" } }}Then a bare gth review diffs your working tree against the commit where the branch left
origin/main, so work merged to origin/main since then is not reviewed as if you had deleted it.
What the setting accepts, and why untracked files stay out:
Git (local diffs).
Review a branch against its Jira issue, locally and in the pull request
Section titled “Review a branch against its Jira issue, locally and in the pull request”Goal: gth review on your branch, and gth pr on its pull request, both review against the Jira
issue the branch is for, with nobody typing the issue key.
{ "mcpServers": { "jira": { "url": "https://mcp.atlassian.com/v1/mcp", "authProvider": "OAuth", "transport": "http" } }, "contentSourceConfig": { "git": { "mergeBase": "origin/main" } }, "commands": { "pr": { "contentSource": "github", "discovery": { "filesystem": "none", "builtInTools": [], "customTools": false, "allowedTools": ["gh_pr", "gh_diff", "mcp__jira__getJiraIssue"] } }, "review": { "contentSource": "git", "filesystem": "read", "discovery": { "enabled": true, "filesystem": "none", "builtInTools": [], "customTools": false, "allowedTools": ["mcp__jira__getJiraIssue"] } } }}A bare gth review then diffs the branch against where it left origin/main. With no -r, it
collects the branch name and the branch’s pull request as evidence, and because Jira is reached
through the MCP server rather than a Jira requirement source, a discovery agent reads the issue key
from that evidence and fetches the issue with mcp__jira__getJiraIssue. A bare gth pr runs the
same kind of discovery from the pull request. Each discovery agent gets only the tools in its own
allowedTools and no filesystem access, so it looks up the issue and nothing else. The first run
opens a browser for the Atlassian sign-in.
Every discovery key: Review Requirements Discovery Configuration.
What a review is labelled with
Section titled “What a review is labelled with”By default, every review and pr run opens its output with one line — the same run header every
Gaunt Sloth command opens with, naming the command you ran and the model that served it:
Gaunt Sloth · review · gemini-3.1-pro-preview (google-genai)A gth pr run says pr. That comes from the CLI itself, so it reaches everywhere the output goes —
your terminal, the writeOutputToFile
report, and any pull request comment a workflow posts from that file — with nothing to wire up. A
review is usually read somewhere the command that produced it is not visible, and an unlabelled AI
review sitting under a bot avatar gets credited to whichever AI reviewer the reader already knows.
The provider half is dropped when a JS config hands Gaunt Sloth an already-built model, because there is then no provider name to report; the model is dropped altogether when none resolves, leaving the line ending at the command rather than showing a placeholder.
A run that fails before the model is reached — a pull request over GitHub’s 300-file diff limit, no
gh on the path — writes that report as well, headed the same way, with the error in it in place of
a verdict. The run still exits 1, so a workflow fails on the review step; what changes is that the
comment it posts names the failure instead of the next step dying on a file that is not there.
The header belongs to the review document rather than to the technical preamble, so the default
output.header: "compact" keeps it while
dropping the Workdir/Model/Tools lines — on a review, this line is the compact header. Only
output.header: "none" removes it, for a caller who is piping the review into a template of their
own; set that deliberately, because a review posted without it is a review nobody can attribute.
Examples
Section titled “Examples”# Review PR #42 with GitHub issue #23 as the requirementsgth pr 42 23
# Review PR #42 against a Jira issue insteadgth pr 42 PROJ-123 -p jira
# Review a specific commit range (no pipe) via the git content sourcegth review origin/main...feature-branch --content-source git
# Review the working diff with a requirements filegit --no-pager diff | gth review -r requirements.mdRelated
Section titled “Related”- Pull requirements from a GitHub issue or Jira automatically: Content sources.
- Every
review/prflag: Commands. - Run the review under a cheaper model than your coding model: Choose & switch models.
- Attach a package’s own guidelines only when the diff touches it, instead of one guidelines file for the whole repository: Path-scoped prompts.