A code reviewer that never leaves your laptop

Be honest about what this will and will not do

Start here, because a reviewer you over-trust is worse than no reviewer. A model you can run on a laptop is not as good at code review as the largest cloud models, and it is not close. It will miss subtle bugs. It will occasionally object to code that is correct.

What it is genuinely good at is the tedious half of review: a variable used before assignment, an error swallowed silently, a function that grew a fourth responsibility, a test that asserts nothing. And it has three properties the better reviewer does not — it costs nothing per run, it works on an aeroplane, and it will look at code you are contractually forbidden from uploading. That combination is the reason to build it.

Aim it at the tedious half deliberately. A reviewer asked for everything gives you a wall of text you stop reading by Thursday.

Get the diff, and the context around it

A diff alone is a poor thing to review. It shows the lines that changed and nothing about what they changed. A reviewer who cannot see the function a line sits in will comment on style, because style is all that is visible.

So gather two things: the diff, and enough of each changed file to make it meaningful. The trade-off is context budget — the more surrounding code you send, the less room there is for the model to think, and on a local model that budget is tight.

import subprocess
from dataclasses import dataclass


@dataclass
class Change:
    path: str
    diff: str


def run(args: list[str]) -> str:
    result = subprocess.run(args, capture_output=True, text=True)
    if result.returncode != 0:
        raise RuntimeError(result.stderr.strip() or " ".join(args))
    return result.stdout


def staged_changes() -> list[Change]:
    """One entry per changed file. Reviewing file by file rather than all at
    once keeps each request inside the context window and stops a large
    change from crowding out a small important one."""
    names = run(["git", "diff", "--cached", "--name-only"]).split()
    changes = []
    for path in names:
        diff = run(["git", "diff", "--cached", "--unified=8", "--", path])
        if diff.strip():
            changes.append(Change(path=path, diff=diff))
    return changes

git add -p && python -c "from gather import staged_changes; [print(c.path, len(c.diff)) for c in staged_changes()]"

Ask for the tedious half, specifically

The instruction is where this project is won or lost. Ask a model to "review this code" and you get a summary of what the code does, two style opinions, and a compliment. None of those help.

Ask for specific categories of defect, demand a file and line for each, and give it explicit permission to find nothing. That last part matters more than it sounds: a model that cannot say "this looks fine" will manufacture an objection on every clean diff, and a reviewer that cries wolf on every commit gets turned off within a week.

from openai import OpenAI

from gather import Change

client = OpenAI(base_url="http://127.0.0.1:8081/v1", api_key="not-needed")
MODEL = client.models.list().data[0].id

JOB = """You review a single file's staged diff before it is committed.

Look for these, in this order:
1. Bugs: wrong logic, off-by-one, a variable used before it is set, a case
   the change does not handle, an error caught and silently discarded.
2. Things left behind: debugging output, commented-out code, a TODO written
   in this diff, a hard-coded value that should not be hard-coded.
3. Tests: a behaviour changed with no test touched, or a test that asserts
   nothing meaningful.

Ignore formatting, naming and style entirely. A formatter handles those.

For each finding write one line:
  path:line  what is wrong, in one sentence

If the diff has none of these problems, reply with exactly: LOOKS FINE
Do not invent a finding to seem useful. A clean diff is a normal outcome."""


def review(change: Change) -> str:
    reply = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": JOB},
            {"role": "user", "content": f"File: {change.path}\n\n{change.diff}"},
        ],
        temperature=0.1,
    )
    return reply.choices[0].message.content.strip()

python -c "from gather import staged_changes; from review import review; c = staged_changes()[0]; print(review(c))"

Make it feel fast

A local model reviewing a large diff takes a while, and a silent terminal for forty seconds feels broken even when it is working. Streaming does not make it faster; it makes the waiting legible, and that is the difference between a tool you use and one you abandon.

This is also the cheapest possible lesson in why local feels different. The first token arrives quickly; it is the last one that takes time. Showing the first changes the experience entirely.

def review_streaming(change: Change) -> str:
    stream = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": JOB},
            {"role": "user", "content": f"File: {change.path}\n\n{change.diff}"},
        ],
        temperature=0.1,
        stream=True,
    )
    collected = []
    for piece in stream:
        token = piece.choices[0].delta.content or ""
        print(token, end="", flush=True)
        collected.append(token)
    print()
    return "".join(collected).strip()

Wire it into the way you actually work

The finished tool: every staged file reviewed, findings printed under a heading, a non-zero exit code when something was found so it can sit in a pre-commit hook if you want it to.

Make the exit code a choice rather than a default. A reviewer that blocks your commit on a false positive is a reviewer you will disable, and you want this one advisory until you trust it.

import argparse
import sys

import httpx

from gather import staged_changes
from review import review, review_streaming


def main() -> int:
    parser = argparse.ArgumentParser(description="Review staged changes locally.")
    parser.add_argument("--strict", action="store_true",
                        help="exit non-zero when anything is found")
    parser.add_argument("--quiet", action="store_true",
                        help="do not stream; print each review when it is done")
    args = parser.parse_args()

    try:
        changes = staged_changes()
    except RuntimeError as err:
        print(f"git: {err}", file=sys.stderr)
        return 2

    if not changes:
        print("nothing staged")
        return 0

    findings = 0
    for change in changes:
        print(f"\n=== {change.path} " + "=" * max(0, 60 - len(change.path)))
        try:
            result = review(change) if args.quiet else review_streaming(change)
        except (httpx.ConnectError, httpx.ReadTimeout):
            print("Could not reach a model at http://127.0.0.1:8081/v1 — "
                  "open Pip and start a text server.", file=sys.stderr)
            return 2
        if args.quiet:
            print(result)
        if "LOOKS FINE" not in result.upper():
            findings += 1

    print(f"\n{findings} of {len(changes)} files had findings")
    return 1 if (args.strict and findings) else 0


if __name__ == "__main__":
    sys.exit(main())

python cli.py && echo "exit $?"

Now build it again, with the other agent

This is the step that justifies the project sitting at the end of the course. You have built this by hand, or with one agent. Now give the same instruction to the other one — Codex if you used Claude Code, Claude Code if you used Codex — in an empty folder, and read both results side by side.

What you are looking for is not which is better. It is what each one assumed when you did not tell it. One will stream and the other will not. One will review the whole diff at once and blow the context window on a large change; the other will go file by file. One will add a pre-commit hook you did not ask for. Those assumptions are exactly what you need to learn to spot, because they are what you will be reviewing for the rest of your working life.

• Did it review file by file, or send everything in one request?
• Did it handle the local server being down, or does it throw?
• Did it give the model permission to find nothing?
• Did it hard-code a model name instead of asking /v1/models?
• Did it reach for a cloud API anywhere, despite the instruction?
• Which one would you rather maintain in six months?