gatehouse

Local AI code review using 8 concurrent LLM agents, called through OpenRouter. Inspired by diffray's multi-agent architecture and anti-noise prompting.

Install

uv tool install gatehouse-crunchtools

Usage

# Review current branch vs main
gatehouse

# Review staged changes only
gatehouse --staged

# Review against a specific base
gatehouse --base develop

# Run specific agents only
gatehouse --agents bugs,security

# Use a different model
gatehouse --model google/gemini-3.8-flash

# Advisory mode (never exit non-zero)
gatehouse --advisory

Agents

All 8 agents run concurrently. Findings below 80% confidence are filtered out.

How Agents See Changes

Since v0.3.0, agents do not receive raw unified diffs. Each hunk is rendered as a structured view: a BEFORE block (the old code, removed lines marked [-]) and an AFTER block (the new code with real file line numbers, added lines marked [+]), plus instructions to judge the direction of a change. Protections added by a change are treated as fixes, not findings; protections removed by a change are flagged. Diffs that cannot be parsed fall back to the raw unified format.

Exit Codes

GitHub Actions

Drop in examples/gatehouse.yml to review every PR (forks included) via the reusable review.yml workflow — the diff is piped as data, never checked out or executed.

Add examples/gatehouse-retriage.yml as well if Gatehouse triage is a required check. A reply to a finding starts a run whose checks branch rules ignore; the retriage workflow re-runs triage inside the pull_request_target run, where the result counts.

The review is advisory by default: findings post as PR comments and the check always passes (an agent that could not finish is named in the review instead of failing it), so a non-deterministic LLM finding can never block a merge. Do not mark it a required status check. To let critical/high findings fail the check (still not recommended as a required gate), opt in:

uses: crunchtools/gatehouse/.github/workflows/review.yml@v0.12.0
with:
  blocking: true

Configuration

Set OPENROUTER_API_KEY, or OPENROUTER_API_KEY_FILE pointing at a file that holds the key (the file wins when both are set). Either can live in ~/.config/mcp-env/gatehouse.env. If .gemini/styleguide.md exists in the reviewed project, it is injected as context.

Ignoring files

List paths that should never be reviewed in .gatehouse-ignore at the repo root, in gitignore syntax (*, **, trailing /, ! negation). Their diff sections and file-listing entries are dropped before any agent sees them, so data files, fixtures, lockfiles and generated output stop costing tokens. A change is skipped only when every path it touches is ignored, so a rename out of an ignored directory is still reviewed, and so is any change to .gatehouse-ignore itself.

uv.lock
tests/fixtures/
*.fp

In CI the file is read from the base branch, like the styleguide and constitution: a pull request cannot widen it to hide its own changes. The posted review says how many files were skipped; when every changed file is ignored, gatehouse prints No changes to review., exits 0 and posts nothing.

Model

The default model is openai/gpt-6-luna, with google/gemini-3.1-flash-lite as an automatic fallback when it is rate-limited or down. Every request requires zero data retention and forbids training on prompts, so only providers that keep nothing may serve it. --model takes any OpenRouter slug; the fallback still applies.

Luna was chosen on a 33-diff replay of real crunchtools changes (see crunchtools RT #1505): it caught as many reintroduced bugs as gemini-2.5-flash, with far less noise on clean PRs, at about a sixth of the cost.

Upgrading from 0.8.x: gatehouse no longer reads GEMINI_API_KEY. Replace it with OPENROUTER_API_KEY in your env file and GitHub secrets.

Constitution Discovery

The Constitution agent auto-discovers a project constitution in priority order:

1. --constitution <path> (explicit override)
2. .specify/memory/constitution.md (spec-kit)
3. AGENTS.md (cross-runtime standard)
4. CLAUDE.md (Anthropic project instructions)

If no constitution file is found, the agent is silently skipped.

License

AGPL-3.0-or-later