fresh-eyes 0.3.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

Export your Gemini API key (get one at https://aistudio.google.com/apikey):

export GEMINI_API_KEY=your-key-here

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 file context

By default the reviewer sees only the diff hunks plus ~3 lines of surrounding context per hunk — not whole files, and no idea what the change is supposed to do. Two opt-in flags raise the signal when you need it:

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 --full-files                    # attach full post-change content of each changed file
fresh-eyes --since HEAD~3 --full-files --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 --full-files when the reviewer needs to see callers, types, or surrounding code not visible in the diff hunks.

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 marker files, no hidden state.
• 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 diff 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