claude-code-reviewer

Automatically review code changes when Claude Code commits. Uses external AI CLIs (Codex, Gemini CLI) to review staged diffs before allowing git commits.

How it works

1. Claude Code runs git commit via the Bash tool
2. A PreToolUse hook fires and calls claude-code-reviewer hook
3. The hook checks if the command is a git commit
4. git diff --staged retrieves the staged changes
5. An external AI (Codex or Gemini CLI) reviews the diff
6. LGTM → commit proceeds / Issues found → commit is blocked with feedback

⚠️ Privacy Notice

Staged diffs are sent to external AI services for review. Be mindful of sensitive information (API keys, credentials, proprietary code) in your staged changes. Consider using a local AI adapter (e.g., Ollama) for sensitive codebases.

Requirements

• Node.js >= 18
• Claude Code CLI
• At least one of:
  • Codex CLI (npm i -g @openai/codex)
  • Gemini CLI (npm i -g @google/gemini-cli)

Installation

npm install -g claude-code-reviewer

Setup

Register the PreToolUse hook in Claude Code settings:

claude-code-reviewer setup

This adds a Bash matcher hook to ~/.claude/settings.json.

Teardown

Remove the hook:

claude-code-reviewer teardown

Configuration

Configuration is stored in ~/.claude-code-reviewer.json.

# Show current config
claude-code-reviewer config show

# Set adapter
claude-code-reviewer config set adapter gemini

# Set model
claude-code-reviewer config set codex.model o3
claude-code-reviewer config set gemini.model gemini-2.5-pro

# Set max review cycles before auto-allow
claude-code-reviewer config set maxReviews 3

# Set error policy (allow or deny commit on AI failure)
claude-code-reviewer config set onError allow

# Set max diff lines to review (larger diffs are truncated)
claude-code-reviewer config set maxDiffLines 1000

# Set timeout in seconds
claude-code-reviewer config set timeout 120

# Add custom review instructions
claude-code-reviewer config set prompt "Focus on security and error handling"

Default Configuration

| Key | Default | Description | |-----|---------|-------------| | adapter | "codex" | AI adapter to use ("codex" or "gemini") | | maxReviews | 2 | Max review cycles before auto-allowing | | maxDiffLines | 1000 | Max diff lines to send for review (truncates larger diffs) | | onError | "allow" | What to do when AI review fails ("allow" or "deny") | | timeout | 120 | Timeout in seconds for AI review | | prompt | "" | Custom review instructions | | codex.model | "" | Codex model (empty = default) | | codex.sandbox | "read-only" | Codex sandbox mode | | gemini.model | "" | Gemini model (empty = default) |

Manual Review

Review currently staged changes without going through the hook:

git add .
claude-code-reviewer review

How the Hook Works

The hook intercepts Bash tool calls in Claude Code. When a git commit command is detected:

1. Runs git diff --staged to get the changes
2. If the diff exceeds maxDiffLines, it's truncated with a note
3. Sends the diff to the configured AI adapter with code review criteria
4. LGTM response → allows the commit
5. Issues found → blocks the commit and returns feedback to Claude Code
6. Claude Code receives the feedback and can fix issues before retrying

Review Criteria

The AI reviewer checks for:

• Bugs — logic errors, off-by-one, incorrect behavior
• Security — injection, XSS, SSRF, etc.
• Performance — bottlenecks, inefficiencies
• Code style — naming, readability, consistency
• Edge cases — unhandled boundaries
• Error handling — failure modes
• Resource management — files, connections, memory

Prompt Injection Protection

The diff content is wrapped in <CODE_DIFF> tags with explicit instructions to treat it as data, not instructions.

License

MIT