apex-ray 0.1.12

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

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.

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

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

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

apex-ray gate pre-push

The gate reviews review.base...HEAD, 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.

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.

Status	Language family	Strongest current surfaces
Enhanced analyzer available	TypeScript, JavaScript	NestJS controllers/providers/modules/guards, DTO/schema validators, route and DI metadata, workspace imports/exports, enum/const fanout, cache and permission surfaces, related tests.
Enhanced analyzer available	Python	FastAPI routes/dependencies, Pydantic models/settings/validators, SQLAlchemy sessions/transactions, Alembic migrations, async worker/event flows, external HTTP/cloud/Redis adapters, dataclass/TypedDict/Protocol contracts, pytest/unittest tests and fixtures.
Enhanced analyzer available	Go	Type-aware package loading, repository-relative symbols, changed and deleted symbol ranges, callers/callees, interface contracts, context metadata, syntax-only fallback, and related tests.
Enhanced analyzer available	Dart, Flutter	Dart Analysis Server symbols, references, call/type relationships, parts and local packages, related tests, bounded Flutter framework metadata, generated-code suppression, and exact literal platform-channel contracts.
Enhanced analyzer planned	Rust	Repository-aware symbols, callers/callees, contracts, service boundaries, persistence/I/O surfaces, and related tests.
Generic fallback	Other reviewable diffs	Diff-hunk context, risk signals, project rules, memory, reports, and optional LLM review without a repository-aware symbol graph.

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 [e-mail]: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.