Profile: top-level-repository

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

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

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

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

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.

• 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 and docs/for-agents/code-review-cli.md.

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.

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

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. 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. Enable fail-on-block and branch protection when you are ready to use findings 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.

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:

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.

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. The CLI owns provider selection, input sources, policy, and reporting.

# 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

Run these commands from the repository you want to review:

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

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

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.

• Operations guide — providers, permissions, secrets, cost controls, SARIF, failures, releases, and incident-safe defaults.
• Agent handoff — ownership, edit roots, verification commands, and change routes.
• llms.txt — compact public source map for LLMs and coding agents.
• 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:

node examples/verify-readme.mjs

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

The repository is pre-v1 (0.1.x). The CLI and Action are usable today, but immutable v1 Action tags and npm distribution remain planned. Use the GitHub-source command and @main only when that update policy is acceptable; pin a commit SHA for stronger CI reproducibility. See ROADMAP.md and the release guidance.

• 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

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

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.

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.

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.

MIT © AgentsKit contributors.