代码审查工具

Requirements

• Python >=3.11,<3.14;
• Docker for the default PostgreSQL/ParadeDB and Neo4j stack;
• Voyage API credentials for embeddings and reranking;
• VCS credentials for PR reads and publication;
• a supported AI client with the reviewer MCP integration.

Required services and credentials

Run reviewer init to write the selected env file and reviewer check to validate it. Resolution order is REVIEWER_ENV_FILE → $XDG_CONFIG_HOME/rag-reviewer/.env → ./.env.

Important groups:

- Voyage: VOYAGE_API_KEY; - stores: PG_DSN, NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD; - VCS: provider token plus optional API base; - repository scope: DEFAULT_REPO, REVIEW_BRANCHES (branch allowlist fallback; a per-repo home layer takes precedence — see Repositories and branches); - board credentials: provider-specific env declared in the registry.

Published host ports of the Compose storage services are variables, not literals: PARADEDB_PUBLISH_PORT (default 5433), NEO4J_BOLT_PUBLISH_PORT (default 7687) and NEO4J_HTTP_PUBLISH_PORT (default 7474). Container ports stay fixed. reviewer init asks for them in the storage group and derives the first two from PG_DSN and NEO4J_URI, so the client string and the published port cannot drift apart silently; a mismatch on a local host prints a warning without blocking.

PARADEDB_PUBLISH_PORT=6543 NEO4J_BOLT_PUBLISH_PORT=7999 \
  docker compose -f ~/.config/rag-reviewer/docker-compose.yml up -d

reviewer start and reviewer stop manage that Compose file for you:

reviewer start   # up -d --wait, waits for the ParadeDB and Neo4j healthchecks
reviewer stop    # stops the containers; named volumes and the built index survive

reviewer stop also stops the web admin when it was started with --profile web: without an explicit profile selection docker compose does not see it. It leaves the test services (--profile test) alone — those belong to the repository clone's own Compose project. Both storages declare stop_grace_period: 60s: the default 10s are not enough for the Neo4j JVM to shut down cleanly, which left the store to be recovered on the next start.

Both run under the explicit Compose project rag-reviewer. A clone of this repository runs its own stack under the project name rag_for_git — the two publish the same host ports and keep separate volumes, so do not run them at the same time. Contributors working inside the clone should keep using docker compose up -d there.

reviewer stop never removes volumes: it runs docker compose stop, which has no -v flag at all.

On Docker Engine older than 25.0, the start_interval healthcheck key is ignored, so the first Neo4j probe only happens after the plain interval (300s) — exactly the --wait timeout used by reviewer start. On such engines reviewer start can report a timeout failure even though the stack came up fine; upgrading Docker Engine removes the issue.

Prefer variables over editing the Compose file: a hand-edited ~/.config/rag-reviewer/docker-compose.yml no longer matches its recorded hash, so `reviewer update treats it as user-modified (status preserved`) and stops delivering new Compose definitions to it. A preserved Compose file also stops receiving new healthcheck definitions, so reviewer start falls back to waiting for the running state instead of real readiness.

Credentials stay server-side. Credentials are not returned by board metadata or discovery tools and must not be placed in .review.yml.

Deploy for a team

This route assumes that team members open their AI-client sessions on one shared host under one service account. Each client launches its own reviewer-mcp stdio process; those processes share PostgreSQL/ParadeDB and Neo4j through the Compose services bound to 127.0.0.1, plus the service account's reviewer env. It is not one central MCP daemon. MCP requests carry repository, branch, project, and provider_options, and tool results return selected code context to the AI client. For separate workstations, use secured network-accessible stores and configure their DSNs and reviewer env on every workstation instead of using the loopback Compose defaults.

1. On the shared host, start the stores and configure secrets for the service account.

   reviewer update
   docker compose -f ~/.config/rag-reviewer/docker-compose.yml up -d
   reviewer init
   

2. Choose repository and branch scope. Set DEFAULT_REPO as the fallback repo, and either the ordered REVIEW_BRANCHES CSV allowlist in server env or (preferred) a per-repo home layer — see Repositories and branches. Put repository-specific policy, ignored paths, context limits, and non-secret board metadata in .review.yml.

1. Build and verify every tracked branch.

   reviewer index /srv/rag_for_git --ref main --repo mimfort/rag_for_git
   reviewer check
   reviewer status /srv/rag_for_git --branch main --json
   

1. Connect team clients.

   reviewer install --all
   reviewer install codex --dry-run
   

Run installation on the shared host as the same service account. --all configures the supported clients for that account; --dry-run reports planned config writes. Open a new chat or CLI session afterwards; IDE integrations may also require Reload Window.

5. Add optional board context. Select a registered provider in .review.yml, keep its credentials in the reviewer env, and validate the exact project:

   reviewer check --board-project TYPE=PROJECT
   

Repeat --board-project for additional providers. See Task boards and the provider reference.

Installation and configuration

Installation and updates

Persistent CLI:

uv tool install rag-reviewer
reviewer update

uv tool install takes the package name and installs both of its commands, reviewer and reviewer-mcp. Its --from option only pins a different source for the same package (--from rag-reviewer==0.4.3, --from git+…); --from PACKAGE COMMAND is uvx syntax and uv tool install rejects it.

For the one-time transition from 0.4.3, start the new lifecycle through latest uvx and explicitly allow it to upgrade the existing persistent tool:

uvx --refresh --from rag-reviewer@latest reviewer update --upgrade-tool

Every later update is the short command reviewer update. It performs one lifecycle:

• checks PyPI and upgrades the persistent uv tool package when a newer version exists;
• refreshes every detected AI-client MCP integration, native plugin, and file-based skill set;
• synchronizes $XDG_CONFIG_HOME/rag-reviewer/docker-compose.yml from the canonical repository;
• records the managed Compose content hash in .reviewer-update.json.

If the Compose file differs from its recorded hash, reviewer treats it as user-modified, leaves it unchanged, and prints a warning. Update does not run docker compose pull, restart services, remove containers, or delete volumes, so existing databases, indexes, tasks, and subsystem summaries stay intact. Apply a new Compose definition when convenient with the documented `docker compose ... up -d` command.

Temporary/latest invocation:

uvx --from rag-reviewer@latest reviewer --help

An ordinary uvx invocation never mutates a separate persistent tool; only the explicit --upgrade-tool bootstrap does. Use reviewer install CLIENT --dry-run to inspect a named integration write.

`sync-codebase` — build or update the base index

• When: initialize an index, refresh stale code, or rebuild the graph.
• Invoke: /rag-reviewer:sync-codebase --path /srv/repo --ref main.
• Needs: git clone, uvx, reviewer services, Voyage, and optional SCIP.
• Reads/writes: reads the selected git ref and writes branch-scoped vectors/graph nodes.
• Result: incremental index report; failures name the missing prerequisite.

`pr-walkthrough` — human reading guide

• When: orient a human reviewer without running a bug review.
• Invoke: /rag-reviewer:pr-walkthrough owner/repo#123.
• Needs: reviewer MCP, PR access, base index, and graph.
• Reads/writes: reads impact/diffs/callers; posts only on explicit request.
• Result: centrality-first reading order, per-file summary, and grounded impact notes.

Reviewer grounding in plan/review phases (optional)

Reviewer grounding in plan/review phases lets planning and review phases reuse session-less reviewer tools when the base index is current.

Reviewer grounding (plan/review, optional, fail-open). Run reviewer status /path/to/repo --branch main --json first. When drift == 0, prefer search_codebase for cross-file facts and use callers, related_symbols, definition, implementations, or family only for central symbols. The base index does not see uncommitted edits, so read changed files from disk. If reviewer or the index is unavailable, fall back to local search/read tools instead of blocking.

- family(repo, node_id, branch) — the family of look-alike symbols ("who else is like this"): inheritance plus structural contract match. For roll-out tasks ("add a field to every provider"), where one file found is a representative of a family of N.

Configuration ownership

Single repository

Run reviewer init from the clone, inspect the global .env and home per-repo previews, then run reviewer check and reviewer config show --repo owner/name.

Second repository

Run reviewer init --scope repo from the second clone. It creates or previews only that repository's home per-repo YAML and does not rewrite global .env or the first repository's config.

CI / server

Inject secrets into global .env or the process from a secret manager. Use noninteractive init only for deterministic preview/write, mount home YAML for the service account, and keep team-owned policy in committed .review.yml. Pass --repo owner/name when no usable git remote is present.

`configure-review` — update layered policy and branches

- When: tune tracked branches, ignored paths, retrieval limits, summary clustering, or board metadata. - Invoke: /rag-reviewer:configure-review. - Needs: a git repository; MCP and databases are not required for baseline analysis. - Reads/writes: reads tracked Python structure/history and changes approved YAML fields in either home:repos/<owner>/<name>.yml or committed .review.yml; branch values always go to the home per-repo YAML. - Result: preserved foreign keys/comments plus exact rebuild guidance.

CLI reference

Use reviewer COMMAND --help for the current option set. status does not spend Voyage tokens; search and indexing do.

Skills reference

The examples below use Claude-style /rag-reviewer:... invocation. Codex exposes the same namespaced skills with $rag-reviewer:....

Core workflows

Reviewer workflows are delivered as namespaced skills. Each skill defines its own read/write boundaries and confirmation gates; the MCP server performs storage, graph, VCS, and board work.

Ask a grounded codebase question

Use ask for onboarding and codebase Q&A. Answers cite real path:line locations from the base index and code graph. It reads and explains; it neither reviews a PR nor modifies code.

`ask` — grounded codebase Q&A

• When: ask where code lives or how a subsystem works.
• Invoke: /rag-reviewer:ask how does index freshness work?.
• Needs: a built base index and graph.
• Reads/writes: reads repository context and local files; does not modify or review code.
• Result: a Russian explanation with real path:line citations.

Operations, troubleshooting, and limitations