DEV Community

Mukund Jha
Mukund Jha

Posted on

I built a Python code reviewer that only reviews the code you changed

#python #devtools #codequality #showdev

I used to pay for an AI code reviewer. The trial was great — it caught a race condition I'd spent an afternoon chasing. Then the invoice came, and the reality: $29/month, my code uploaded to someone else's servers, and half the report lecturing me about a legacy module the previous dev left behind. The code I actually wrote got buried.

So I canceled it and wrote my own.

Avouch is a free, local, Git-aware code reviewer for Python. It asks git which files your next commit will touch, parses only those with the standard ast module, and reports structural problems against limits you configure in avouch.toml.

pip install avouch
cd your-repo
avouch

The core idea: the review set is the diff, not the repository. Avouch reviews git diff HEAD plus untracked files. PASSED ✓ util.py means that file is clean right now — not "passing because the linter is reviewing 500 files you never touched."

What it checks

17 rules, measured from the AST, not regex:

  • SCR002 — bare except: handlers
  • SCR014 — too many parameters (def connect(host, port, user, password, db, timeout) → 6/5)
  • SCR017 — mutable default arguments (def add_item(item, items=[]))
  • SCR013 — nesting depth (a with → for → if → try chain 5 deep gets flagged)
  • Cyclomatic complexity on functions and classes

If a metric can't be computed exactly from the AST, avouch doesn't claim it.

Design choices

  • It reviews; it doesn't gate. Exit code 0 = clean, 1 = findings, 2 = tool error. Enforcement belongs in a hook or CI, not in the tool itself.
  • No daemon, no network, stdlib only. Three git subprocess calls and the standard library. Runtime is bounded by your diff, not your repository.
  • Machine-readable by contract. avouch --json prints a stable, versioned document — no colors or timestamps leak into it, so automation can depend on it.

Honest limits

No autofix (yet), no plugin system, config is CWD-local. The roadmap covers baselines, parallel review, and CI-native output formats.

It's not competing with Ruff on rules, and it's not competing with AI reviewers on judgment. It answers one question in the seconds before git push: is what I'm about to push structurally sound?

Install: pip install avouch (Python 3.10+, stdlib only) · GitHub (https://github.com/mukundzha/avouch) (MIT)

Written by Mukund — I'd love feedback from solo devs who've felt the same way about their own review setups.

Top comments (0)