gatehouse

Local AI code review using 8 concurrent Gemini agents. 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 gemini-2.5-pro

# 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.

The review is advisory by default: findings post as PR comments and the check always passes, 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.2.0
with:
  blocking: true

Configuration

Set GEMINI_API_KEY environment variable. If .gemini/styleguide.md exists in the reviewed project, it is injected as context.

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