CodeSnuffler

CodeSnuffler is a self-hosted pull request review service for teams that want AI-assisted review to run under their own repository, credential, and runner policy.

It connects to Git providers, tracks repositories, installs repository webhooks, receives pull request events, prepares isolated checkout artifacts, runs configured AI reviews through managed runner workspaces, and publishes review updates back to the provider where the provider supports it.

Status: active alpha implementation. The current product is centered on local and self-hosted development.

What It Does

• Tracks provider connections and repositories.
• Reconciles provider webhooks for pull request events.
• Records webhook deliveries, review results, and durable review jobs in SQLite.
• Maintains reusable checkout caches and per-review clones.
• Runs configured AI review execution through an isolated container image controller.
• Supports configured AI harness plugin instances for bundled Codex, OpenCode, Claude Code, Gemini CLI, Pi, and future AI harness plugins.
• Serves a FastAPI JSON API and the Vue application from one container.
• Exposes review, checkout, repository, provider, webhook, AI harness, runner, plugin, startup checklist, installation, and split Settings views in the frontend.

CodeSnuffler is not just a prompt wrapper. It keeps durable review records, checkout state, webhook state, provider capability evidence, runner artifacts, and AI review policy so review work can be inspected, restored, rerun, or published deliberately.

Architecture At A Glance

The default runtime is a Docker Compose application with two first-class services:

• FastAPI serves the API and built Vue frontend.
• RQ workers process review, comment, check, and patch jobs.
• Valkey backs the queues and is bound inside the container.
• SQLite stores durable application state.
• A separate container image controller service builds Tool Container images and launches isolated AI harness plugin execution through Docker.
• Docker volumes and host-mounted config separate durable data, runner workspaces, and secret credentials.

FastAPI is exposed to the host on port 8000 by default. The local Compose stack also exposes the container image controller on its configured development port so build and runner diagnostics can be inspected while developing.

Quick Start

Prerequisites:

• Docker Desktop or Docker Engine with Compose.
• make.
• jq for the endpoint check commands.

Run the app:

make up

Then open:

http://localhost:8000/

Check the service:

curl http://localhost:8000/healthz | jq
curl http://localhost:8000/readyz | jq
curl http://localhost:8000/api/instance | jq
curl http://localhost:8000/api/repositories | jq
curl http://localhost:8000/api/ai-tools/instances/codex/primary | jq

Run another worktree or version on a different host port:

make up 8001
make down 8001

For setup details, see Quick Start and Installation.

Documentation

• Quick Start: run the app locally and verify it.
• Docs Index: the documentation landing page.
• Installation: Simple, Clerk, and LDAP setup, the supported Make/Compose runtime, config directories, volumes, and app-only Plain Docker notes.
• Production Deployment: recommended single-VPS architecture, production-readiness gates, deployment phases, backups, upgrades, and the path beyond local .codesnuffler state.
• Auth Providers: bundled auth provider layout and runtime flow.
• Development: tests, type checks, frontend checks, dev seeds, live-provider lanes, and useful development commands.
• Operations Console: a small TUI for common local, update, test, release, deployment, and diagnostic commands.
• Webhook Tunnels And Proxying: expose local CodeSnuffler routes through Cloudflare Tunnel for provider webhooks.
• Storage And Restore: checkout caches, review clones, runner workspaces, cleanup, restore, and rerun behavior.
• AI Tools: AI harness plugin instance setup, auth storage, runner workspaces, and update notes.
• AI Tool Plugin Contract: the single-source-of-truth contract for AI harness plugins.
• API Endpoints: commonly used HTTP routes.
• Plugin Sources: plugin catalog, AI harness manifests, and tool package model.
• Frontend Disclosure Inventory: current expandable UI surfaces, shared primitives, and standardization backlog.
• Project State: current implementation shape and forward plan.
• Backend Architecture: package ownership and backend flow.

Main Product Flow

1. Configure a provider connection.
2. Add credentials for provider API access.
3. Import and track a repository.
4. Set up or reconcile the repository webhook.
5. Receive a pull request webhook event.
6. Register or update a CodeSnuffler review.
7. Prepare checkout cache, review clone, diff, and artifacts.
8. Run configured AI review execution through an isolated runner.
9. Inspect findings, result outcome, latest job phase, and checkout readiness in CodeSnuffler.
10. Publish supported review updates back to the provider.

Configuration

Host-side CodeSnuffler config defaults to:

~/.config/codesnuffler

The app container mounts that directory at:

/config/codesnuffler

Basic installation settings live in:

~/.config/codesnuffler/config.toml

Durable AI harness auth runtime files are kept under:

~/.config/codesnuffler/plugin-auth

Stable development credential profiles saved from verified tool auth state are kept under:

~/.config/codesnuffler/tool-auth-profiles

Set CODESNUFFLER_CONFIG_HOST_DIR before running make up to use a different host-side config tree.

For local Docker stacks, the config directory is selected in this order:

1. Explicit CODESNUFFLER_CONFIG_HOST_DIR
2. .codesnuffler-instance.toml config_file
3. Existing ./.config/config.toml in the worktree root
4. Compose fallback to ~/.config/codesnuffler

Current Implementation Notes

• SQLite is stored at /data/reviews.db.
• Valkey append-only data is stored under /data/valkey.
• Checkout caches live under /data/repos/cache.
• Per-review clones live under /data/clones.
• Review artifacts live under /data/artifacts/reviews.
• Runner workspaces are disposable and live under /runner-workspaces.
• AI harness plugin instances are plugin instances addressed by { plugin_id, instance_id }.
• AI harness auth runtime state is host-backed under keyed directories: ~/.config/codesnuffler/plugin-auth/<plugin-id>/<instance-id>/<auth-storage-key>/....
• Saved development credential profiles are host-backed under stable directories: ~/.config/codesnuffler/tool-auth-profiles/<tool-id>/<profile-id>/....
• Generic plugin secrets are host-backed under ~/.config/codesnuffler/secrets/plugins/<plugin-id>/<instance-id>/....
• Non-secret AI harness runtime state lives under /plugin_data/<plugin-id>/<instance-id>/....
• Tool-auth containers mount those keyed directories at each CLI's native auth paths during setup and probes.
• Runner workspaces receive disposable copies of the native auth/config paths; durable plugin-auth roots are not mounted into review runner containers.

For the fuller storage model, see Storage And Restore.

Project Status

CodeSnuffler is in active alpha. It already supports provider configuration, repository tracking, webhook ingestion, review registration, checkout preparation, plugin-backed runner recipes, configured AI review execution, runner artifacts, review findings, provider comment paths where supported, scoped RBAC, automation API keys, configurable plugin credentials, startup onboarding, development seeds, and Bitbucket/Forgejo live-provider review lanes.

Near-term work is focused on completing provider publication reliability, inline comment behavior, review policy inheritance, capability evidence, checkout and runner restore flows, and broader automated test coverage.

For detailed current state, see Project State.