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 and review state in SQLite.
• Maintains reusable checkout caches and per-review clones.
• Runs configured AI review execution through an isolated container image controller.
• Supports plugin-declared AI tool configuration 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 tool, installation, and 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 tool 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, Docker, config directories, volumes, and plain Docker usage.
• Auth Providers: bundled auth provider layout and runtime flow.
• Development: tests, type checks, frontend checks, and useful development 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: plugin-owned AI tool 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.
• Disclosures: legal disclosure inventory notes.
• 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 and review state 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 profile files are kept under:

~/.config/codesnuffler/plugin-auth

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

The old CODESNUFFLER_CONFIG_DIR and CODESNUFFLER_CONFIG names are removed, not deprecated aliases.

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/bare.
• 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 instances are plugin instances addressed by { plugin_id, instance_id }.
• AI harness auth profile state is host-backed under keyed directories: ~/.config/codesnuffler/plugin-auth/<plugin-id>/<instance-id>/<auth-storage-key>/....
• 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, and configurable plugin credentials.

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.