sherpa

sherpa is a CLI tool that runs an AI code review locally on your changes before you commit.

Install

pipx install "git+https://github.com/dubloom/sherpa.git"

Configuration

If --model is not provided, Sherpa uses .sherpa/config.json.

On first launch, if no config is found, Sherpa starts an interactive setup to choose:

• default model (from the supported models list)
• default reasoning effort (low, medium, high)

It then creates:

{
  "default_model": "gpt-5.3-codex",
  "default_reasoning_effort": "medium"
}

default_reasoning_effort only applies to OpenAI models and must be one of:

• low
• medium
• high

To update config later:

sherpa config

Tokens

Sherpa can store provider tokens globally so they keep working across new terminals.

Use:

sherpa token

To update only one provider without touching the others:

sherpa token openai
sherpa token anthropic
sherpa token github

This updates tokens stored in ~/.sherpa/tokens.json for:

• OpenAI
• Anthropic
• GitHub

Each prompt is hidden. Leaving a prompt blank clears the stored token for that provider.

For each provider, the matching environment variable overrides the stored value:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• GITHUB_TOKEN

Stored OpenAI and Anthropic tokens are loaded into the Sherpa process automatically when the corresponding environment variables are not already set.

Usage

sherpa commit: review before committing

Run an AI review on your staged changes, then commit if approved:

sherpa commit -m "my commit message"

sherpa commit is intended to work like git commit:

• all arguments passed after sherpa commit are forwarded to git commit
• you can still pass your regular commit flags/message

Choose a model for that run:

sherpa commit --model claude-opus-4-5 -m "my commit message"

For OpenAI models, you can also set reasoning effort explicitly:

sherpa commit --model gpt-5.3-codex --reasoning high -m "my commit message"

For default model and reasoning-effort behavior, see the Configuration section.

Review feedback can include four categories:

• High (errors, blocks commit)
• Medium (warnings, does not block commit)
• Low (debug-level feedback, does not block commit)
• Nice to have

Each issue/nit gets an identifier you can use in the fix stage.

When a commit is approved via sherpa commit, Sherpa appends an Approved-By: <model_name> trailer to the commit message.

Commit hooks (pre-review)

Sherpa supports repo-local commit hooks that run before AI review.

Create a named hook:

sherpa hook add lint

This scaffolds a single prompt-only Glyph markdown workflow, for example .sherpa/hooks/lint.md. Edit the step body to describe what the model should check; placeholders {{ key }} are filled from Sherpa (see comments at the top of the generated file).

At commit time, Sherpa discovers every *.md workflow under .sherpa/hooks/ and runs them sequentially in sorted path/name order.

Hook context is passed as initial_input and includes:

• repo_root
• commit_args
• commit_message
• modified_files
• git_diff

The model’s final message must be JSON Sherpa can parse (plain JSON or one fenced block is accepted):

• {"status": "continue"} to keep going
• {"status": "block", "message": "reason"} to stop before AI review

The first hook returning block aborts commit flow. Hook execution errors are also treated as safe failures and abort before review.

sherpa fix: fix selected issues

Use sherpa fix to select one or more issues from the latest stored review and apply fixes.

When multiple issues are selected, Sherpa can run fixes in parallel using separate git worktrees.

sherpa fix

Target specific issue IDs:

sherpa fix H0 M1

Before each selected fix task starts, Sherpa prompts:

Extra Instruction:

Leave it blank to run without extra instructions.

sherpa review: run standalone reviews

Review staged changes (default):

sherpa review

Review a specific commit:

sherpa review <commit>

Quick review workflows:

sherpa review --last
sherpa review --branch

Combine with global options like --model:

sherpa --model claude-haiku-4-5 review --branch

sherpa address: address pull request feedback

Use sherpa address to browse GitHub PR comment threads in your terminal, reply, and run a fix flow for a selected thread.

sherpa address

sherpa address must be run in the right repo and on the right branch to benefit from the right code location.

By default, Sherpa infers the current PR from your branch and origin remote but you can also target a PR explicitly:

sherpa address https://github.com/<owner>/<repo>/pull/<number>

Prerequisites:

• GITHUB_TOKEN must be set, or a GitHub token must be stored via sherpa token
• origin must point to GitHub (for PR inference)

Inside the address UI you can:

• navigate threads (Enter/next, back/prev, and ↑/↓ in interactive terminals)
• reply to a thread (r or reply)
• run an AI-assisted fix flow for the current thread (f or fix)
• mark a thread as done in the local session (d or done)