Argus.

A review is not a diff summary. It is a claim about code that someone has to verify, so every finding carries the evidence that produced it.

Local development runs the three processes directly and keeps Postgres and Redis in containers. Five commands, then a review.

# 1 — dependencies
npm install

# 2 — your settings: AUTH_SECRET is the only one with no default
cp .env.example .env

# 3 — infrastructure only (Postgres + Redis)
npm run dev:infra

# 4 — schema, then the three processes
npm run db:generate && npm run db:migrate
npm run dev            # api :4000 · worker · web :3000

Open http://localhost:3000 and sign in. The API creates the first account from BOOTSTRAP_ADMIN_EMAIL / BOOTSTRAP_ADMIN_PASSWORD the first time it boots with an empty users table.

Optional: demo data

npm run db:seed      # seeded repositories, runs and findings + admin@example.com / change-me-please

The seed adopts any account that already owns the admin email instead of failing, and never overwrites a password — reseeding cannot invalidate a real account.

One review, step by step. Every step is idempotent and streams events, so a crashed worker can be resumed.

1. Trigger — webhook (verified, deduplicated by delivery id), API call, CLI, or retry.
2. Enqueue — a ReviewRun row with an idempotency key from (repository, pull request, head sha, trigger). Three webhooks from one push produce one review.
3. Lock — a Redis lock on review:<pullRequestId> stops two workers reviewing the same pull request at once.
4. Prepare — shallow clone of the head commit into a workspace keyed by the run, plus PR metadata, commits and file list from GitHub.
5. Classify — changed files are bucketed (source, test, docs, generated, …) and the plan decides which checks are worth running.
6. Run checks — planned scripts execute in the sandbox; output is parsed into findings with real file and line anchors.
7. Agent loop — the model reads files, searches the repository, requests commands and drafts findings, bounded by budget and permissions.
8. Validate — each draft is schema-checked, deduplicated, calibrated against REVIEW_MIN_PUBLISH_CONFIDENCE and compared with the previous run. A model critique may only soften or discard — never strengthen.
9. Finalize — a verdict (passed / neutral / failed), a narrative and counts.
10. Publish — summary comment found and updated in place via an embedded marker, plus a check run with annotations — or a pending approval when the gate is on.

An npm-workspaces monorepo. The API, the worker and the CLI share one container: same dependency set, different entrypoint.

Packages

Apps

Every variable is validated in packages/config/src/env.ts. Startup fails with the list of what is wrong instead of booting half-configured, and .env.example documents all of them.

Provider presets

All four speak OpenAI Chat Completions, so tool calls and JSON mode behave identically. An explicit base URL always wins; openai-compatible has no default and needs one.

# OpenRouter
LLM_PROVIDER=openrouter
LLM_API_KEY=sk-or-...
LLM_MODEL=openai/gpt-4o
LLM_HTTP_REFERER=https://your-app.example   # optional app attribution
LLM_APP_TITLE=Argus                        # optional app attribution

# nan.builders
LLM_PROVIDER=nan-builders
LLM_API_KEY=sk-...
LLM_MODEL=glm5.3-flash

# Any other gateway, local or hosted
LLM_PROVIDER=openai-compatible
LLM_BASE_URL=https://gateway.internal/v1
LLM_MODEL=my-model

Per-repository policy

Stored in the database and editable in the dashboard or via PATCH /repositories/:id/settings. It can narrow or widen the deployment defaults inside the bounds the environment allows: which checks run, deep review, inline findings, summary comment, check run, ignored paths, minimum confidence, blocking severities, the approval gate and the agent's permission set.

A GitHub App is the full path: webhooks and installation tokens. A personal access token is the quick path: reviews without webhooks.

GitHub App (recommended)

Personal access token

A classic token with the repo scope, or a fine-grained token with Contents: read, Issues: read & write, Pull requests: read & write, Checks: read & write. Put it in GITHUB_TOKEN. It cannot receive webhooks, so reviews are triggered from the dashboard, the CLI or the API.

Local webhook testing

# expose the API (port 4000, not the web) and point the App's Webhook URL at:
#   https://<your-tunnel>/github/webhooks
cloudflared tunnel --url http://localhost:4000   # or ngrok http 4000

Saving the Webhook URL makes GitHub send a ping. A bad signature answers 401, a repeated delivery answers duplicate — that is the idempotency working, not an error. Redeliver from the App’s Advanced tab to see it.

Three doors to the same pipeline: the dashboard, the CLI, and HTTP.

Dashboard

• Repositories — every repository the platform can review, with its counts, plus Add and Sync.
• Repository detail — Trigger a review by number, the review policy, and access management.
• Pull requests — review history per PR, Sync from GitHub, Review now.
• Reviews — status, plan, usage, cost, node trace, findings, check runs, live events, approvals, SARIF export.

CLI

npm run review -- --repo owner/name --pr 42            # full review, no dashboard, no Redis
npm run review -- --repo owner/name --pr 42 --no-checks  # fastest: AI pipeline only
npm run review -- --repo owner/name --pr 42 --publish    # write the comment and check run

The first run reads the repository and the pull request straight from GitHub and records both, so a PR shows up in the dashboard without waiting for a webhook. Exit code is non-zero when the run fails, so it works as a CI step.

Everything the dashboard uses, in plain HTTP with a session cookie. Routes are not prefixed: the API is either served on its own host or routed by your ingress.

Errors are one envelope — { code, message, details, requestId } — with codes mirroring the status: validation_error, unauthorized, forbidden, not_found, conflict, internal_error. Every response carries x-request-id, which is also the key in the logs.

The model never decides what is safe. Budgets, permissions and publishing are computed from configuration, and the agent operates inside those bounds.

Sandbox modes

Workspace confinement is enforced with real paths, so a symlink cannot escape the run's directory, and the command allow-list is derived from the repository manifest — the model can request a script, not invent a command.

Prompt injection

Pull request text is untrusted input from strangers. It is wrapped in a per-request random boundary, injection signals are detected and surfaced, and the instruction hints field is the repository owner's channel, not the author's.

Cost

• Every run records tokens in, tokens out and an estimated cost, visible per run and per repository.
• Budget limits (tokens, wall clock, tool calls) stop a run instead of letting it drift; the run records that it hit the limit.
• A single surviving finding skips the adversarial critique — a deliberate cost decision, not an omission.

docker-compose.yml defines postgres, redis, migrate, api, worker and web. Four commands and the stack is up.

docker compose build
docker compose up -d
docker compose logs -f api worker
# health:  GET /health (never fails)   ·   GET /ready (gates on the database)

• One backend image with api and worker targets: same dependency set, different entrypoint.
• The migrate service runs prisma migrate deploy and gates the API with service_completed_successfully, so nothing serves traffic on an old schema.
• api and worker share the workspaces volume — that is what makes REVIEW_COMMAND_EXECUTION=queued work: the worker opens the exact path the API created.
• Scale by adding workers; BullMQ plus the per-pull-request lock makes that safe.
• The worker image carries the Docker CLI. Mount /var/run/docker.sock only if you accept that a container can then control the host daemon; it is commented out for that reason.

Before you call it production

• Set NODE_ENV=production explicitly. Compose substitutes it from your .env, so a container run inherits development — and the production invariant checks only run when it is production.
• Mount the App private key and point GITHUB_PRIVATE_KEY_PATH at the in-container path, or pass GITHUB_PRIVATE_KEY inline.
• Set COOKIE_SECURE=true behind TLS, and keep real secrets in the environment rather than a committed file. The API already honors X-Forwarded-* through trustProxy.
• Back up Postgres: the volumes hold every run, finding and approval. Redis needs its AOF, already enabled in compose, so accepted reviews survive a restart.

One command runs everything that is expected to pass.

npm run verify        # typecheck + typecheck:tests + lint + all test projects
npm run test:unit     # no database needed
npm run test:integration
npm run test:e2e
npm run test:e2e:web  # Playwright against the dashboard

The database-backed suites read the seeded fixtures, so run npm run db:seed once after a fresh volume. A review is a real HTTP and database flow in e2e, not a mocked one.

Real failures, and what they actually mean.

What this does not do yet, stated plainly.

• A review is a model’s reading of your code. Evidence is required for blocking findings and the checks give ground truth, but a finding is a claim to verify, not a verdict you delegate.
• A re-review reports a delta: it never claims a previous finding was fixed, only that this run did not raise it again.
• Checks are npm-shaped. A repository whose scripts live elsewhere gets the AI review without the sandboxed checks.
• SARIF export is generated by the dashboard from a run’s findings; uploading it to code scanning is your pipeline’s job, not automatic.
• TLS, ingress, secret management and database backups are deployment concerns this repository does not ship.