Apex Ray

Local CLI-first AI code review for git diffs with analyzer-backed context.

Full documentation: dobrotacreator.github.io/apex-ray

Apex Ray reads a git diff, builds compact context packs around changed code, runs optional specialist LLM review through local CLIs or direct APIs, verifies findings, and writes Markdown, JSON, HTML, and SARIF reports. It can run locally or in GitHub Actions without depending on a hosted PR-review product.

Apex Ray is pre-1.0. Report schemas and configuration can change while the project is prepared for production use.

Install

One-off run without a persistent install:

uvx apex-ray --help
uvx apex-ray doctor

User-level CLI install:

uv tool install apex-ray
apex-ray --version
apex-ray doctor

pipx install apex-ray is also supported if you use pipx for isolated Python CLI tools.

Quick Start

In a project you want to review:

apex-ray init
apex-ray doctor
git status --short

Inspect and commit the setup files before using the first worktree review for application changes. For a normal project, init writes the repository's exact Apex Ray version to .apex-ray/version and renders managed hooks and agent commands through cached uvx; keep uv available on developer and CI machines. An Apex Ray source checkout can instead use the mutually exclusive .apex-ray/runtime source mode so self-review runs the current checkout with uv run --locked apex-ray.

If Apex Ray later warns that generated agent instructions are outdated, refresh only those managed artifacts with:

apex-ray init --refresh-agent-artifacts --dry-run
apex-ray init --refresh-agent-artifacts

Use apex-ray init --refresh-managed-artifacts to synchronize the hook and instructions with the repository runtime mode. Upgrading a consumer lock is explicit: run the target package with uvx, then add --update-version-lock. Source mode keeps version-free current-checkout launchers across releases. See configuration for the safe migration flow.

Run a deterministic no-LLM review:

apex-ray review --worktree --no-llm --output .apex-ray/reports/review.md --json .apex-ray/reports/review.json

Run the configured LLM review:

apex-ray review --worktree --llm --output .apex-ray/reports/review.md --json .apex-ray/reports/review.json --html .apex-ray/reports/review.html

Review a branch against the configured base:

apex-ray review --base main --llm

Continue only unreviewed packs from a partial report:

apex-ray review --continue-from .apex-ray/reports/review.json --residual-priority p0 --llm
apex-ray review --continue-from .apex-ray/reports/review.json --only-pack '<pack-id>' --llm

Findings describe the reviewed scope, not necessarily the whole diff. A PARTIAL COVERAGE or INCOMPLETE REVIEW result can therefore have zero findings while work remains. To drain a configured baseline reviewer in bounded batches and fail if it cannot finish:

apex-ray review \
  --continue-from .apex-ray/reports/review.json \
  --reviewer correctness \
  --until-complete \
  --strict-coverage \
  --llm

Use an existing reviewer id; when a project has several reviewers, selecting the intended baseline explicitly also keeps cost and completion semantics predictable. Completion covers only context packs matching that reviewer, so a narrow specialist can finish while unrelated global debt remains. The saved report must contain a review-input snapshot, and any live target must still validate. Ordinary non-completion continuation of an older snapshot-less report remains available with a warning, but completion fails closed and requires a fresh review.

Run the same gate that apex-ray init wires into pre-push:

apex-ray gate pre-push

The gate reviews review.base...HEAD, with optional APEX_RAY_BASE or TURBO_SCM_BASE hook overrides, writes .apex-ray/reports/pre-push.md and .apex-ray/reports/pre-push.json, prints an agent-friendly blocking summary, and exits non-zero when the configured policy fails. With fetch_base enabled, those overrides may name an exact remote-tracking branch, a short branch on origin, or an existing local ref/SHA used by stacked-branch tooling.

See the full Quick Start and Review Workflow docs for installation requirements, provider setup, report interpretation, continuation commands, cache behavior, and troubleshooting.

What It Does

• Builds context packs from changed files, symbols, callers, callees, contracts, metadata, and related tests.
• Runs a language-neutral diff -> context pack -> optional LLM review workflow.
• Uses enhanced analyzers for TypeScript/JavaScript, Python, Go, and Dart/Flutter today, with Rust planned next.
• Supports project-specific rules and repo-committed review memory.
• Runs without LLM calls, with Codex CLI / Claude Code CLI subscriptions, or with OpenAI, Anthropic, DeepSeek, Qwen, Kimi, Z.ai, and custom compatible APIs.
• Supports project risk policies and independent correctness, security, financial, UX, or other focused reviewers with separate scope, model routing, depth, verification, and budgets.
• Runs reviewer matrices in GitHub Actions and emits SARIF/code-scanning, step-summary, and downloadable report artifacts.
• Routes cheap and strong models through profiles.
• Tracks LLM coverage, skipped packs, partial severity, provider failures, cache usage, and continuation commands.
• Replays historical GitHub PR review comments for local evals.
• Writes local telemetry so teams can tune cost, latency, and coverage over time.

Analyzer Coverage

Apex Ray's review pipeline is language-neutral. It is strongest where an analyzer backend can build repository-aware context instead of relying only on diff hunks.

What It Does Not Do

Apex Ray does not replace CI, tests, linters, typecheck, dependency scanners, SAST, or human review. It focuses on diff-aware behavioral review and makes partial coverage explicit.

Documentation

• Quick Start
• Review Workflow
• Configuration
• LLM Providers
• Rules And Memory
• Telemetry
• Historical PR Replay Evals
• Architecture
• Development

Development

For local development from source:

git clone git@github.com:dobrotacreator/apex-ray.git
cd apex-ray
uv sync --all-groups
npm --prefix analyzer-runtimes/typescript ci
npm --prefix analyzer-runtimes/typescript run build

Useful checks:

uv run coverage run -m pytest -q
uv run coverage report -m
npm --prefix analyzer-runtimes/typescript run typecheck
npm --prefix analyzer-runtimes/typescript test
npm --prefix analyzer-runtimes/typescript run coverage
git diff --check

See docs/development.md and CONTRIBUTING.md.

Maintainers: release automation is documented in docs/development.md.

License

Apache-2.0. See LICENSE.