vouch

The code review AI coders need.

A Go CLI that catches the kinds of mistakes AI coding tools make silently. Drops into pre-commit or CI. Vendor-neutral — works with Claude, Cursor, Copilot, anything that writes code.

What it catches today

• Undefined symbols and methods. NewGreeter() when no such constructor exists; g.Greet() when the method is actually Hello. The compiler will reject these eventually; vouch surfaces them at review time, scoped to the diff.
• Arity and type mismatches at call sites.
• Inconsistent receiver names. (s *Server) here, (srv *Server) over there — a tell that methods were written in separate turns.
• Unimplemented stubs. panic("not implemented"), errors.New("TODO: wire this up"), log.Fatal("implement me"). Compiles fine; reviewers miss them.

Each is its own check; you can disable them individually.

30-second install

go install github.com/c-tonneslan/vouch/cmd/vouch@latest

# every available check, one per line
vouch list

# run on the current package
vouch check

# only flag findings on lines this PR touches
vouch check --diff origin/main

# machine-readable
vouch check --format json

Exit codes: 0 clean, 1 findings present, 2 tool error.

Write your own check

The public API is the checker package. A check is a Go value satisfying the Checker interface, registered at package-init:

package mycheck

import "github.com/c-tonneslan/vouch/checker"

type Check struct{}

func (Check) Name() string        { return "console-leftover" }
func (Check) Description() string { return "Flags console.* added to JS/TS." }

func (Check) Check(ctx checker.Context) ([]checker.Finding, error) {
    // Walk ctx.Path, find issues, filter by ctx.Diff.Contains(file, line).
    return nil, nil
}

func init() {
    checker.Register(Check{})
}

That's the whole contract — one interface, three methods. Importing the package adds the check to the global registry. To build a custom vouch binary with extra checks, import them alongside the in-tree ones in cmd/vouch/main.go — same pattern as golangci-lint plugins.

A complete worked example lives at checker/example_test.go.

Integrations

GitHub Actions. A composite action ships in action.yml:

- uses: c-tonneslan/vouch@v1
  with:
    path: .
    # diff: origin/main         # override the auto-detected base
    # fail-on-finding: "false"  # annotate without failing the job

Findings render as inline annotations on the PR's Files Changed tab. No PR-comment spam.

--format sarif emits SARIF 2.1.0 if you'd rather feed vouch into GitHub code scanning. Pipe it to a file and pass that to github/codeql-action/upload-sarif.

Pre-commit. Run vouch install-hook in any git repo to drop a pre-commit script that calls vouch check --diff HEAD on the staged change. Honors core.hooksPath so it lands in the right place under husky / pre-commit / monorepo setups. --force overwrites an existing hook.

Try it

Toy fixtures live under testdata/:

vouch check ./testdata/hallucination/sample

main.go:21:16  [hallucination/undefined-method]  g.Greet undefined (type Greeter has no field or method Greet)
main.go:24:8   [hallucination/undefined-symbol]  undefined: NewGreeter
main.go:28:31  [hallucination/arity-mismatch]    too many arguments in call to Welcome

3 finding(s)

vouch check ./testdata/stub/sample

store.go:19:8   [stub/unimplemented]  panic left as a placeholder: "not implemented"
store.go:24:20  [stub/unimplemented]  errors.New left as a placeholder: "unimplemented"

2 finding(s)

Why vouch and not go build or semgrep?

• go build reports every error in the tree. vouch classifies the AI-tell ones, scopes to the diff, and runs alongside checks that aren't about compilation at all (stubs, receiver naming).
• Semgrep is a great general pattern-matcher. vouch is git-aware: it knows what changed, what the file looked like before, what the surrounding code was. The checks here are about the kind of mistake AI makes, not pattern-matching arbitrary code.

The story

The post-mortem that started this project: docs/why.md.

Roadmap

The issue tracker is the source of truth. Broad direction:

• api-shape: wrong-argument-order calls and silently-deprecated APIs via gopls
• over-mock: tests whose mocks are so complete they'd pass against an empty implementation
• refactor-residue: orphaned imports, half-renamed identifiers, dead branches
• More languages: TypeScript first
• VSCode extension that runs vouch on save

Eval

The eval harness scores vouch against real AI-authored bug fixes (precision / recall per check). The corpus is small at v1.5 and growing. See eval/README.md for how cases are sourced.

Contributing

We want your checks. The plugin API is stable; adding one is a single file and an init().

• Open an issue first if the check is substantial.
• Include a real-world example the check would catch.
• Tests, and a Description() that reads like a sentence.
• We won't merge AI-generated PRs that aren't disclosed.

See CONTRIBUTING.md.

License

MIT. See LICENSE.