rag-reviewer — плагин для Claude Code: что делает и как установить
Плагин rag-reviewer проводит ревью пулл-реквестов с учётом контекста всего репозитория через гибридный RAG, граф кода в Neo4j и инлайн-комментарии.
MIT ★ 1 596 обновлён 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install rag-reviewer@awesome-codex-pluginsЧто делает rag-reviewer
Плагин автоматизирует проверку пулл-реквестов с опорой на всю кодовую базу. Для поиска зависимостей и вызовов он объединяет гибридный поиск в PostgreSQL/ParadeDB, граф кода в Neo4j и эмбеддинги через Voyage API. Найденные проблемы оформляются комментариями прямо в строках диффа или выносятся в общий отчёт.
Архитектура построена на собственном MCP-сервере reviewer-mcp. Перед запуском анализа утилита требует собрать базовый индекс ветки командой reviewer index, иначе ревью ограничится только диффом и временным оверлеем.
Для работы необходимы Python 3.11–3.13, Docker для развёртывания баз данных, ключ Voyage API и токен провайдера контроля версий с правами на публикацию.
Какие задачи решает
- находить логические ошибки в пулл-реквесте с оглядкой на граф вызовов проекта
- оставлять инлайн-комментарии в строках диффа через API провайдера VCS
- отвечать на вопросы по кодовой базе со ссылками на конкретные строки файлов
- формировать обзор затронутых компонентов перед ручным код-ревью
Примеры запросов агенту
- /rag-reviewer:review-pr owner/repo#123 --dry-run
- /rag-reviewer:ask как устроен пайплайн аутентификации в этом сервисе
- /rag-reviewer:pr-walkthrough owner/repo#45
Как установить rag-reviewer
Через маркетплейс плагинов
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install rag-reviewer@awesome-codex-pluginsПо шагам, с командами для каждой платформы: Плагины Claude Code: маркетплейсы, установка и как собрать свой
Вопросы о rag-reviewer
Как установить rag-reviewer в Claude Code?
Сначала добавьте каталог плагинов командой /plugin marketplace add hashgraph-online/awesome-codex-plugins, затем установите сам плагин через /plugin install rag-reviewer@awesome-codex-plugins.
Что делает rag-reviewer?
Он анализирует пулл-реквесты с глубоким пониманием репозитория, сопоставляет изменения с графом кода и отправляет проверенные замечания в VCS.
Какие внешние сервисы нужны для запуска?
Понадобятся запущенные через Docker базы данных PostgreSQL/ParadeDB и Neo4j, ключ к Voyage API для векторизации и токен VCS для чтения и публикации комментариев.
Исходный текст
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.
[](https://pypi.org/project/rag-reviewer/)
[](https://pypi.org/project/rag-reviewer/)
[](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