Superdub

Review PRs and generated code in plain English.

Superdub helps you actually read code before you ship it. Run it on your local changes or an incoming GitHub PR, and it opens a local browser review UI that explains the changed code in plain English. Start with concise block-level explanations, then switch to line-by-line translation when you need to inspect a file closely.

Quick Start

Set your Claude API key:

export ANTHROPIC_API_KEY=...

Run it in any git repo:

npx superdub

Or install it globally:

npm i -g superdub
superdub

Superdub writes .superdub/annotations.json and .superdub/cache.json, starts a local server, and opens a browser review UI. It reviews your working-tree diff against HEAD by default.

If both Claude and OpenAI keys are present, Superdub uses Claude by default. You can choose explicitly:

superdub --provider anthropic
superdub --provider openai

API Keys

Superdub requires your own Claude or OpenAI API key. There is no Superdub account, hosted backend, or shared API key in the default product. You can export a key or put it in a local .env file:

ANTHROPIC_API_KEY=...
ANTHROPIC_MODEL=claude-haiku-4-5
ANTHROPIC_BASE_URL=...

OPENAI_API_KEY=...
OPENAI_MODEL=gpt-4.1-mini

Override the model from the CLI:

superdub --model claude-haiku-4-5

For Claude Code or gateway setups, Superdub also accepts ANTHROPIC_AUTH_TOKEN when ANTHROPIC_API_KEY is not set.

Commands

superdub                  # review current working tree
superdub main..HEAD       # review a specific git diff range
superdub --diff main..HEAD
superdub pr 123           # fetch and review GitHub PR #123 against its target branch
superdub pr 123 --base release  # override target branch detection
superdub pr https://github.com/org/repo/pull/123
superdub --all            # review all source files in the project
superdub --path ../repo   # review another folder
superdub --provider openai
superdub --model gpt-4.1-mini
superdub --include .vue,.svelte,.prompt
superdub --concurrency 4  # run more AI batches in parallel
superdub --no-cache       # ignore the local annotation cache
superdub --eager-lines    # generate Translate mode before you open it
superdub --port 7778      # choose a server port
superdub --max-files 8    # limit files, useful outside git repos
superdub --no-open        # do not open a browser

Speed

Superdub is optimized to show useful review context quickly:

• Block annotations are generated first, so the default Annotate view becomes useful before line translations exist.
• Translate mode is lazy. Line-by-line English is generated for the current file only when you open Translate.
• Repeated chunks are cached by provider, prompt version, and code hash in .superdub/cache.json.
• Batches run in parallel by default. Increase or reduce this with --concurrency.
• Import-only, re-export-only, comment-only, and structural-only changes are skipped before they reach the AI provider.

For the fastest repeat runs:

superdub --concurrency 4

For a fully populated artifact, including Translate mode:

superdub --eager-lines

File Selection

By default, Superdub reviews changed source files from git diff HEAD. Use superdub --diff main..HEAD to review a specific branch/range, or superdub --all to scan every supported source file in the project.

To review an incoming GitHub pull request, run:

superdub pr 123

Superdub asks GitHub for the PR's target branch, fetches that branch into refs/remotes/origin/<target>, fetches the PR into refs/superdub/pr-123, and reviews origin/<target>...refs/superdub/pr-123. It does not check out the PR branch or change your working tree. For private repos, set GITHUB_TOKEN or GH_TOKEN so Superdub can read PR metadata, and make sure your local git fetch origin already has access.

Use --base <branch> only when you need to override target branch detection:

superdub pr 123 --base release

Superdub recognizes common app, systems, scripting, SQL, config, and web component languages out of the box. For generated or unusual file types, add extensions explicitly:

superdub --all --include .prompt,.rules,.agent

Local Development

From this repo:

node ./bin/dub.js --no-open

Privacy

Superdub runs locally and only sends changed code chunks to the AI provider you configure for annotation. It does not require a login, include hidden telemetry, or upload your repo to a Superdub server. The local cache stays in your repo under .superdub/cache.json.

Usage Tracking

Superdub does not include hidden telemetry. Package adoption is tracked through public npm downloads, and product interest is best tracked through GitHub stars, forks, issues, and traffic insights.