# Argus: the reviewer that remembers

> Open-source code review for GitHub that you self-host. It cites what earlier reviews learned, drops repeats your team dismissed, and lists tokens per stage.

Self-hosted only: Docker Compose or Fly.io, Postgres with pgvector 0.8.2 or newer (Compose includes one), a GitHub App you create, a Clerk app for dashboard sign-in, your model keys and an embeddings endpoint for memory. Argus is AGPL-3.0 source; there is no hosted version.

Argus reviews pull requests file by file under one written rubric, filters findings through a separate judge model when a scoring model is configured, and posts one GitHub COMMENT review per run. It keeps what your team teaches it in your Postgres: findings you dismiss, patterns from findings its judge scored highly, and conventions it reads from your diffs, with you deciding when two conflict. With an embeddings endpoint, later reviews drop close repeats of findings you dismissed and cite the pull request a matching pattern came from.

## Start here

- [Self-hosting guide](https://github.com/BeLazy167/argus/blob/main/docs/self-hosting.md): the GitHub App, `backend/.env`, Compose or Fly.io, the dashboard and model keys
- [Landing page as Markdown](https://argus.reviews/landing.md): the full page, including an abridged example review
- [Examples](https://argus.reviews/examples): one example pull request start to finish, in Argus's real formats
- [Documentation](https://argus.reviews/docs): features, settings and commands
- [Source](https://github.com/BeLazy167/argus): AGPL-3.0

## What it does

- **Team memory**: replies and 👍/👎 from people with write access, findings the judge scored 90 or higher (80 under Deep Review) and up to three conventions per diff become memory for the repo. Without a scoring model, or when the judge call fails, blocking and warning findings are stored instead. Memory search needs an embeddings endpoint.
- **Dismissals**: a new finding at similarity 0.80 or higher to one dismissal is dropped before posting and counted; from 0.75 it posts one severity lower. Security findings and five permanent checks are lowered at most one level, never dropped. Reactions are read at the next review of that PR, or when someone replies to that comment.
- **Citations**: a finding that matches a stored pattern cites the pull request the pattern came from ("Matches a prior fix in PR #N"). "A prior fix" is the label; Argus does not check that a fix merged.
- **Convention conflicts**: a convention that contradicts a stored one posts a "Convention conflict" comment, and only a tick from someone with write access settles it.
- **Review Laws**: twelve written rules go into every review prompt. A finding must state the failure scenario and the file:line before a severity; style, untouched lines, speculative abstractions and taste are not findings. Zero findings is a valid review.
- **Review contract**: each PR gets one of eight change classes (production, migration, one_time_script, test, config, docs, generated, revert) from a hotfix label, its branch prefix and its changed paths, with a model only when those are silent, kept at confidence 0.6 or higher. Scripts, docs, generated code and tests skim each deep-triaged file whose own path matches the class, except security-relevant paths; migrations review every .sql file at full depth.
- **Judge and posting**: when a scoring model is configured, a separate judge scores each finding from 0 to 100 on its own scoring guide (with the Jev classifier on, a finding Jev rates a confident false positive is dropped before the judge), against bars set by change class (blocking 35, warning 45, suggestion 55 on production). Up to 10 points under the bar, a finding goes to a collapsed Minor notes list. At most 10 inline comments per review, plus a progress comment it hides when done and replies in its own threads. It never approves or requests changes, and it creates no status checks.
- **Deep Review** (off by default): four specialist prompts (bug hunter, security, architecture, regression) per file triaged for a full review, after a lead brief. Findings from its two passes after scoring get their own judge call.
- **Custom review agents**: reviewers your organization writes, each a name and a prompt added to the review prompt under the same rules. Attach them org-wide or per repo, and a repo can override an agent's name and prompt; each agent adds one review call per file triaged for a full review, with or without Deep Review, up to 8 per run, and the usage block's `checked:` list names the ones that ran. A review reduced by the size limits runs none.
- **Re-check on push**: a push re-reviews only the new commits. Open Argus threads with a change within three lines go to a judge model (with the Jev classifier on, it answers first and settles the threads it is confident about), and only a confirmed fix resolves the thread ("Resolved by <sha>"). The next summary counts threads still open.
- **Earlier-finding re-checks**: up to five findings Argus stored as blocking or a warning, for the files a push changes, are re-read by a model against the diff when the repo's earlier-findings check is on (the backend's default). A prediction at confidence 0.8 or higher that one still applies is listed under "earlier findings may still apply". Nothing is executed.
- **Context**: related files, code-graph dependents, SAST hints from staticcheck, ESLint and Semgrep for the PR's main language, and the PR's stated goal.
- **Issue acceptance and cross-repo PR checks**: linked issues' acceptance criteria are checked against the diff ([docs](https://argus.reviews/docs/features/issue-acceptance)); PRs linked in the description are checked for risks that appear only when the changes combine ([docs](https://argus.reviews/docs/features/cross-pr-checks)).
- **PR description enrichment** (on unless switched off): an "Also in this PR" list and up to two graph-grounded Mermaid diagrams, when the dashboard's Mermaid validator is configured.
- **Commands**: `@argus-eye review [--force]`, `remember [--org] <pattern>`, `resolve`, `fix`, `test [--code]`, `help`. `review` and `remember` need write access; `--org` needs an owner or organization member.
- **MCP server** (off by default, `MCP_ENABLED=true`): an agent signs in through your Clerk app, picks one organization and gets nine tools to search team memory, fetch the reviewer briefing, write or retire memory, and read reviews. Claude Code skills: argus-memory, argus-memory-setup.
- **TypeSafe Jev classifier** (opt-in, off by default): a typed classifier that answers first on five decisions: auto-resolve on push, convention relations, the goal check, a false-positive filter before the judge, and a triage pass that can raise a file's review effort. A confident answer decides alone and skips the model call; an uncertain one goes to your models unchanged. It runs when an installation stores its own TypeSafe key, or when you set `TYPESAFE_API_KEY` and opt the installation in ([docs](https://argus.reviews/docs/features/jev-classifier)).
- **Usage block**: each summary ends with the review contract, what was checked, how many findings team feedback suppressed and how long the review took, then a Stage | Model | Tokens table, with a Cost column when your provider reports cost or the model has a known price.

## Costs and limits

- **Argus: $0**, open source (AGPL-3.0), self-hosted only. No paid tier, no seats, no feature gating.
- **Your costs**: your model and embeddings providers bill you directly on your own keys, Clerk charges at its own rates, and you run the Postgres and server. The median per-repo average in the data behind the size limits is 322k tokens per review.
- **Size and token limits**: at 60 files or 1,500 changed lines, the 40 highest-risk files are reviewed at reduced depth; at 400 files or 20,000 lines the review is refused with the reason on the PR. A repo whose recent reviews averaged 3,000,000 tokens is reduced, and one at 10,000,000 is refused. Change them in Settings → Limits.
- **Cost preview**: with auto-review off for a repo, each PR gets a checkbox comment with a cost preview from the repo's last 20 reviews. Only a tick or `@argus-eye review` from someone with write access starts it.
- [Pricing and the cost estimator](https://argus.reviews/pricing)

## Self-hosting

- GitHub only. Not SOC 2 certified.
- Models: triage, review, scoring and synthesis each take their own provider, model and reasoning effort; triage, review and scoring also take their own max tokens and temperature. The dashboard's Integrations page takes keys for 11 providers: OpenRouter, OpenAI, Anthropic, Fireworks AI, Groq, Together AI, DeepSeek, Azure OpenAI, AWS Bedrock (limited support), Zhipu AI (GLM) and Vercel AI Gateway. Keys are stored AES-256-GCM encrypted.
- Embeddings: `EMBEDDINGS_API_KEY` in `backend/.env` (a Vercel AI Gateway key for the example's base URL; for another provider change `EMBEDDINGS_BASE_URL` and `EMBEDDINGS_MODEL`), or the Memory embeddings card on the Integrations page. A keyless local endpoint needs `EMBEDDINGS_BASE_URL`, `EMBEDDINGS_MODEL` and a model that returns 1024-dimension vectors.
- GitHub App: set its Callback URL to `https://<your-dashboard>/github/callback`, check **Request user authorization (OAuth) during installation**, and set its Client ID and a client secret as `GITHUB_APP_CLIENT_ID` and `GITHUB_APP_CLIENT_SECRET` on the backend. The dashboard links a new installation only after GitHub confirms the user can access it; without them, new installations can't be linked.
- Compose: `docker compose up` starts pgvector/pgvector:pg16, runs migrations and starts the server on port 8080. `backend/.env.example` ships `SELF_HOSTED=false`; with `SELF_HOSTED=true` and no setting stored, Argus reviews each pull request when it opens, gets a push or reopens, and an explicit repo or org setting wins.
- Fly.io: rename the app in `backend/fly.toml`, set the `backend/.env` values with `fly secrets set` (`DATABASE_URL` pointing at your own Postgres with pgvector, and the PEM as `GITHUB_PRIVATE_KEY` in place of `GITHUB_PRIVATE_KEY_PATH`), then `fly deploy` from `backend/`.
- Dashboard: the Next.js app in `web/`, with your Clerk keys, `NEXT_PUBLIC_API_URL` and `MERMAID_VALIDATOR_SECRET`. Set `CORS_ALLOW_ORIGIN`, `DASHBOARD_BASE_URL` and `MERMAID_VALIDATOR_BASE_URL` on the backend to its address. Without `CLERK_JWKS_URL` the dashboard API returns 503.
- Data: your Postgres stores findings, each run's diff and team memory. Server logs include prompts, verified webhook bodies and parsed source files. Nothing in Argus deletes saved diffs.
- What leaves your servers: prompts to your LLM provider, finding and memory text to your embedding endpoint, sign-in through Clerk, and keyless fetches of OpenRouter's public model and price list: from the backend unless `OPENROUTER_PRICING_ENABLED=false`, and from the dashboard's server when someone opens the /pricing estimator, which that flag does not stop. TypeSafe (the Jev classifier) receives finding text, PR metadata and a body excerpt, the stated goal, diff excerpts and stored conventions, only if you set `TYPESAFE_API_KEY` and opt an installation in, or an installation stores its own TypeSafe key; PostHog only when `POSTHOG_API_KEY` (server) or `NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN` (dashboard) is set.
- Spend on your key: with auto-review on, pull requests from forks start reviews. Replies in an Argus thread and `@argus-eye test` from anyone make a model call.
- Prompt injection is mitigated, not prevented: PR text, replies and memory are redacted and wrapped as data; diffs are sent as they are.

## Docs

- [Self-hosting guide](https://github.com/BeLazy167/argus/blob/main/docs/self-hosting.md)
- [Documentation](https://argus.reviews/docs)
- [Docs as Markdown](https://argus.reviews/docs.md)
- [MCP server](https://argus.reviews/docs/mcp)
- [Jev classifier](https://argus.reviews/docs/features/jev-classifier)
- [FAQ](https://argus.reviews/docs/faq)

## Optional

- [Website](https://argus.reviews)
- [Compare with alternatives](https://argus.reviews/compare)
- [Changelog](https://argus.reviews/changelog)
- [Issues](https://github.com/BeLazy167/argus/issues)
- [Security policy](https://github.com/BeLazy167/argus/blob/main/docs/SECURITY.md)