Skip to main content
plugin CX Codex

rag-reviewer — Claude Code plugin: what it does, how to install

rag-reviewer runs repository-grounded pull request reviews using hybrid search, a Neo4j code graph, and inline diff comments.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install rag-reviewer@awesome-codex-plugins
Open on GitHub

What rag-reviewer does

The plugin inspects pull requests by taking the whole repository into account rather than just modified lines. It pairs a Neo4j code graph with hybrid search in PostgreSQL/ParadeDB, using Voyage API for code embeddings and reranking. Verified findings turn into inline comments on changed diff lines or roll into a summary report.

Workflows execute through dedicated skills and the reviewer-mcp server. Without building a base index first via reviewer index, reviews operate only on a shallow diff overlay and lose broader repository context.

Setting up requires Python 3.11–3.13, Docker for local database containers, a Voyage API key, and VCS credentials with write access for publishing comments.

What it helps with

  • detect regressions across the repository using call graphs and hybrid search
  • post inline comments directly on changed diff lines in pull requests
  • answer architecture questions with exact file path and line citations
  • generate a change walkthrough for human reviewers before merging

Example prompts for the agent

  • /rag-reviewer:review-pr owner/repo#123 --dry-run
  • /rag-reviewer:ask where database connections are initialized
  • /rag-reviewer:pr-walkthrough owner/repo#45

How to install rag-reviewer

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install rag-reviewer@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about rag-reviewer

How to install rag-reviewer in Claude Code?

Add the marketplace source using /plugin marketplace add hashgraph-online/awesome-codex-plugins, then install the package with /plugin install rag-reviewer@awesome-codex-plugins.

What does rag-reviewer do?

It reviews pull requests with whole-repo awareness via hybrid search and code graphs, then submits grounded comments to your VCS.

What external dependencies are required?

It requires Python 3.11–3.13, Docker running PostgreSQL/ParadeDB and Neo4j, a Voyage API key, and VCS credentials to publish reviews.

Source text

rag_for_git · MIT
# rag-reviewer

[Русский](README.ru.md)

AI-assisted pull-request reviews grounded in whole-repository context: hybrid search, a code
graph, and inline comments anchored to changed lines.

> Requires Python 3.11–3.13 and external Voyage, PostgreSQL/ParadeDB, and Neo4j services.
> Publishing reviews also requires credentials for the selected version-control provider.

[![PyPI](https://img.shields.io/pypi/v/rag-reviewer?color=2563eb&label=PyPI)](https://pypi.org/project/rag-reviewer/)
[![Python 3.11–3.13](https://img.shields.io/badge/python-3.11%E2%80%933.13-2563eb)](https://pypi.org/project/rag-reviewer/)
[![License: MIT](https://img.shields.io/badge/license-MIT-22c55e)](LICENSE)

## Start here

Choose the shortest route for what you need now. Both routes lead to the same workflows and
reference sections later in this document.

| If you want to… | Follow |
|---|---|
| Try reviewer and get a first result | [Try reviewer](#try-reviewer) |
| Use reviewer with a team on one shared host | [Deploy for a team](#deploy-for-a-team) |

## Try reviewer

You need Python 3.11–3.13, [uv](https://docs.astral.sh/uv/), Docker, a Voyage API key, and a
version-control system (VCS) token if reviewer should read or publish pull-request reviews. The
stores run locally; embedding and reranking requests go to Voyage.

1. Install the launcher, synchronize reviewer's managed artifacts, start the stores, and configure
   reviewer:

   ```bash
   uv tool install rag-reviewer
   reviewer update
   docker compose -f ~/.config/rag-reviewer/docker-compose.yml up -d
   reviewer init
   ```

   `reviewer update` creates the managed Compose file next to the env file in
   `$XDG_CONFIG_HOME/rag-reviewer/` (`~/.config/rag-reviewer/` by default). One store stack therefore
   serves every repository, and the Compose project name stays independent of the current working
   directory. The command also refreshes detected AI-client integrations and skills.

2. See the supported AI clients and connect one:

   ```bash
   reviewer install --list
   reviewer install codex
   ```

3. Build the branch-scoped searchable snapshot called the base index, then check the environment
   and inspect index freshness:

   ```bash
   reviewer index /path/to/repo --ref main
   reviewer check
   reviewer status /path/to/repo --branch main --json
   ```

   Indexing initializes the `chunks` schema that `reviewer check` queries, so a fresh installation
   must index before checking. The check validates every configured VCS provider; its successful
   identity check does not prove repository-specific permissions. The status payload should show an
   indexed SHA and `drift == 0`.
   Full indexing sends code chunks to Voyage and can be slow on its free tier. Without a base
   index, PR review has only the diff and its temporary changed-file index (overlay), and therefore
   thinner repository context.

4. Open a new client session and run the first review:

   ```text
   # Claude Code
   /rag-reviewer:review-pr owner/repo#123 --dry-run

   # Codex
   $rag-reviewer:review-pr owner/repo#123
   ```

   Invocation syntax differs by client. A dry run returns grounded findings without publishing;
   a normal run publishes through `publish_review` and therefore requires VCS write credentials.

For a temporary launcher without a persistent tool installation:

```bash
uvx --from rag-reviewer@latest reviewer
```

## 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.**

   ```bash
   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](#repositories-and-branches). Put repository-specific
   policy, ignored paths, context limits, and non-secret board metadata in `.review.yml`.

3. **Build and verify every tracked branch.**

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

4. **Connect team clients.**

   ```bash
   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:

   ```bash
   reviewer check --board-project TYPE=PROJECT
   ```

   Repeat `--board-project` for additional providers. See [Task boards](#task-boards) and the
   [provider reference](docs/board-providers.md).

## 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.

### Review a pull request

Use `review-pr` for bug finding. It prepares a PR session, retrieves code and graph
context, analyzes changed files, verifies candidate findings, and publishes only grounded results.
Use `--dry-run` first when validating a deployment. Inline comments can target only commentable
diff lines; off-diff findings go to the summary.

### Solve a task

Use `solve-task` to turn a board task or free-text request into a persisted brief before
development. It checks index freshness, warms task context, gathers related work and code, then
hands the brief to brainstorming. It does not implement the task by itself.

### 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.

### Walk a human reviewer through a PR

Use `pr-walkthrough` for a reading guide: where to start, what each file changes, and
which callers are affected. It is intentionally separate from bug review.

### Run a focused review

Use `performance-review` for repeated I/O, N+1 work, poor asymptotics, batching, caching,
and memory risks. Use `maintainability-review` for complexity, duplication, readability,
separation of concerns, and repository conventions. Both stay within the requested dimension.

### Create, decompose, and finish board tasks

`create-task` drafts a canonical task body and writes only after confirmation.
`decompose-task` turns one stored parent into a fully previewed native-child batch, asks for one
confirmation, preserves the previewed idempotency key on retries, then re-syncs and verifies every
relationship and child read.
`finish-task` links the PR, moves the task to a discovered done target, adds a task link
to the PR body, and re-syncs the task corpus—also only after confirmation.

### Reviewer grounding in plan/review phases (optional)

[Reviewer grounding in plan/review phases](#reviewer-grounding-in-planreview-phases-optional)
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.

## How it works

RAG means retrieval-augmented generation: the model receives code selected by hybrid semantic and
lexical search instead of only the PR diff. The graph adds structural relationships.

```text
PR → prepare_review → base + overlay retrieval → skill analysis
   → verify → policy gate → grounding → dedup → inline comments + summary → cleanup
```

- **Base index.** Persistent chunks live under `base:<branch>`. PostgreSQL/ParadeDB combines
  pgvector approximate nearest-neighbor (ANN) search with BM25 lexical ranking; Voyage produces
  embeddings and reranks candidates.
- **Overlay.** Changed PR files use an ephemeral `pr:N` ref. Retrieval takes unchanged files from
  base and changed files from overlay.
- **Code graph.** Neo4j nodes use `node_id = path#fqn`, where `fqn` is the fully qualified name.
  SCIP, an external type-aware code indexer, provides `CALLS` and method-level `IMPLEMENTS`; `auto`
  falls back to tree-sitter `CALLS` plus class-level `IMPLEMENTS` (from syntax) when SCIP is
  unavailable.
- **Grounded publishing.** Findings must quote real changed code. GitHub suggestions are emitted
  only when the replacement is safely applyable on the RIGHT side of the diff.
- **Idempotency.** Hidden fingerprints prevent reposting the same finding. Overlay/session cleanup
  runs after publication and fail-soft on errors.

For the module-level map and invariants, see [CLAUDE.md](CLAUDE.md).

## Installation and configuration

### 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.

### Installation and updates

Persistent CLI:

```bash
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:

```bash
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:

```bash
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.

### AI clients

`reviewer update` refreshes all detected clients automatically. Use `reviewer install --list` and a
named install when connecting a client for the first time, before it can be detected:

```bash
reviewer install codex
reviewer install --all
reviewer install-skills codex
```

Codex-specific lifecycle:

```bash
uvx --from rag-reviewer@latest reviewer install codex
uvx --from rag-reviewer@latest reviewer install codex --dry-run
codex plugin list --json
codex mcp list
```

Claude Code global plugin lifecycle:

```bash
uvx --from rag-reviewer@latest reviewer install claude-code
claude plugin list --json
claude plugin marketplace list --json
```

After installation or update, start a New Chat/new CLI session; in an IDE, also use Reload Window.

### Breaking skill-name migration

This release removes the redundant `reviewer_` segment from every skill name. Legacy skill
invocations are unsupported: update the plugin/cache, use the short names listed below, then open
a New Chat or new CLI session. In an IDE, also use Reload Window.

### 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](#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.

```bash
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:

```bash
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`.

### Configuration ownership

| Location | Owner | Stores | Must not store |
|---|---|---|---|
| global `.env` | deployment/operator | secrets, credentials, DSNs, runtime infrastructure and compatibility fallbacks | repository policy |
| home global YAML | OS account running reviewer | shared non-secret defaults | credentials |
| home per-repo YAML | OS account running reviewer | `repository.primary_branch`, `repository.index_branches`, operator-owned repo policy | credentials |
| committed `.review.yml` | repository team | team-visible review policy and non-secret task-board metadata | credentials or `repository` |
| git remote / CLI | repository/operator | canonical `owner/name` identity and explicit command overrides | persisted secrets |
| Postgres / Neo4j | reviewer runtime | derived indexes, task/review state and code graph | source-of-truth configuration |

#### 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.

### VCS credentials

| Provider | Environment | Minimum access | Reviewer reads | Reviewer writes | `reviewer check` |
|---|---|---|---|---|---|
| GitHub | `GITHUB_TOKEN` | fine-grained PAT: Pull requests: Read and write; Contents: Read | PR metadata, files, comments, contents, compare | review comments/summary and PR body backlink | authenticates `/user` identity |
| GitLab | `GITLAB_URL`, `GITLAB_TOKEN` | PAT/project token with `api` scope | MR metadata, changes, notes, repository files, compare | discussions/notes and MR description backlink | authenticates `/api/v4/user` identity |

The health check proves URL/token authentication, not every granular repository permission. The
selected repository permissions are exercised by an actual review. `reviewer init` shows the same
contract before prompting only for the selected provider's credentials.

### Repositories and branches

`DEFAULT_REPO` identifies the fallback `owner/name`. The repo tag is resolved as `--repo` →
`git remote origin` → `DEFAULT_REPO`, and the resolution reports its own origin: `cli`,
`git:origin`, or `env:DEFAULT_REPO`. Because an index written under the wrong tag surfaces only
as odd search results, `reviewer index` **refuses** to write when the name was substituted from
`DEFAULT_REPO` rather than derived from the clone — pass `--repo owner/name` or fix the origin
URL. `reviewer status` stays fail-open and instead exposes the origin: a warning line in the text
output and a `repo_source` key in `--json`.

Tracked branches for a repository are
resolved in layered order — the first source that defines them wins entirely (no per-branch
merge): a per-repo home file `$XDG_CONFIG_HOME/rag-reviewer/repos/<owner>/<name>.yml` →
the home-global `review.yml` → the env `REVIEW_BRANCHES` CSV allowlist → `["main"]`. In every
source the first entry is primary unless `primary_branch` is set explicitly. Each branch has
isolated `base:<branch>` chunks and graph nodes. Run `reviewer config show --repo owner/name`
to see the effective branches and which layer produced them.

```bash
reviewer index /path/to/repo --ref main --repo owner/name
reviewer status /path/to/repo --branch main --json
reviewer search "token verification" --branch main
```

Use `reviewer config migrate --repo owner/name` to copy the env `REVIEW_BRANCHES` allowlist into
the per-repo home layer (no-op if a home layer already sets branches), or `reviewer migrate-branches`
once when upgrading a legacy unscoped base index.

### Per-repo `.review.yml`

Per-repo policy overrides server defaults and is read from the target/base branch. Typical fields:

```yaml
paths:
  ignore:
    - generated

summary_cluster_depth: 2
summary_topk_threshold: 20

summary_paths:
  ignore:
    - tests
    - test

context_limits:
  search_codebase:
    floor: 4
    ceiling: 15
  graph:
    hops: 1
  code_section:
    max_files: 20
    max_chunks_per_file: 1
    chars_per_file: 975
    max_augmented_files: 3
```

`summary_paths.ignore` only filters which files feed subsystem-summary clustering — unlike
`paths.ignore`, it does not affect indexing or PR review. Default is `["tests", "test"]`; there
is no env layer (like `context_limits`), and an explicit empty list disables the filter.

`context_limits` has four subsections: `search_codebase` (hybrid + graph-expansion + Voyage
rerank for `/ask`, priming, and PR review), `search_tasks` (RRF-only task retrieval), `graph`
(traversal depth from top hits), and `code_section` — the file budget for the task context's
`code` section (PRI-256, defaults widened in PRI-259). `code_section`'s budget unit is a file,
not a chunk: the section holds up to `max_files` files, each contributing up to
`max_chunks_per_file` chunks of `chars_per_file` characters. The section's
character cap is not a separate key — it is derived: the operational budget is
`max_files × max_chunks_per_file × chars_per_file`, while the post-render safety cap is
`max_files × max_chunks_per_file × chars_per_file × 3 // 2`. The default trades width for depth
(`12 × 1300` → `20 × 975`), growing the operational budget by 25 % (15,600 → 19,500) to raise
bulk core-recall past the acceptance threshold; `chars_per_file` has a floor of 975 (enough to
read a symbol's signature plus a few lines of body) because the recall metric only counts paths
and is blind to fragment depth. See `eval/replay_report.md`, "Приёмка PRI-259".

`code_section.max_augmented_files` (default 3, PRI-257) mixes actual diff paths from similar
tasks into the `code` section — a single source (`similar-diffs`, from the `brief_quality`
table plus a git-log fallback keyed on the task ID). It is a *reserve* of file slots inside
`max_files`, not a cap on what's left over: the hybrid retrieval fills its full `max_files`
budget first, and only against that final output — not the raw retrieval pool — is a candidate
path judged "already known" (checking against the raw pool would discard exactly the files this
lever exists to surface). With no augmented candidates, the hybrid keeps the entire budget. A
co-change (git file-pairs-changed-together) second source was built and measured — 4 core hits on
34 mixed-in paths, a bulk-recall drop — and removed rather than kept disabled; only similar-diffs
covers (median core-recall 0.5 → 0.75, precision 0.167 → 0.333, 28 hits on 35 paths). See
`eval/replay_report.md`, "Приёмка PRI-257".

### Layered repository policy

Policy is resolved in this exact order; each later source wins for the same leaf key:

```text
ENV
  < $XDG_CONFIG_HOME/rag-reviewer/review.yml
  < committed .review.yml at the selected target ref
  < $XDG_CONFIG_HOME/rag-reviewer/repos/<owner>/<name>.yml
```

When `XDG_CONFIG_HOME` is unset, the home root is `~/.config/rag-reviewer`. Merging is **recursive
over mapping values**: a later layer that says nothing about a subsection does not erase it, so a
home `context_limits: {graph: {hops: 2}}` keeps the committed `context_limits.code_section` pin.
Everything else is replaced whole — lists, scalars, an explicit empty mapping, a `null`, and any
change of type. `task_board` is the single atomic mapping key: it is a coherent contract (`type` +
`project` + `create_target`/`done_target` + `options`), so a later layer replaces it completely
rather than per subfield. Replacement of a value that an earlier layer also set is **shadowing**.
Inspect the effective policy, the source of each key, and shadowed sources with:

```bash
reviewer config show --repo group/service --branch main --json
```

`sources` and `shadowed` are keyed by the **dotted path to the leaf**
(`context_limits.code_section.max_files`), not by the top-level policy key — otherwise "the
subsection was shadowed" is indistinguishable from "there was no subsection". `task_board` and any
key a layer set as a whole (to a scalar or `null`) keep a single entry on the key itself. In the
text output a key whose leaves all come from one layer stays a single `source:` line; when layers
differ the line reads `source: mixed` and is followed by one line per leaf.

The committed layer is fetched at the selected ref, so review/config resolution never reads an
uncommitted worktree `.review.yml`.

It is read **from a local clone whenever one is usable**, and only otherwise through the hosting
API. `config show` uses `--path <clone>` if given and the current directory otherwise; the MCP
server uses the clone path recorded by `reviewer index` (which already runs from a clone). A
candidate is accepted only if it is a git repository whose remote matches the target repo — a clone
with **no** recognizable remote is accepted too, which is exactly the case where the committed layer
was previously unreachable. If the ref does not resolve in the clone (branch not fetched), the read
falls back to the API rather than silently reporting an empty layer. The report states which path
was taken:

```bash
reviewer config show --repo group/service --branch main --path /srv/clones/service
# committed: git-blob     ← resolved without a single network call
```

In JSON the same value is the `committed_source` key (`git-blob` / `vcs`); the clone path itself is
never printed. The label names the object that was read — the committed git blob at the ref, never
the file in the clone's working tree.

Because of that distinction, `config show` also reports whether the working tree has drifted away
from that blob. The `worktree_drift` key (JSON: `{"status": ..., "keys": [...]}`; text: a
`worktree_drift:` line followed by the diverging keys) is present only when the committed layer was
actually read from the clone. Statuses: `clean` (no difference in values — a comment-only or
reformatting edit is not drift), `drifted` (diverging leaf keys are listed, **never their values**),
`absent_in_worktree`, `absent_in_blob`, `ref_not_head` (the ref does not resolve to the clone's
HEAD, so no comparison was made), and `unknown` (the diagnostic itself failed; it stays silent in
the text output). Drift is a warning only: the effective policy still comes entirely from the
committed blob, and the exit code is unaffected.

To copy a safe committed policy into the repo-specific home
layer without modifying the committed file, run:

```bash
reviewer config migrate --repo group/service --branch main
```

Migration is non-destructive: an equivalent destination is a no-op, while a differing destination
is reported as a conflict and left unchanged. Home files with credential-like keys are rejected as
policy layers and their values are never displayed; keep credentials in server environment instead.
Home configuration belongs to the OS account running reviewer. On a shared service account it can
silently affect that account's workloads, so use committed `.review.yml` for team-visible policy and
restrict the service account's home configuration permissions.

Use `configure-review` to update context fields without clobbering unrelated keys. It
recommends the per-repo home target first, or can explicitly update the committed `.review.yml` for
team-visible policy.

### Task boards

Board selection is generic and registry-driven. Credentials come from server env; `.review.yml`
contains only non-secret metadata:

```yaml
task_board:
  type: <registered-provider>
  project: PRI
  key_pattern: "[A-Z]+-\\d+"
  url_template: "https://tasks.example/{code}"
  create_target: Backlog
  done_target: Done
  options:
    <provider-option>: <discovered-value>
  sync_filter:
    max_age_days: 180
    include_archived: false
```

The repo block wins; an explicit empty `task_board:` disables board work. If the block is absent,
the server may use a **non-secret deploy-wide fallback**. Calls use configured registry credentials
without returning them.

`sync_filter` is a generic sibling of provider `options`. By default `max_age_days` is absent (no
age limit) and `include_archived: true`. Age uses task last-modified time with an inclusive cutoff,
so a task exactly at the boundary remains eligible. An unknown age is not filtered by age. Only
while `include_archived: false`, unknown archive does not itself exclude the row and an archive
warning is emitted only then. Age filtering runs first and may still exclude the row; in that case
archive uncertainty is not counted or warned. Archive is separate from terminal/done state.
Repositories with the same `task_board.project` share one task corpus. Retention never deletes
implicitly: purge is explicit. A filter change backfills newly eligible tasks on the next successful
full sync.

The server-side flow is **store-first**:

1. `sync_board` enumerates and normalizes tasks, then stores vectors and task-graph metadata under
   `tasks:<type>:<board>`.
2. Skills call `get_task(key, project=...)`; linked tasks/PRs/code come from task context tools.
3. Client models never...

© mimfort · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Code review and refactoring →

From the same set391

The whole set →
registry-broker-codex-plugin registry-broker-codex-plugin lets Claude hand work to outside specialists through HOL Registry Broker: ask first, review the shortlist, then summon an agent. CX Codex ★ 1,596repo stars account-video-downloader The account-video-downloader plugin for Claude Code and Codex batch-downloads watermark-free videos from public creator profiles on YouTube, TikTok, Douyin, Kuaishou, and Bilibili. CX Codex ★ 1,596repo stars red-green-proof The red-green-proof plugin turns a suspected bug into evidence with a focused test, a fix, and a rollback check. Use it when the cause still needs proof. CX Codex ★ 1,596repo stars nueton-receipts nueton-receipts counts every time your agent said it was done and checks each claim against the commands in the same session: confirmed, contradicted or unverified. CX Codex ★ 1,596repo stars quiver quiver structures work from an initial idea to a pull request, with commands for planning, execution, review, debugging, and session handover. CX Codex ★ 1,596repo stars quality-engineering-skills Twenty-three quality engineering skills and eight agents for automotive and manufacturing teams: 8D, FMEA, PPAP, APQP, SPC, MSA, ISO 9001 and IATF 16949 audits. CX Codex ★ 1,596repo stars codex-project-autopilot codex-project-autopilot guides project creation from raw concept to handoff: conducts discovery quizzes, drafts three plan tiers, coordinates roles, and prepares deployment checklists. CX Codex ★ 1,596repo stars pro-launch pro-launch guides a product from idea to release with phase gates and concrete artifacts. Use it for naming, UI work, GTM planning, and shipping. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open