fresh-eyes 0.5.0

Independent AI peer review of git diffs for Claude Code and other coding agents

fresh-eyes

Independent AI peer review of git diffs, designed for use alongside Claude Code (or any coding agent). Sends your latest changes to a different model so you get a second opinion with different blind spots from the one that wrote the code.

Install

uv tool install fresh-eyes

Or from a local checkout:

uv tool install --from . fresh-eyes

This installs two equivalent commands: fresh-eyes (canonical) and fe (typeable alias).

Setup

fresh-eyes calls three independent reviewers (Gemini, Mistral, DeepSeek). Export a key for each one you want to use — the tool runs whichever providers have keys set. At least one is required.

export GEMINI_API_KEY=your-key-here       # https://aistudio.google.com/apikey  (free tier)
export MISTRAL_API_KEY=your-key-here      # https://console.mistral.ai          (paid)
export DEEPSEEK_API_KEY=your-key-here     # https://platform.deepseek.com       (paid)

Reviewer selection

• Whichever *_API_KEY env vars are set decides which reviewers run. Set all three for the strongest review (different blind spots compound); set one for a quick check.
• --only <gemini|mistral|deepseek> runs a single reviewer for the current invocation, even if other keys are set.
• Override the default model for any reviewer with FRESH_EYES_GEMINI_MODEL, FRESH_EYES_MISTRAL_MODEL, or FRESH_EYES_DEEPSEEK_MODEL.

Activation

fresh-eyes is opt-in per repo, so it doesn't fire in every git repo you cd into. Enable it once per repo:

fresh-eyes --init      # enables fresh-eyes in this repo (writes .git/fresh_eyes_enabled)
fresh-eyes --disable   # disables it again

Running any other command in a non-activated repo prints a friendly message and exits without making API calls.

Usage

From inside an activated git repository:

fresh-eyes                      # review the last commit (HEAD~1..HEAD)
fresh-eyes --since HEAD~3       # review the last 3 commits
fresh-eyes --since abc1234      # review since a specific commit
fresh-eyes --since main         # review everything on this branch since it diverged from main
fresh-eyes --full               # shortcut: diff entire branch against the default branch
fresh-eyes --all                # one-time baseline: review the entire current codebase
fresh-eyes --staged             # review staged-but-uncommitted changes

fe is the short alias — fe --since HEAD~3 works identically.

--since accepts anything git rev-parse resolves: SHAs, branch names, tags, HEAD~N. This is how Claude Code can scope a review around the actual unit of work rather than a fixed window.

Adding intent and trimming context

By default the reviewer sees the diff hunks and the full post-change content of every changed file, so it can see callers, types, and surrounding code without hallucinating about what's outside the hunk. What it does not know is what the change is supposed to do — pass --context for that.

fresh-eyes --context "Adds rate limiting to the /login endpoint. Should reject >5 req/min per IP."
fresh-eyes --context-file SPEC.md          # read intent from a file (relative to CWD)
fresh-eyes --diff-only                     # send only diff hunks, skip full files (trim tokens)
fresh-eyes --since HEAD~3 --context "Refactors auth to use the new token store"

Use --context to tell the reviewer the author's stated goal — the prompt asks it to use this for grading "does the diff do what the author claims?" while still surfacing out-of-scope issues. Use --diff-only to drop the full-file attachments when you know the diff is self-contained or the changed files are very large (cuts token cost on paid providers).

Claude Code integration

Copy the slash command files from this repo into your Claude Code commands directory:

cp commands/fresh-eyes.md commands/fe.md ~/.claude/commands/

You can now invoke /fresh-eyes or /fe in a Claude Code session. The command tells Claude to run the CLI (forwarding flags like --since HEAD~3 when the request implies a specific baseline), read its output, synthesize the findings against the current task context, and raise genuine concerns before continuing.

How it works

• Stateless: every invocation is explicit about scope. Default is the last commit; pass --since <commit> for anything else. No review-history markers, no hidden state about previous runs.
• One model per run today (Gemini 2.5 Flash). The output is emitted under a ## Gemini 2.5 Flash header so a future second reviewer can be added without changing the format.
• Noise filtering: lockfiles, minified assets, and dist//build/ are excluded from the diff so they don't burn tokens.
• Size guard: bails out with a message (exit 0) if the assembled prompt (diff + optional intent + optional full files) exceeds ~100k estimated tokens.

Exit codes

Code	Meaning
0	Review ran successfully, OR diff was too large to send (the tool reports; it does not gate)
1	--since commit not found, or other git error
2	Missing/invalid GEMINI_API_KEY

License

MIT