llms-full.txt

# AgentsKit Code Review — full documentation corpus

Generated from the public repository documentation. Prefer llms.txt for concise discovery and this file only when the full operating and ownership context is required.

## AgentsKit ecosystem

- AgentsKit: https://www.agentskit.io/docs
- AgentsKit Registry: https://registry.agentskit.io/docs
- AgentsKit Chat: https://chat.agentskit.io/docs
- Agents Playbook: https://playbook.agentskit.io/docs
- Doc Bridge: https://agentskit-io.github.io/doc-bridge/
- AgentsKit Code Review: https://github.com/AgentsKit-io/code-review-cli#readme
- AgentsKit OS: https://akos.agentskit.io/docs

## Public README

Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/README.md

<p align="center">
  <img src="docs/assets/agentskit-mark.svg" width="64" height="57" alt="AgentsKit" />
</p>

# AgentsKit Code Review

Profile: <code>top-level-repository</code>

**Deep, low-noise AI code review with the model you already use.**

It is intended for developers and teams who want focused review feedback without changing their model subscription, and without adopting a separate chat product surface.

[![CI](https://github.com/AgentsKit-io/code-review-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/AgentsKit-io/code-review-cli/actions/workflows/ci.yml)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13866/baseline)](https://www.bestpractices.dev/projects/13866)
[![License: MIT](https://img.shields.io/badge/License-MIT-0f766e.svg)](https://github.com/AgentsKit-io/code-review-cli/blob/main/LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://github.com/AgentsKit-io/code-review-cli/blob/main/package.json)

**Tags:** `agentskit` · `ai-code-review` · `github-action` · `typescript` · `sarif` · `codex` · `claude` · `ollama`

**Topics:** `ai-agents` · `code-review` · `developer-experience`

**Ecosystem:** [AgentsKit](https://www.agentskit.io/docs) · [Registry](https://registry.agentskit.io/docs) · [Chat](https://chat.agentskit.io/docs) · [Playbook](https://playbook.agentskit.io/docs) · [Doc Bridge](https://agentskit-io.github.io/doc-bridge/) · **Code Review** · [AKOS](https://akos.agentskit.io/docs)

Run code review locally or on every pull request. Bring Claude, Codex, OpenAI, Gemini, Ollama, OpenRouter, or another supported AgentsKit adapter. Seven focused review lenses propose potential problems; adversarial verification filters weak findings before they reach your team.

## Verified proof

- Offline CLI discovery works without credentials (`--help`, `--list-providers`) — covered by `test/cli-smoke.test.mjs`.
- A clean local Codex CLI fixture completes an offline stdin review — covered by the same smoke suite.
- Documentation, Action contract, and Doc Bridge gates run through `npm run check`.
- Machine-readable public map: [`llms.txt`](https://github.com/AgentsKit-io/code-review-cli/blob/main/llms.txt) and [`docs/for-agents/code-review-cli.md`](https://github.com/AgentsKit-io/code-review-cli/blob/main/docs/for-agents/code-review-cli.md).

## Why this exists

Most AI reviewers are easy to start and hard to trust: they produce long lists of stylistic opinions, repeat the same concern, and bury the issue that can actually break production.

AgentsKit Code Review is built around a different contract:

- **Bring your own model.** Use an existing CLI subscription, an API provider, a local model, or your own gateway.
- **Low noise by design.** Findings are challenged by independent verification votes before they survive.
- **Local first, CI ready.** Review a diff before pushing, inspect complete paths, read stdin, or comment directly on a GitHub PR.
- **Control cost and policy.** Set file budgets, concurrency, thresholds, project conventions, and blocking severity.
- **See the cost before execution.** Use `--plan --json` to inspect files, lenses, retries, concurrency, deadline, and estimated provider calls without a model request. Plans label estimates as `bounded` when `thresholds.maxPerFile` is set; otherwise they are `best-effort` because model output volume is inherently variable.

## Run your first review

Open a terminal inside any Git repository and choose a provider you already use. You do not need to clone or install AgentsKit Code Review:

<!-- readme-example:first-review -->
```sh
# Codex CLI — uses your existing login on a trusted local machine
npx --yes github:AgentsKit-io/code-review-cli --provider codex-cli --mode trusted-local

# Claude CLI — uses your existing login
npx --yes github:AgentsKit-io/code-review-cli --provider claude-cli

# OpenAI API
OPENAI_API_KEY=... npx --yes github:AgentsKit-io/code-review-cli \
  --provider openai --model gpt-4o
```

The CLI reviews the current repository's diff against `origin/main` and prints the report in your terminal. Choose another base with `--base main`.

For the Grok Build ACP worker, use `XAI_API_KEY` (or `--api-key`) in the default isolated mode. To reuse `grok login`, opt in explicitly with `--mode trusted-local`.

Local `codex-cli` subprocesses have a 300-second deadline per model call; `claude-cli` and the other local workers use 120 seconds. Every run also has a global deadline (10 minutes for full, 2 minutes for `fast`) and a bounded Codex smoke check before fan-out. Set `--deadline-ms` for a smaller explicit budget; timed-out calls fail explicitly and cannot turn an unreviewed file into an approval.

Terminal provider authentication failures stop the remaining lenses immediately; the review still exits incomplete and never converts a credential failure into approval.

The default `isolated` mode does not inherit an interactive CLI login. Use `--mode trusted-local` only on a machine or runner you trust with the provider's local session and environment.

`grok-cli` is stable and uses Grok Build's ACP transport (`grok agent stdio`) by default. In the default isolated mode, pass `XAI_API_KEY`/`--api-key`; the key is injected into the isolated worker environment, never into command arguments. Existing `grok login` state is available only with explicit local-only `--mode trusted-local`. Isolated workers grant no filesystem write, terminal, MCP, plugin, or subagent capability and use a temporary working directory. `--transport headless` is available for explicit non-interactive runs, while `--transport auto` is local-only and reports an ACP fallback before trying headless.

`opencode-cli` is stable and uses OpenCode's ACP transport (`opencode acp`) by default. In the default isolated mode, pass `OPENCODE_API_KEY`/`--api-key`; the selected key is injected into the isolated worker environment, never into command arguments. Existing OpenCode login/configuration state is available only with explicit local-only `--mode trusted-local`. OpenCode is not installed automatically. `--transport headless` is available for explicit non-interactive runs, while `--transport auto` is local-only and reports an ACP fallback before trying headless.

Preflight refuses an over-budget run before the first provider call. For GitHub PR sources, the CLI automatically caps the reviewed files to the safe call budget when `--max-files` is omitted; the remaining files are marked `UNREVIEWED`, so the result stays incomplete and cannot approve the PR. Use `--max-files` to choose a smaller explicit scope. `--dry-run` and `--plan` print the cap and concrete reductions; `--json` makes the plan machine-readable. CLI providers default to concurrency `1`, while API providers retain concurrency `4`. Required-lens or source coverage failures always exit `2`, even with `--no-fail`.
Use `--profile fast` when latency and provider budget matter more than the optional lenses: correctness, security, and tests run in one structured batch with one verification vote and no retry. The result records provider calls, failures, skips, elapsed time, circuit state, and whether the deadline fired. Any incomplete evidence remains fail-closed.

![AgentsKit Code Review showing an APPROVE result after seven review lenses complete](https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/docs/assets/code-review-terminal.png)

The current command runs directly from GitHub. After the first npm release, the shorter form will be:

```sh
npx @agentskit/code-review --provider codex-cli
```

## Run through pre-commit

The repository publishes a [`pre-commit`](https://pre-commit.com/) hook for teams that already use that framework. It is manual by default because a full adversarial review is slower and more expensive than a formatter or linter.

Add this to `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/AgentsKit-io/code-review-cli
    rev: main # pre-release; pin a release tag when one contains the hook
    hooks:
      - id: agentskit-review
        args: [--provider, codex-cli, --no-fail, --max-files, "20"]
```

Then run it when a change is ready for review:

```sh
pre-commit run --hook-stage manual agentskit-review
```

The hook reviews the repository diff against `origin/main`; it does not claim to review only staged files. Override `--base` when your integration branch differs. To run on every push, override the hook with `stages: [pre-push]` and install that hook type explicitly, but first choose cost, latency, provider, and blocking policies appropriate for the repository.

### Review locally with Ollama

Use Ollama when repository policy requires model inference to stay on a machine or self-hosted runner. Pull a tool-capable coding model that fits the available memory, start Ollama, and review a small branch diff first:

```sh
ollama pull qwen2.5-coder:7b

npx --yes github:AgentsKit-io/code-review-cli \
  --provider ollama \
  --model qwen2.5-coder:7b \
  --base main \
  --base-url http://localhost:11434 \
  --max-files 10 \
  --concurrency 1 \
  --no-fail
```

This reviews committed changes between `main` and `HEAD`; it is not a staged-files-only hook. The selected model must support Ollama tool calling because every review lens submits a structured result. Requests have a 30-second default deadline. `--no-fail` keeps findings advisory, but connection, source, and execution errors still exit nonzero. No provider key is required. Local inference reduces code disclosure, but logs, SARIF files, caches, optional gateways, and observability exporters still need their own access and retention policy.

See the [operations guide](https://github.com/AgentsKit-io/code-review-cli/blob/main/docs/OPERATIONS.md#local-ollama-review) for model sizing, health checks, failure handling, and self-hosted CI guidance.

## Use the GitHub Action

Add `.github/workflows/code-review.yml` to any repository:

```yaml
name: Code Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: AgentsKit-io/code-review-cli@v0.3.0
        with:
          provider: openai
          model: gpt-4o
          api-key: ${{ secrets.LLM_API_KEY }}
          # max-files: '17'
          # max-calls: '1000'
          # max-findings-per-file: '7'
          # profile: 'full' # or fast for a bounded required-lens batch
          # deadline-ms: '600000'
          # fail-on-block: 'true' # advisory by default
          # block: high
```

The Action fetches the PR diff and posts one batched inline review plus a summary. Its defaults review at most 17 files, 7 findings per file, and 1,000 provider calls. It is advisory by default. Advisory mode affects findings only: source, provider, or execution failures still fail the check, and any reviewable file with zero successful primary lenses prevents approval. Summaries report successful and failed lens counts so partial degradation stays visible. `codex-cli` requires a pre-authenticated `trusted-local` self-hosted runner; use an API provider with a secret on GitHub-hosted runners. Enable `fail-on-block` and branch protection when you are ready to use findings as a merge gate.

Building a conversational review experience? Use [AgentsKit Chat](https://chat.agentskit.io/docs) for the cross-framework application layer instead of embedding chat here. Looking for organization-wide orchestration, governance, and production controls? Continue with [AKOS](https://akos.agentskit.io/docs).

Pin the Action to an immutable release tag such as `@v0.3.0`; use a full commit SHA when your policy requires the strongest reproducibility.

## Choose how to run

| Mode | Provider examples | Credentials | Best for |
|---|---|---|---|
| Local CLI | `codex-cli`, `claude-cli`, `grok-cli`, `opencode-cli` | Existing CLI login | Local development or self-hosted runners |
| Hosted API | `openai`, `anthropic`, `gemini`, `mistral`, `groq` | Provider API key | Managed CI |
| Local model | `ollama` | Usually none | Privacy and predictable cost |
| Gateway | `openrouter` or a custom `--base-url` | Gateway-specific | Central routing and policy |

`grok` is the xAI API provider; `grok-cli` is the separate Grok Build CLI entry. `opencode-cli` is the OpenCode CLI entry. API providers are discovered from factories exported by [`@agentskit/adapters`](https://www.npmjs.com/package/@agentskit/adapters). Run `npx --yes github:AgentsKit-io/code-review-cli --list-providers` to see IDs, support levels, transports, and model requirements.

Credentials resolve in this order:

1. `--api-key`
2. `LLM_API_KEY`
3. `<PROVIDER>_API_KEY`, such as `OPENAI_API_KEY`

Secrets passed to the GitHub Action are forwarded through the environment, not included in command-line arguments.

## How review works

```mermaid
flowchart LR
  A["Diff · PR · paths · stdin"] --> B["Normalize targets"]
  B --> C["7 focused lenses"]
  C --> D["Adversarial verification"]
  D --> E["Thresholds + CI policy"]
  E --> F["Markdown · GitHub · SARIF"]
  D -. "weak finding" .-> G["Dropped with audit note"]
```

The review agent lives in `agents/code-review/` and is vendored from the [AgentsKit registry](https://github.com/AgentsKit-io/agentskit-registry/tree/main/registry/code-review). The CLI owns provider selection, input sources, policy, and reporting.

## Common commands

```sh
# Tune verification and severity
npx --yes github:AgentsKit-io/code-review-cli --provider codex-cli \
  --base main --votes 5 --min-severity high

# Review a GitHub PR and post the result
GITHUB_TOKEN=... OPENAI_API_KEY=... \
  npx --yes github:AgentsKit-io/code-review-cli --provider openai --model gpt-4o \
  --pr owner/repo#42 --post

# Review complete files or directories
npx --yes github:AgentsKit-io/code-review-cli --provider claude-cli \
  --paths src --max-files 30

# Review piped source and also write SARIF
echo 'const x = a.b' | npx --yes github:AgentsKit-io/code-review-cli \
  --provider ollama --model llama3 \
  --base-url http://localhost:11434 --stdin --lang ts --sarif out.sarif

# After fetching the PR base and installing reviewdog, reuse its annotation transport
REPORT_FILE="$(mktemp)"
trap 'rm -f "${REPORT_FILE}"' EXIT
npx --yes github:AgentsKit-io/code-review-cli#3dfd7427640148281454d52846d369e5ddf85b11 \
  --provider openai --model gpt-4o \
  --base "origin/${BASE_REF}" --sarif "${REPORT_FILE}" --no-fail &&
reviewdog -f=sarif -name=agentskit-review \
  -reporter=github-pr-review -filter-mode=added -fail-level=error \
  < "${REPORT_FILE}"
```

The reviewdog recipe needs no custom converter: Code Review emits SARIF 2.1.0 and reviewdog consumes SARIF natively. See the [complete GitHub Actions job](https://github.com/AgentsKit-io/code-review-cli/blob/main/docs/OPERATIONS.md#route-findings-through-reviewdog) for pinned installation, base-branch checkout, permissions, severity mapping, and CI ownership of the failure threshold.

## CLI reference

### Providers

Run these commands from the repository you want to review:

| Provider | What you need | Model | Example |
|---|---|---|---|
| `codex-cli` | Codex CLI logged in | Optional | `npx --yes github:AgentsKit-io/code-review-cli --provider codex-cli` |
| `claude-cli` | Claude CLI logged in | Optional | `npx --yes github:AgentsKit-io/code-review-cli --provider claude-cli` |
| `grok-cli` | Grok Build CLI; stable ACP/headless | Optional | `... --provider grok-cli` |
| `opencode-cli` | OpenCode CLI; stable ACP/headless | Optional | `... --provider opencode-cli` |
| `openai` | `OPENAI_API_KEY` | Required | `... --provider openai --model gpt-4o` |
| `anthropic` | `ANTHROPIC_API_KEY` | Required | `... --provider anthropic --model <model>` |
| `gemini` | `GEMINI_API_KEY` | Required | `... --provider gemini --model <model>` |
| `ollama` | Ollama running locally | Required | `... --provider ollama --model llama3 --base-url http://localhost:11434` |
| `openrouter` | `OPENROUTER_API_KEY` | Required | `... --provider openrouter --model <model>` |
| Other adapters | `<PROVIDER>_API_KEY` when applicable | Usually required | `... --provider <name> --model <model>` |

In shortened examples, replace `...` with `npx --yes github:AgentsKit-io/code-review-cli`.

### Options

| Flag | Meaning |
|---|---|
| `--provider <name>` | Required provider: local CLI or `@agentskit/adapters` factory |
| `--model <id>` | Model id; required for API/local-server providers |
| `--api-key <key>` | Provider key; environment variables are preferred |
| `--base-url <url>` | Provider endpoint, local server, or gateway |
| `--transport <name>` | Provider transport: `acp`, `headless`, or local-only `auto` where supported |
| `--base <ref>` | Git diff base; default `origin/main` |
| `--pr owner/repo#N` | GitHub PR source; requires `GITHUB_TOKEN` |
| `--paths <p...>` | Complete files or directories |
| `--stdin [--lang ts]` | Source read from stdin |
| `--post` | Post a batched review when the source is a PR |
| `--sarif <file>` | Also write SARIF |
| `--votes <n>` | Adversarial verification votes; default `3` |
| `--profile <full\|fast>` | Full review or one bounded required-lens batch |
| `--min-severity <level>` | Minimum reported severity |
| `--min-confidence <n>` | Minimum reported confidence |
| `--max-files <n>` | Positive file budget; over-budget runs are refused before the provider |
| `--max-calls <n>` | Provider-call budget; absolute ceiling `1000` |
| `--max-findings-per-file <n>` | Maximum verified findings per file; bounds adversarial verification calls |
| `--concurrency <n>` | Parallel model calls; default `1` for CLI providers, `4` for API providers |
| `--deadline-ms <n>` | Global run deadline; defaults to `600000` (`120000` for `fast`) |
| `--health-check <auto\|off>` | Bounded provider smoke check before model fan-out |
| `--plan`, `--dry-run` | Print provider-free preflight; add `--json` for machine output |
| `--validate-patch` | Run `git apply --check` on suggested patches |
| `--block <severity>` | CI gate floor; default `blocker` |
| `--no-fail` | Keep findings advisory |
| `--conventions <path>` | Inject project conventions |
| `--allow-incomplete` | Local-only exception for a config that declares incomplete lens coverage |
| `--allow-unredacted` | Local-only exception; rejected in CI |
| `--api` | Back-compatible alias for `--provider anthropic` |
| `doctor --provider <name>` | Offline provider diagnostics; no model request |
| `doctor --live` | Explicit provider smoke-test mode |
| `doctor --json` | Stable machine-readable diagnostics |
| `--mode <mode>` | `isolated` (default) or explicit local-only `trusted-local` |
| `--help` | Full command help |

When no conventions path is supplied, the CLI looks for `CONVENTIONS.md`, `CONTRIBUTING.md`, `.cursorrules`, or `AGENTS.md`.

### Versioned configuration

The repository may contain one strict `.agentskit-review.json` file. It must use
`configVersion: 1`; unknown fields, secrets, unsupported values, and unsafe lens
policies fail before provider execution with exit `2`. Every built-in lens is
enabled by default, with `correctness`, `security`, and `tests` required. Flags
override file values. A required lens may only be disabled in an explicitly
declared `incompleteProfile`, which requires `--allow-incomplete` locally and is
never accepted in CI.

```json
{
  "configVersion": 1,
  "profile": "full",
  "lenses": {
    "performance": { "enabled": false, "required": false }
  },
  "votes": 3,
  "budget": { "maxFiles": 20, "maxCalls": 200, "concurrency": 1, "deadlineMs": 600000 },
  "worker": { "timeoutMs": 120000, "maxOutputBytes": 20971520 },
  "thresholds": { "minSeverity": "med", "minConfidence": 0.7 },
  "context": { "mode": "prompt", "patterns": ["src/**"] }
}
```

Provider, model, transport, context trust, redaction, and permissions are
trusted execution inputs; a project config cannot set them in CI. Put provider
credentials only in the environment or provider login, never in this file.
Remote and unknown provider boundaries redact high-confidence credential
patterns before the model sees source. Unsafe, oversized, binary, or excluded
paths are reported as `UNREVIEWED`; content is never silently truncated.

### Doctor

Run `doctor` before a review to check a registered provider’s executable, version, transport, model requirement, configuration mode, and credential presence. It is offline by default; `doctor --live` and normal Codex reviews use a bounded smoke check to catch authentication or hangs before fan-out. API credentials are checked only for presence and values are never printed. Unknown local CLI versions warn locally and fail when `CI=true`. Exit `0` means healthy, `1` means a failed diagnostic, and `2` means invalid CLI usage.

```sh
npx --yes github:AgentsKit-io/code-review-cli doctor --provider codex-cli
npx --yes github:AgentsKit-io/code-review-cli doctor --provider openai --model gpt-4o --json
```

## Cost and privacy

A full review runs seven lenses across selected files and then verifies candidate findings. Control usage with `--profile fast`, `--max-files`, `--max-calls`, `--votes`, `--deadline-ms`, `--concurrency`, paths, and workflow triggers. For sensitive code, use a local model or an approved private gateway; provider data policies still apply to hosted APIs.

## Operations and machine-readable docs

- [Operations guide](https://github.com/AgentsKit-io/code-review-cli/blob/main/docs/OPERATIONS.md) — providers, permissions, secrets, cost controls, SARIF, failures, releases, and incident-safe defaults.
- [Provider compatibility matrix](https://github.com/AgentsKit-io/code-review-cli/blob/main/docs/provider-compatibility.json) — stable CLI transports and their offline fixtures.
- [Agent handoff](https://github.com/AgentsKit-io/code-review-cli/blob/main/docs/for-agents/code-review-cli.md) — ownership, edit roots, verification commands, and change routes.
- [`llms.txt`](https://github.com/AgentsKit-io/code-review-cli/blob/main/llms.txt) — compact public source map for LLMs and coding agents.
- [`llms-full.txt`](https://github.com/AgentsKit-io/code-review-cli/blob/main/llms-full.txt) — complete README, operations, and agent-handoff corpus.
- [`doc-bridge.config.json`](https://github.com/AgentsKit-io/code-review-cli/blob/main/doc-bridge.config.json) — executable Doc Bridge corpus, ownership, and gate contract.

`npm run check` builds the CLI, executes a full credential-free review fixture, validates the composite Action and documentation contract, runs Doc Bridge gates, checks CLI help, and enforces README Standard v1. Prove credential-free discovery with:

```sh
node examples/verify-readme.mjs
```

`npm pack --dry-run` verifies the release payload.

## Maturity

The repository is **pre-v1 (`0.3.x`)**. The CLI and Action are available for evaluation and advisory CI; use an exact release tag such as `@v0.3.0` or a commit SHA, and treat the future `v1` moving tag as a separate stability milestone. See [ROADMAP.md](https://github.com/AgentsKit-io/code-review-cli/blob/main/ROADMAP.md) and the [release guidance](https://github.com/AgentsKit-io/code-review-cli/blob/main/docs/OPERATIONS.md#releases-and-maturity).

## Compatibility

- **Node.js 20+** (see `engines` in `package.json`)
- **TypeScript** source and compiled ESM distribution
- **GitHub Actions** composite Action at repository root (`action.yml`)
- Providers via local CLIs or [`@agentskit/adapters`](https://www.npmjs.com/package/@agentskit/adapters)

## AgentsKit ecosystem

Code Review is the verification step in the broader AgentsKit journey:

| Need | Continue with |
|---|---|
| Build the agent or custom review adapter | [AgentsKit](https://www.agentskit.io/docs) |
| Install the vendored review agent or explore ready agents | [Registry](https://registry.agentskit.io/docs) |
| Deliver review through a conversational application | [AgentsKit Chat](https://chat.agentskit.io/docs) |
| Apply engineering patterns before review | [Playbook](https://playbook.agentskit.io/docs) |
| Generate ownership-aware documentation handoffs | [Doc Bridge](https://agentskit-io.github.io/doc-bridge/) ([source](https://github.com/AgentsKit-io/doc-bridge)) |
| Add enterprise orchestration and production governance | [AKOS](https://akos.agentskit.io/docs) |

This repository intentionally has **no Fumadocs application and no embedded AgentsChat**. Its public product surface is the CLI, GitHub Action, repository documentation, and machine-readable handoffs.

## Contributing

Providers, review lenses, reporters, fixtures, documentation, and false-positive reductions are welcome. Start with [CONTRIBUTING.md](https://github.com/AgentsKit-io/code-review-cli/blob/main/CONTRIBUTING.md), browse issues labeled `good first issue`, or propose a new provider/lens with the issue templates.

Please report vulnerabilities privately as described in [SECURITY.md](https://github.com/AgentsKit-io/code-review-cli/blob/main/SECURITY.md).
Maintainer responsibilities, public decision-making, and the release process are
documented in [GOVERNANCE.md](https://github.com/AgentsKit-io/code-review-cli/blob/main/GOVERNANCE.md).

## Roadmap

The near-term roadmap focuses on a stable `v1` Action, npm distribution, provider smoke tests, better cost visibility, and more community-owned review lenses. See [ROADMAP.md](https://github.com/AgentsKit-io/code-review-cli/blob/main/ROADMAP.md).

## License

[MIT](https://github.com/AgentsKit-io/code-review-cli/blob/main/LICENSE) © AgentsKit contributors.
## Operations guide

Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/docs/OPERATIONS.md

# Code Review operations guide

This guide is the repository-native reference for running AgentsKit Code Review locally and in CI. The CLI is the source of truth for flags; run `agentskit-review --help` against the version or commit you use.

## Provider and credential choices

| Provider class | Examples | Secret or login | Network boundary |
|---|---|---|---|
| Logged-in local CLI | `codex-cli`, `claude-cli`, `grok-cli`, `opencode-cli` | Existing local login | Provider CLI policy |
| Hosted API | `openai`, `anthropic`, `gemini`, `mistral`, `groq` | Repository/org secret | Selected code reaches provider |
| Local model | `ollama` | Usually none | Host or runner network only |
| Gateway | `openrouter`, custom `--base-url` | Gateway secret | Gateway policy and routing |

Credential precedence is `--api-key`, `LLM_API_KEY`, then `<PROVIDER>_API_KEY`. Prefer environment variables and GitHub secrets: process arguments may be visible to other processes or captured by diagnostics. The composite Action forwards its secret through `LLM_API_KEY` and never adds it to CLI arguments.

Do not run hosted review on code whose policy forbids external processing. A local model reduces external disclosure but does not remove the need to secure the runner, logs, cache, and generated SARIF.

## Provider registry and doctor

Provider IDs are versioned registry entries. `grok` is the xAI API adapter, while `grok-cli` and `opencode-cli` are stable local CLI providers. `--list-providers` prints registry metadata and dynamically discovered API factories, including each support level (`stable`, `experimental`, or `unsupported`), transport, and model requirement.

Use the offline doctor before execution:

```sh
npx --yes github:AgentsKit-io/code-review-cli doctor --provider codex-cli
npx --yes github:AgentsKit-io/code-review-cli doctor --provider openai --model gpt-4o --json
```

It checks the named executable and version, transport, model requirement, configuration mode, and credential presence without making a model request. API keys are represented only as `configured` or `missing`; they are never printed. Local CLI credentials are represented as login-managed because login storage is provider-specific. `doctor --live` is the explicit provider smoke-test path; normal Codex reviews run the same bounded smoke check before fan-out. Unknown local CLI versions warn during local runs and fail in CI. Doctor exits `0` when checks pass, `1` when a provider check fails, and `2` for invalid usage.

## First local setup

```sh
git clone https://github.com/AgentsKit-io/code-review-cli.git
cd code-review-cli
npm install
npm run check
npx --yes github:AgentsKit-io/code-review-cli --provider opencode-cli --transport acp --model openai/gpt-4o --no-fail
```

The last command requires an installed and authenticated OpenCode CLI. For a
credential-free verification, `npm run check` uses only the committed offline
fixtures. Precedence is explicit CLI flags, then the repository's
`.agentskit-review.json` policy, then safe defaults; the project file never
selects a trusted execution mode or carries credentials.

## Grok Build CLI via ACP

`grok-cli` is stable and uses `--transport acp` by default. It
starts `grok agent stdio --no-auto-update`, performs the ACP initialize,
authentication (when advertised), session, prompt, update, shutdown, and exit
sequence, then emits one `submit_findings` tool call. The worker accepts only a
`schemaVersion: 1` envelope with valid findings; malformed output gets one
bounded retry.

In the default `isolated` mode, provide `XAI_API_KEY` through the environment
or `--api-key`; the selected key is copied only into the temporary worker
environment. Existing `grok login` state is available only with explicit
local-only `--mode trusted-local`. Filesystem writes, terminal, MCP, plugin,
and subagent requests are denied, and the worker never uses the checkout as
its working directory. `doctor --provider grok-cli` checks executable/version
availability without making a model request. Headless mode is documented below
and must be selected explicitly.

## OpenCode CLI via ACP

`opencode-cli` is stable and uses `--transport acp` by default.
It starts `opencode acp`, performs the ACP initialize, session, prompt, update,
shutdown, and exit sequence, then emits one validated `submit_findings` tool
call. When `--model` is provided it is passed as OpenCode's `--model` option.
The worker allows no filesystem writes, terminal, MCP, plugin, or subagent
requests and retries malformed output once.

In the default `isolated` mode, provide `OPENCODE_API_KEY` through the
environment or `--api-key`; the selected key is copied only into the temporary
worker environment. Existing OpenCode login/configuration state is available
only with explicit local-only `--mode trusted-local`. The CLI does not install
OpenCode automatically.
`doctor --provider opencode-cli` checks executable/version availability without
making a model request. Headless mode is documented below and must be selected
explicitly.

## Grok and OpenCode headless transport

Headless mode is explicit with `--transport headless`. Grok uses
`grok --no-auto-update -p <prompt> --output-format json`; OpenCode uses
`opencode run --format json [--model provider/model] <prompt>`. Their output
framings are parsed separately and normalized to the same strict
`schemaVersion: 1` envelope. Surrounding logs are bounded and tolerated only
when the validated envelope can still be recovered.

`--transport auto` is a local convenience for these two providers:
it tries ACP first, reports the reason on stderr, then tries the provider's
headless command. It is rejected in CI so a pipeline cannot silently change
transport. Both paths use the same isolated worker timeout, output cap,
cancellation, temporary working directory, selected-credential injection, and
redacted diagnostics. Neither path installs a provider CLI automatically.

The executable compatibility source of truth is
[`provider-compatibility.json`](https://github.com/AgentsKit-io/code-review-cli/blob/main/docs/provider-compatibility.json). It lists the
stable providers, every supported transport, required lenses, minimum version,
and the offline fixture that proves each cell. A provider remains experimental
until its registry entry, matrix, fixtures, and doctor checks are all green.

## pre-commit integration

The root `.pre-commit-hooks.yaml` exposes `agentskit-review` as a Node hook. It uses `pass_filenames: false` because the CLI reviews a Git diff, explicit paths, a pull request, or stdin rather than interpreting positional filenames. It is confined to the `manual` stage by default so cloning the hook does not silently add model calls to every commit.

Consumer configuration must select a provider through `args`. Keep credentials in the provider login or environment; never place API keys in `.pre-commit-config.yaml`. Before overriding the hook to `stages: [pre-push]`, decide whether findings are advisory, set a file budget, and confirm that provider latency and data handling are appropriate for every contributor.

The default diff base remains `origin/main`. A pre-commit invocation does not mean the input is limited to the Git staging area. Set `--base` explicitly when the repository uses another integration branch.

## Versioned review configuration

Use a strict `.agentskit-review.json` at the repository root for review policy.
It requires `configVersion: 1` and supports a `full` or `fast` profile. The
fast profile reviews correctness, security, and tests in one bounded batch with
one vote and no retry. The config also supports lens policy (`enabled` and
`required` per built-in lens), votes, retries, thresholds, file/byte/call,
concurrency and global-deadline budgets, conventions, and context selection. All built-in lenses
are enabled by default; correctness, security, and tests are required.
The shared local worker also accepts bounded `timeoutMs` and `maxOutputBytes`
settings; absolute ceilings are always enforced.

Flags override file values. The file cannot contain credentials or executable
plugins. Provider, model, transport, trust mode, redaction, permissions, and
other execution inputs are rejected when supplied by the project config in CI.
An intentionally incomplete profile must say `incompleteProfile: true` and be
run locally with `--allow-incomplete`; it is rejected in CI and cannot become an
approval. Malformed, unknown, or unsafe configuration exits `2` before a model
request and diagnostics do not print config values.

Keep policy-only configuration in the file. Use trusted workflow flags or the
runner environment for provider selection, credentials, and execution mode.

`prompt` is the default context mode. To review an explicit repository snapshot,
set `context.mode` to `isolated-snapshot` and provide repository-relative
patterns such as `src/**` or `!src/generated/**`. Sensitive directories/files,
symlink escapes, binaries, and over-limit inputs are excluded and shown as
`UNREVIEWED`. The default snapshot ceiling is 100 files/5 MiB; the absolute
ceiling is 500 files/25 MiB. Prompt files default to 256 KiB with a 1 MiB
absolute per-file ceiling.

Remote and unknown provider boundaries receive high-confidence credential
redaction while preserving file and line context. `--allow-unredacted` is a
local-only escape hatch and is rejected in CI; never use it for untrusted code.

## Local Ollama review

Ollama serves its local API at `http://localhost:11434` by default. Verify the service without sending repository content:

```sh
curl --fail --silent http://localhost:11434/api/tags >/dev/null
```

Choose a tool-capable model that fits the host; tool calling is required because every lens submits a structured result. `qwen2.5-coder:7b` is a practical starting point for machines that cannot run the larger `qwen3-coder:30b`; model quality, context capacity, latency, and memory requirements vary. Pulling a model downloads several gigabytes and does not start a review:

```sh
ollama pull qwen2.5-coder:7b
```

Start with a bounded, advisory branch review:

```sh
npx --yes github:AgentsKit-io/code-review-cli \
  --provider ollama \
  --model qwen2.5-coder:7b \
  --base main \
  --base-url http://localhost:11434 \
  --max-files 10 \
  --concurrency 1 \
  --no-fail
```

The default source is the committed Git diff from `--base` to `HEAD`. It does not mean “only staged files,” even when invoked by a Git hook. Use `--paths` when complete files are the intended source. Avoid piping a unified Git patch through `--stdin`: stdin is treated as one source file rather than parsed into per-file changed ranges.

Seven primary lenses plus adversarial votes can be expensive for a local model, and each structured result can require more than one model turn. Begin with `--max-files 10`, `--concurrency 1`, and the default three votes. Reduce the file set before reducing verification depth. `--no-fail` makes surviving findings advisory; it does not hide an unavailable model, malformed response, unreadable source, or failed lens coverage.

For a self-hosted runner, bind Ollama only to the network interfaces required by the job, isolate the runner per repository trust boundary, and protect job logs and artifacts. Do not set a hosted gateway as `--base-url` and describe the run as local. Any optional telemetry or observability exporter creates a separate network boundary that must be approved explicitly.

Troubleshooting:

- **Connection refused:** start Ollama and repeat the `/api/tags` health check.
- **Model not found:** run `ollama pull <exact-model-id>` and pass the same id to `--model`.
- **Slow or out-of-memory:** choose a smaller model, reduce `--max-files`, and keep `--concurrency 1`.
- **Context overflow:** review narrower paths or a smaller branch diff; unreviewed files must remain visibly outside the result.
- **No findings with exit 0:** inspect the summary and successful/failed lens counts; advisory output is not proof that every file was reviewed.

## GitHub Action permissions

The copy-ready workflow in [`examples/pull-request.yml`](https://github.com/AgentsKit-io/code-review-cli/blob/main/examples/pull-request.yml) requires:

```yaml
permissions:
  contents: read
  pull-requests: write
```

`contents: read` loads the PR source. `pull-requests: write` posts the batched review. Do not grant repository administration, package write, or workflow write. Fork PRs do not receive normal repository secrets; do not switch to `pull_request_target` merely to expose a model key, because that can execute or process untrusted contributions with privileged context.

The composite Action defaults to 17 files, 7 findings per file, 1,000 provider calls, and a 10-minute global deadline. `codex-cli` is accepted only with `mode: trusted-local` on a pre-authenticated self-hosted runner; use an API provider with a secret on GitHub-hosted runners.

Use environment protection or organization secrets for sensitive providers. Rotate a secret after suspected exposure and review provider usage plus GitHub audit logs.

When `--post` is used with `--pr`, the reviewer stores a hidden SHA and policy
fingerprint marker in the summary comment. Re-running the same head SHA with
the same policy skips provider calls and updates no comments. A new SHA uses
GitHub compare scope only when the previous marked SHA is an ancestor; a
missing marker, force-push, or changed fingerprint falls back to the full PR
file list. Fork PRs are reported as `SKIPPED` with exit `2` on this workflow
boundary; do not switch to `pull_request_target` to expose secrets. Summary
comments are reconciled by marker, while POST/PATCH failures remain visible for
manual retry.

## Advisory and blocking behavior

The Action is advisory by default: `fail-on-block: 'false'` adds `--no-fail`. Findings still post, but surviving blocker/high findings do not fail the job. `--no-fail` never suppresses provider, source, reporter, or review-execution errors. For enforcement:

```yaml
with:
  block: high
  fail-on-block: 'true'
```

Then require the workflow check in branch protection. CLI exit codes are:

| Exit | Meaning | Operator action |
|---:|---|---|
| `0` | Review completed; no blocking finding, or advisory mode | Inspect posted/report output |
| `1` | A finding at or above `--block` survived | Fix, dismiss with evidence, or change policy intentionally |
| `2` | Configuration, provider, source, or reporter failure | Inspect stderr; do not interpret as a clean review |

A model response that is malformed may drop one lens while other lenses continue; progress output and the final summary report successful and failed primary-lens counts. If any reviewable file cannot be ingested or has zero successful primary lenses, the pipeline stops before reporters run and exits `2`, including in advisory mode. Treat missing output or exit `2` as unavailable review, not approval.

Use `--plan --json` (or `--dry-run`) to run the source and budget preflight without a model request. The plan reports profile, batching, files, bytes, enabled and required lenses, votes, retries, concurrency, deadline, estimated provider calls, and concrete reductions when a limit would be exceeded. Estimates are `bounded` when `thresholds.maxPerFile` is set and `best-effort` otherwise, because model output volume is variable. The preflight refuses before the provider starts; `maxCalls` is capped at 1000 and unlimited mode is not supported. A required-lens failure is `INCOMPLETE` and exits `2`, including with `--no-fail`.

## Cost and latency controls

Seven lenses fan out over selected files; candidate findings then receive adversarial votes. The primary controls are:

- `--max-files`: positive hard file budget;
- `--max-calls`: bounded provider-call budget (absolute ceiling 1000);
- `--max-findings-per-file`: positive verified-finding budget per file;
- `--votes`: verification depth and cost;
- `--concurrency`: simultaneous model/subprocess calls (default 1 for CLI providers, 4 for API providers);
- `--profile fast`: one bounded correctness/security/tests batch per file, one vote, and no retry;
- `--deadline-ms`: hard global deadline; active local workers receive the abort signal and queued calls do not start;
- `--health-check`: bounded provider smoke check before fan-out (`auto` or `off`);
- `--paths` or workflow path filters: narrow scope;
- `--min-severity` and `--min-confidence`: output noise, not input-token cost.

Start advisory with a small file budget, measure provider usage, and raise depth only where it improves signal. Never present an unmeasured cost estimate as a guaranteed price.

Every completed report includes provider-call evidence: calls started, failed,
skipped by the circuit/budget, elapsed time, deadline status, and circuit state.
The circuit opens immediately for authentication, timeout, or cancellation
failures and after repeated transient provider failures. Incomplete evidence is
never an approval.

## SARIF

`--sarif out.sarif` writes SARIF 2.1.0 alongside Markdown. Each surviving finding includes a `code-review/<category>` rule, severity level, message, file, and line. Uploading SARIF to GitHub code scanning requires the separate `security-events: write` permission and `github/codeql-action/upload-sarif`; the bundled Action does not request that permission or upload automatically.

SARIF can contain source paths and model-generated explanations. Apply the same retention and access policy as CI logs.

### Route findings through reviewdog

[reviewdog](https://github.com/reviewdog/reviewdog) accepts SARIF directly, so no AgentsKit-specific reporter or converter is required. This complete pull-request job installs reviewdog, fetches the base history, generates the report in advisory mode, and lets reviewdog own diff filtering, annotations, and the final CI threshold:

```yaml
name: AgentsKit reviewdog
on: pull_request

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0
      - uses: reviewdog/action-setup@d8edfce3dd5e1ec6978745e801f9c50b5ef80252 # v1.4.0
        with:
          reviewdog_version: v0.21.0
      - name: Review changed code
        env:
          BASE_REF: ${{ github.base_ref }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
          REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          REPORT_FILE="$(mktemp)"
          trap 'rm -f "${REPORT_FILE}"' EXIT
          npx --yes github:AgentsKit-io/code-review-cli#3dfd7427640148281454d52846d369e5ddf85b11 \
            --provider openai --model gpt-4o --base "origin/${BASE_REF}" \
            --sarif "${REPORT_FILE}" --no-fail &&
          reviewdog -f=sarif -name=agentskit-review \
            -reporter=github-pr-review -filter-mode=added -fail-level=error \
            < "${REPORT_FILE}"
```

The hosted-runner example uses an API provider because local CLI providers require their executable and an existing authenticated session. Replace the provider and model with your approved adapter. The base comes from the pull-request event rather than assuming `main`, and `fetch-depth: 0` makes its remote-tracking ref available to `git diff`. Pass the provider secret through `LLM_API_KEY`, pass the workflow token through `REVIEWDOG_GITHUB_API_TOKEN`, and grant only `contents: read` plus `pull-requests: write`.

The temporary report and `&&` prevent reviewdog from reading stale output when the producer fails. Keep `--no-fail` on the producer so reviewdog receives the complete report when review succeeds; `-fail-level=error` then makes SARIF `error` findings fail the reviewdog step. AgentsKit maps blocker and high findings to SARIF `error`, medium to `warning`, and nit to `note`.

The default `added` filter limits inline feedback to changed lines. Choose a broader reviewdog filter deliberately; broader modes can move findings outside the PR diff into checks, annotations, or console output depending on the reporter. Pin both Code Review and reviewdog to reviewed immutable versions in enforcement workflows.

## Failure scenarios

- **Unknown provider or missing model:** validate with `--list-providers`; API/local-server adapters require `--model`.
- **Authentication failure:** verify only the provider-specific secret/login and avoid printing its value. A terminal authentication failure stops remaining lenses immediately and the review exits incomplete rather than spending one failed call per lens.
- **Rate limit or timeout:** Codex calls stop after 300 seconds by default; other local CLI calls use 120 seconds. Set `AGENTSKIT_REVIEW_SUBPROCESS_TIMEOUT_MS` to a positive millisecond value when needed, reduce concurrency/file budget, or use an approved gateway; retry only when provider policy makes the operation safe.
- **No PR comments:** confirm `pull-requests: write`, token availability, and fork restrictions. The Markdown report still appears in logs.
- **Inline comment rejected:** the reporter falls back to a non-approving comment for GitHub 422 restrictions.
- **Large diff:** GitHub PR reviews cap metadata at 500 files, select only the configured file budget before downloading contents, and stop content downloads at the byte budget. Set `--max-files`/`--max-calls` or split review by paths; truncated or unreviewed files must not be described as reviewed.
- **Ollama timeout:** Requests stop after 30 seconds by default. Use a smaller scope or a responsive local model when the request is aborted; a stalled model must not hold the review indefinitely.
- **Provider unavailable:** fail or mark the check unavailable according to team policy; never silently convert it to approval.

## Releases and maturity

The current package is `0.3.0` and the project is pre-v1:

- GitHub-source CLI commands can pin a commit SHA after `github:AgentsKit-io/code-review-cli#<sha>`;
- Actions should pin `@v0.3.0` or a full commit SHA;
- a moving `@main` reference is suitable only when that mutability is accepted;
- the future `@v1` Action tag remains a separate stability milestone.

Release work updates [`CHANGELOG.md`](https://github.com/AgentsKit-io/code-review-cli/blob/main/CHANGELOG.md), [`ROADMAP.md`](https://github.com/AgentsKit-io/code-review-cli/blob/main/ROADMAP.md), package version, immutable tag guidance, and signed/provenance evidence when available. Run `npm run check` and `npm pack --dry-run` before publishing.

### Automated npm publishing

`.github/workflows/publish.yml` publishes only when a stable GitHub Release is published with a semantic version tag such as `v0.3.0`. The workflow checks out that tag, verifies that the tag matches `package.json`, runs `npm run check` and `npm pack --dry-run`, then publishes `@agentskit/code-review` using [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC). No long-lived `NPM_TOKEN` is stored in GitHub.

Before the first release, configure the npm package's Trusted Publisher for GitHub Actions with:

- Organization: `AgentsKit-io`
- Repository: `code-review`
- Workflow filename: `publish.yml`
- Allowed action: `npm publish`

The npm configuration is a one-time external prerequisite; the GitHub workflow cannot create it. For each release, update the package version and changelog in a reviewed commit, push the commit, then create the matching GitHub Release/tag. Do not run `npm publish` locally.

## Contribution and security

Start with [`CONTRIBUTING.md`](https://github.com/AgentsKit-io/code-review-cli/blob/main/CONTRIBUTING.md). Provider integrations must preserve the AgentsKit adapter contract and keep secrets out of arguments/logs. Review lenses need reproducible evidence and false-positive fixtures. Report vulnerabilities privately through [`SECURITY.md`](https://github.com/AgentsKit-io/code-review-cli/blob/main/SECURITY.md).

For adjacent work, use [AgentsKit](https://www.agentskit.io/docs) for runtime and adapters, [Registry](https://registry.agentskit.io/docs) for the vendored agent, [AgentsKit Chat](https://chat.agentskit.io/docs) when review belongs inside a conversational application, [Playbook](https://playbook.agentskit.io/docs) for engineering patterns, [Doc Bridge](https://agentskit-io.github.io/doc-bridge/) for documentation ownership handoffs, and [AKOS](https://akos.agentskit.io/docs) for enterprise orchestration and production governance.

Machine readers should start with [`llms.txt`](https://github.com/AgentsKit-io/code-review-cli/blob/main/llms.txt), escalate to [`llms-full.txt`](https://github.com/AgentsKit-io/code-review-cli/blob/main/llms-full.txt) only when the complete corpus is required, and use [`docs/for-agents`](https://github.com/AgentsKit-io/code-review-cli/blob/main/docs/for-agents/index.md) before changing an owned module.
## Agent documentation index

Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/docs/for-agents/index.md

# Code Review agent docs

- Code Review CLI handoff — ownership, change routes, security boundaries, and verification: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/docs/for-agents/code-review-cli.md
- Concise machine map — discovery, raw sources, and all seven ecosystem products: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/llms.txt
- Full machine corpus — public, operational, governance, maturity, and agent handoffs: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/llms-full.txt
## Code Review agent handoff

Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/docs/for-agents/code-review-cli.md

---
type: package
package: code-review-cli
editRoot: .
checks: [npm run check, npm pack --dry-run]
---

# Code Review CLI handoff

## Purpose

Provider-neutral, low-noise AI code review for local Git diffs, files/stdin, and GitHub pull requests. Seven focused lenses propose findings; adversarial votes remove weak findings; reporters emit Markdown, GitHub reviews, and SARIF.

## Ownership map

- `src/cli.ts`: public flags, source selection, provider selection, exit policy.
- `src/*-adapter.ts`: logged-in local CLI adapters.
- `agents/code-review/`: review pipeline, lenses, input normalization, reporters.
- `action.yml`: composite GitHub Action contract.
- `.github/workflows/publish.yml`: tag-verified npm Trusted Publishing workflow.
- `examples/`: copy-ready Action workflows.
- `README.md` and `docs/OPERATIONS.md`: public adoption and operations guidance.
- `ecosystem.json`, `llms.txt`, and `llms-full.txt`: canonical product graph and machine-readable discovery/full-corpus surfaces.
- `test/`: credential-free CLI, Action, and documentation contract proofs.

## Boundaries

- Depend on AgentsKit adapter/runtime/tool contracts; do not create a second model abstraction.
- Preserve provider neutrality and advisory-by-default Action behavior.
- Never expose provider keys in arguments, docs fixtures, logs, or PR output.
- This product intentionally has no Fumadocs site and no embedded AgentsChat.
- The vendored review agent tracks the AgentsKit Registry source; keep divergences explicit.

## Change routes

- CLI flag/provider behavior: start at `src/cli.ts`, then update README, operations docs, and tests.
- Local CLI subprocess behavior: start at the matching `src/*-adapter.ts` and add an offline fixture.
- Review logic or noise reduction: start at `agents/code-review/agent.ts` and the relevant lens; prove both survival and rejection behavior.
- GitHub comments/SARIF: start at `agents/code-review/reporters.ts` and verify permissions/failure docs.
- Action input: update `action.yml`, `examples/pull-request.yml`, README, and contract tests together.
- Release automation: update `.github/workflows/publish.yml` and the automated publishing section in `docs/OPERATIONS.md` together.

## Verification

```bash
npm ci
npm run check
npm pack --dry-run
```

`npm run check` includes typecheck, build, an end-to-end offline stdin review, Action/documentation tests, Doc Bridge gates, and CLI help.

## Ecosystem routes

- AgentsKit — runtime, adapters, and custom review agents: https://www.agentskit.io/docs
- Registry — ready-made agent source: https://registry.agentskit.io/docs
- AgentsKit Chat — conversational delivery; do not embed a chat runtime here: https://chat.agentskit.io/docs
- Playbook — engineering discipline before verification: https://playbook.agentskit.io/docs
- Doc Bridge — documentation ownership, freshness, and handoff generation: https://agentskit-io.github.io/doc-bridge/
- AKOS — enterprise orchestration and production governance: https://akos.agentskit.io/docs

Use `llms.txt` for discovery and `llms-full.txt` only when the complete public, operational, and agent-handoff context is required.

## Human guide

- README: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/README.md
- Operations guide: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/docs/OPERATIONS.md
- Contributing: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/CONTRIBUTING.md
- Security: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/SECURITY.md
## Security policy

Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/SECURITY.md

# Security Policy

## Supported versions

Security fixes are provided for the latest published release. Older releases may
be asked to upgrade before receiving a fix.

## Reporting a vulnerability

Do not open a public issue for a suspected vulnerability. Use [GitHub private vulnerability reporting](https://github.com/AgentsKit-io/code-review-cli/security/advisories/new) with the affected version, impact, reproduction steps, and any suggested mitigation.

Please do not include secrets or private source code beyond what is necessary to reproduce the issue. We aim to acknowledge a complete report within 14 days, investigate it, and coordinate disclosure and remediation with the reporter. If the report is accepted, we will keep the reporter informed as the fix progresses.

## Scope reminders

This tool sends selected code to the provider you configure. Review that provider's data handling policy before using a hosted API. Prefer a local model or approved private gateway for repositories whose policy prohibits external processing. Store GitHub tokens and provider keys as secrets; never commit them to workflow files.
## Contributing guide

Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/CONTRIBUTING.md

# Contributing

Thanks for helping make AI code review more useful and less noisy.

## Start here

1. Fork and clone the repository.
2. Create a focused branch from `main`.
3. Run `npm install`.
4. Make the smallest change that solves the issue.
5. Run `npm run check` before opening a pull request.

Node.js 20 or newer is required.

## Project map

- `src/cli.ts` — arguments, providers, review policy, and reporters.
- `src/*-adapter.ts` — adapters for logged-in local CLIs.
- `agents/code-review/` — vendored review agent, lenses, sources, and reporters.
- `action.yml` — GitHub Action interface.
- `examples/` — copy-ready workflows.

## Good contributions

- Reduce a reproducible false positive.
- Add a provider through the existing adapter contract.
- Add a focused review lens with clear evidence requirements.
- Improve a reporter or source without tying it to one model.
- Add provider-neutral examples and documentation.

Please open an issue before a large architectural change. Small fixes and documentation improvements can go straight to a pull request.

## Pull requests

- Keep one concern per PR.
- Explain the user-visible behavior and how you tested it.
- Add or update tests for behavior changes.
- Preserve provider neutrality: provider-specific behavior belongs in its adapter.
- Never commit API keys, model output containing private code, or review tokens.
- Update README or examples when changing the public CLI or Action interface.

Project decisions, maintainer responsibilities, and the release process are
documented in [GOVERNANCE.md](https://github.com/AgentsKit-io/code-review-cli/blob/main/GOVERNANCE.md).

By participating, you agree to follow the [Code of Conduct](https://github.com/AgentsKit-io/code-review-cli/blob/main/CODE_OF_CONDUCT.md).
## Roadmap

Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/ROADMAP.md

# Roadmap

This roadmap communicates direction, not a promise of dates.

## Toward v1

- [ ] Publish `@agentskit/code-review` and signed release artifacts.
- [ ] Publish immutable GitHub Action releases with a moving `v1` tag.
- [ ] Add credential-free adapter contract tests and opt-in provider smoke tests.
- [ ] Document measured review cost and latency by configuration.
- [ ] Expand fixtures for false-positive and multi-language regression testing.

## Community tracks

- Review lenses with precise evidence and low false-positive rates.
- Additional local CLI and private-gateway adapters.
- Reporters for other code-hosting and CI systems.
- Better SARIF, monorepo, and large-diff workflows.

Open an issue before starting a large item so maintainers and contributors can align on scope.
## Changelog

Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/CHANGELOG.md

# Changelog

All notable changes will be documented here. This project follows Semantic Versioning.

## [Unreleased]

## [0.3.0] - 2026-08-30

### Added

- Added global cancellation deadlines, provider health preflight, a circuit breaker, and bounded execution evidence.
- Added the explicit `fast` profile with a single required-lens batch for lower latency and predictable calls.
- Added CI Action inputs for profile, deadline, and health-check policy.

## [0.2.3] - 2026-08-30

### Fixed

- Stop issuing additional provider calls after a terminal authentication failure; reviews still fail closed without spending one failed call per lens.

## [0.2.2] - 2026-08-29

### Added

- Added a GitHub Release workflow for tag-verified npm Trusted Publishing with OIDC and provenance.

### Fixed

- Prevented Codex authentication, timeout, and process failures from being retried as output-schema compatibility failures.
- Documented and exposed explicit trusted-local mode for logged-in Codex/Claude CLI workflows.
- Raised the default Codex local-worker deadline to five minutes and made GitHub PR file budgets enforceable and fail-closed.
- Bounded GitHub Action calls, propagated Claude OAuth credentials, made review fingerprints version-aware, paginated comment reconciliation with a fail-closed cap, and bounded GitHub API responses.

## [0.2.1] - 2026-08-29

### Fixed

- Applied Codex timeout defaults in direct library usage, bounded GitHub PR metadata/content ingestion, and transient-only GitHub GET retries.
- Added Ollama request deadlines and integration coverage for rate limits, posting failures, stalled requests, and large PR limits.

## [0.2.0] - 2026-08-29

### Changed

- Added strict versioned `.agentskit-review.json` policy with lens coverage, budgets, thresholds, context, and safe CI precedence; incomplete profiles require explicit local opt-in.
- Hardened the shared local CLI worker with cancellation, process-tree cleanup, isolated temporary environments, bounded output, and redacted diagnostics.
- Added bounded source snapshots with infrastructure/configuration file support, denylisted sensitive paths, symlink checks, input limits, and data-boundary-aware secret redaction.
- Added provider-free `--plan`/`--dry-run` preflight with explicit file/byte/call budgets, bounded retries, CLI concurrency defaults, and fail-closed required-lens coverage.
- Made reviews fail closed when any reviewable file has no successful primary lens or cannot be ingested; advisory mode now suppresses finding-based failures only, never source/provider/execution failures.
- Added primary-lens execution coverage to review summaries so partial provider degradation is visible.
- Repositioned the CLI and GitHub Action as provider-neutral.
- Made provider selection explicit and removed provider-specific model defaults.
- Added bounded GitHub review reconciliation with SHA/policy fingerprints, incremental compare scope when the prior SHA is an ancestor, fork-safe skip behavior, and idempotent summary updates.
- Added experimental Grok Build CLI ACP support with isolated capability denial, versioned output validation, bounded invalid-output retry, and offline lifecycle fixtures.
- Added experimental OpenCode CLI ACP support with the same isolated, versioned, bounded worker contract and offline lifecycle fixtures.
- Added provider-specific Grok/OpenCode headless transports with explicit local-only ACP fallback via `--transport auto`.
- Added package metadata, CLI help, open-source governance, and contribution guidance.