@agentskit/code-review

AgentsKit Code Review

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

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

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.

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:

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

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

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

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

Use the GitHub Action

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

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@main
        with:
          provider: openai
          model: gpt-4o
          api-key: ${{ secrets.LLM_API_KEY }}
          # fail-on-block: 'true' # advisory by default
          # block: high

The Action fetches the PR diff and posts one batched inline review plus a summary. It is advisory by default. Enable fail-on-block and branch protection when you are ready to use it as a merge gate.

Use @main while the project is pre-release. After the first stable release, pin @v1 or a full release tag when reproducibility matters most.

Choose how to run

Mode	Provider examples	Credentials	Best for
Local CLI	codex-cli, claude-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

Provider names other than the two local CLIs resolve to factories exported by @agentskit/adapters. Run npx --yes github:AgentsKit-io/code-review-cli --list-providers for common choices.

Credentials resolve in this order:

• --api-key
• LLM_API_KEY
• <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

diff / PR / paths / stdin
          ↓
   normalize targets
          ↓
  7 specialized lenses
          ↓
 adversarial verification
          ↓
 thresholds + CI policy
          ↓
Markdown / GitHub / SARIF

The review agent lives in agents/code-review/ and is vendored from the AgentsKit registry. The CLI owns provider selection, input sources, policy, and reporting.

Common commands

# 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

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
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
--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
--min-severity <level>	Minimum reported severity
--min-confidence <n>	Minimum reported confidence
--max-files <n>	File budget
--concurrency <n>	Parallel model calls; default 4
--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
--api	Back-compatible alias for --provider anthropic
--help	Full command help

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

Cost and privacy

A full review runs seven lenses across selected files and then verifies candidate findings. Control usage with --max-files, --votes, --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.

Contributing

Providers, review lenses, reporters, fixtures, documentation, and false-positive reductions are welcome. Start with 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.

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.

License

MIT © AgentsKit contributors.