AICodeReviewer

AICodeReviewer (AICR) is a self-hosted service that orchestrates AI code review across your version-control systems. It normalizes webhooks and triggers into one review pipeline, runs the agent CLI of your choice inside a locked-down sandbox, and routes structured findings back to pull-request comments, managed issues, or IM bots. Free-form agent stdout never becomes the report.

What AICR does

Structured report contract

Agents report findings through a fixed MCP tool set. AICR validates, deduplicates, and renders them. Free-form agent stdout never becomes the report.

Multiple agents

Kilo Code, Claude Code, opencode, Zoo Code, and Copilot CLI share one runtime contract. Switch agents without rewriting your pipeline.

Multiple VCS

GitHub, Gitea, Forgejo, and GitLab over webhooks; Perforce and Subversion over triggers. All normalized into a single ReviewEvent.

Safe by default

Scoped fetch of only changed files, read-only source mounts, allowlisted sandbox commands, secret scrubbing at every boundary, and hard timeouts.

Cost & context control

Automatic diff compression, per-run budget caps, LLM fallback chains, and a dashboard that tracks tokens and cost per project and provider.

Self-hosted, single container

Server, queue worker, orchestrator, dashboard, and database run in one process. Deploy with docker run or podman run.

How it works

1. A webhook or trigger arrives from your VCS (push, PR, or a manual /aicr review command). AICR validates the request against your configured HMAC secret or API key.

2. The VCS adapter fetches changes. Only the changed files are pulled — scoped fetch, not a full clone. For PRs the merge-base diff is computed; for P4 and SVN the changelist or revision diff.

3. Diff compression kicks in when the change set is too large for the model’s context window. AICR keeps the most relevant hunks and trims the rest.

4. The agent runs in a sandbox. Your chosen agent CLI executes inside a Docker or Podman container with the diff, your AI instructions, and the stable MCP tool set — with read-only source mounts, allowlisted commands, and a hard timeout that cleans up the whole process tree.

5. Structured findings are routed. Problems become PR line comments (with code context), managed issues (with lifecycle tracking and auto-close on fix), or IM summary cards (Feishu/WeCom with proper rendering). The same aicr.report_problem call drives all three.

Key features

• One pipeline, many VCS. GitHub, Gitea, Forgejo, and GitLab arrive over webhooks; Perforce (P4) and Subversion (SVN) arrive over trigger endpoints. All are normalized into one ReviewEvent.
• Multiple agents. Kilo Code, Claude Code, opencode, Zoo Code, and Copilot CLI share one runtime contract. AICR translates ModelSpec into each tool’s native fields and records capability downgrades in the run manifest instead of silently dropping them.
• Structured report contract. Agents emit findings through a fixed MCP tool set (aicr.report_problem, aicr.publish_summary, aicr.skip, aicr.fetch_more_context, aicr.try_blame). The same problem renders as a PR line comment, a managed issue, or an IM summary card.
• Safe by default. Scoped VCS fetch (only changed files), read-only source mounts, allowlisted sandbox commands, secret scrubbing at every boundary, whole-process-tree timeout cleanup, and --init zombie reaping in the service container.
• Context-aware compression. Large diffs are compressed before they hit the model’s context window. Per-model override thresholds let you tune compression per provider without changing the review pipeline.
• Managed problem lifecycle. Problems are tracked across runs with stable fingerprints. When a file is re-reviewed and a problem is gone, its managed issue is auto-closed. A file-scope guard keeps reviews that didn’t touch a file from closing its issues.
• Built-in observability. Dashboard with per-project stats, per-run token and cost breakdowns, provider-level LLM usage, daily rollups, and a /metrics endpoint for Prometheus scraping.
• Retry and fallback. Queue-level retry with exponential backoff. LLM fallback chains route to the next provider when the primary fails or throttles.

Supported integrations

Surface	Options
VCS providers	GitHub, Gitea, Forgejo, GitLab (webhooks); Perforce (P4), Subversion (SVN) (triggers)
Agent CLIs	Kilo Code, Claude Code, opencode, Zoo Code, Copilot CLI
Output channels	PR/MR line comments & summary, managed problem issues, Feishu bot, WeCom bot
Sandboxes	native, docker, podman, docker_socket (k8s_pod, firecracker reserved)
Model providers	Any OpenAI-compatible API; models.dev catalog for context window and pricing metadata

Review output standards

Every finding follows one contract, so reports stay consistent no matter which agent produced them or which channel renders them. A problem always carries a severity, a category, a file path, a line range, and a human-readable message (with an optional fix suggestion).

Severity is a fixed five-level scale, so downstream routing and triage are predictable:

Severity	Meaning
critical	Must fix before merge — data loss, security breach, crash, or corruption
high	Likely bug or vulnerability with real impact under realistic conditions
medium	Correctness, contract, or performance risk worth addressing
low	Minor issue or smell; safe to defer
info	Advisory note or observation, no action required

Category groups findings into stable families such as correctness, security, performance, api-contract, and style, which keeps grouping and deduplication consistent across runs.

Reviews are precision-first: the agent reports only validated, actionable problems, and the summary frames those problems instead of narrating everything that was checked and found fine. When nothing actionable exists, the review ends with an explicit skip instead of a praise-filled summary.

Rendering & security

Findings are rendered as proper Markdown — IM bots receive real tables and code blocks, never raw stdout. Secrets are scrubbed from prompts, logs, and every output boundary. The review prompt guides the agent over common vulnerability classes (including the OWASP Top 10).

Design principles

• Minimal assumptions. AICR normalizes VCS inputs but doesn’t guess your workflow. Skip policies, output routing, label management, and commit strategies are all configurable.
• Honest downgrades. When an agent adapter or model doesn’t support a feature (e.g., structured output, reasoning), it’s recorded in the run manifest. Nothing is silently dropped.
• Single container. The entire service — HTTP server, queue worker, agent orchestrator, dashboard, and SQLite database — runs in one process. Deploy with docker run or podman run. For more throughput, multiple worker processes can share one SQLite or Redis queue.
• Readable output. Every problem includes a severity, category, file path, line range, and human-readable message. IM bots receive properly rendered Markdown tables and code blocks. No raw agent stdout makes it into a user- facing notification.

Next steps

Quick startRun AICR locally or with Docker Compose and trigger your first review in minutes.

Authentication & secretsThe three-layer model: webhook HMAC, server API key, and per-workspace key.

LLM providers & modelsConfigure OpenAI-compatible providers, model catalogs, retry, and budget caps.

Agent & sandboxChoose an agent CLI, set timeouts, enable auto-compaction, and lock down the sandbox.

Output channels & routingThe MCP report tools, supported channel kinds, and how routing works.

Deploy to productionSingle-container Docker or Podman, reverse-proxy TLS, and persistent volumes.

The fastest path to production is a single Docker or Podman container behind a reverse proxy, fed by a GitHub or Gitea webhook. See Quick start to begin. For evaluation or contributing, the local Node.js quick start needs only pnpm install and pnpm build.