Codexa

Codexa is a local change-evidence layer for human and agentic software workflows: committed-change receipts, plan conformance, blast-radius review, and verification crediting built on a deterministic codebase map.

In a pull request or terminal, Codexa reviews the committed base-to-head range and produces one receipt for developers, CI, and automation. If Codex or Claude Code is the editor, the same engine also shows what the agent read, what plan it saved, what changed, which checks would earn verification credit, and which gaps still need an honest handoff.

In plain English: it reads a repository, builds a compact index of the files, symbols, imports, tests, risks, workflows, process traces, and graph clusters it can prove, then gives Codex, Claude Code, or another MCP client small evidence-backed packets when direct source inspection is not enough. Exact, local work stays source-first instead of paying a mandatory context-tool tax. Codexa is meant to help an agent answer questions like:

• What should I read first?
• What could this change break?
• Which tests are relevant?
• Did my final dirty tree match the plan I saved before editing?
• Did the verification commands the agent reported actually prove anything?
• What does this committed branch change, and what should a reviewer verify?

It is not an autonomous coding agent. It does not edit your source files through MCP. It is a context compiler, query server, and verification guide.

Why Codexa

Seven capabilities are deliberately hard to find elsewhere:

• One committed-change receipt. codexa review resolves an explicit Git base and head without a shell, requires the head to match a clean indexed checkout, and returns bounded identity, file changes, diff statistics, graph impact, plan conformance, test recommendations, supplied execution reported verification claims, verdict, and next actions. The CLI, GitHub Action, and advanced MCP change_review operation use the same structured result. Observe mode is the default and never blocks on heuristics; explicit fail mode blocks only on local, range-bound plan drift or reported command failures.

• A drift loop. change_plan snapshots per-file hashes plus symbol and risk baselines before editing; post_edit_review diffs the real dirty tree against that plan afterwards, rename-aware. When no plan was saved, the pre-edit hook saves an implicit baseline automatically, so the review always has a pre-edit reference; an explicit change_plan upgrades it with planned scope, tests, and explicit task invariants. Distinct repeated attempts are counted by task and plan revision; a mandatory replan remains latched until the agent saves a newer accepted plan. Blocking is opt-in: only reviews against an explicit plan can surface a blocking verdict to the host — implicit baselines keep the loop informational.

• Exact checkout identity. Every query validates that the index belongs to the selected canonical worktree and current HEAD. A mismatched checkout, copied index, changing Git probe, or dirty overlay that changes while an authoritative result is being persisted fails closed. A stable dirty overlay remains valid input to change planning and post-edit review; auto-refresh gets one repair attempt and must pass the same identity check before any context is returned.

• A verification ledger. Commands the agent reports are parsed against a faithful POSIX-shell subset before earning coverage credit: npm test || true earns nothing, tsc --help is vetoed as non-compiling, sh -c wrappers are unwrapped with ambiguity failing closed. Scope stated plainly: this detects structural exit-masking in reported commands — it cannot detect a wholesale fabricated report. Targeted Playwright Test files receive reported credit across direct, launcher, and package-script forms; unscoped, project-only, list, UI, and zero-test-tolerant invocations stay uncredited. The opt-in AutoVerify lane exists for execution-backed evidence. Coverage, ledgers, and proof cards label that difference explicitly: executed-by-autoverify evidence ranks above imported live-run manifests and reported commands, while unauthenticated imported artifacts remain explicitly reported rather than being presented as witnessed execution.

• Compaction-safe continuity. Session decisions, rejected hypotheses, invariants, run-artifact references, and stopping conditions are carried by bounded task/session state. Compaction archives are published before active detail is removed, and proof cards verify snapshot memory pointers against the active store or the bounded archive.

• Graph-aware relational packets. v0.7.0 precomputes bounded process packets, functional module clusters, graph-view exports, and opt-in summary prompts. search now reports raw exact-hit counts beside Codexa-ranked anchors, so a "zero grep hits" task can still surface one ranked symbol or file target plus related process and cluster context.

• A fail-closed eval. The eval harness runs real rg/git baselines and fails a scenario outright if the raw baseline does the job better. The archived v0.2.0 release run passed 20/20 scenarios with packets averaging 0.66x the raw baseline output size — and the harness ships in this repo, so you can re-run it yourself. See Public Proof.

Limits, stated up front: TypeScript/JavaScript and Python are the deep lanes (Rust/Go/Java are shallow; other languages get light file facts). Impact expansion caps at graph depth 3. The tested envelope is repos around the ~50K-LOC scale of Codexa itself — expect slower cold indexing and shallower ranking on large monorepos. Everything runs locally: zero API keys and zero network calls in the core paths.

Maintainer Expectations

Codexa is maintained by one person, in spare time, with a deliberately narrow scope. That shapes how this repo works:

• Response times are days to weeks, not hours.
• Scope is narrow on purpose. Deep native language indexers, new LLM analysis layers, broad IDE products, and general-purpose search modes are usually out of scope.
• Not every working PR will be merged. Open an issue first for anything beyond a typo or small docs fix.
• Security issues go through private advisories, not public issues. See SECURITY.md.
• Questions and "is this the right tool?" discussions belong in Discussions, not the issue tracker.

Quick Start

Codexa requires Node.js 22 or newer.

Install from npm:

npm install -g @mirnoorata/codexa

Or work from a checkout:

git clone https://github.com/mirnoorata/codexa.git
cd codexa
npm install
npm run build
npm link

Wire Codexa into another repository:

codexa init /path/to/project --policy-pack            # Codex CLI: .codex/config.toml + hooks + local proof policies
codexa init /path/to/project --claude --policy-pack   # also writes a repo-root .mcp.json for Claude Code
codexa init /path/to/project --ci                     # also writes a read-only pull-request review workflow
codexa session-start /path/to/project
codexa prove /path/to/project --task "make this change safely"

For a start-to-finish first setup, see the new user tutorial. For a host-focused install choice, see No-Brainer Install Guide.

After codexa init, the target repository gets a repo-local .codex/config.toml entry that lets Codex discover the Codexa MCP server automatically, and with --claude a repo-root .mcp.json so Claude Code discovers the same server (only the codexa entry is managed; other servers in an existing .mcp.json are preserved, and malformed JSON aborts the write). When init runs from an evictable npx cache, generated configs pin npx -y @mirnoorata/codexa@<version> instead of the cache path so they keep working after a cache prune.

Codex Project Worktrees And Local Setup

Linked git worktrees are wired the same way. Untracked .codex/config.toml and hook files stay host-local, so a fresh worktree is invisible to Codexa until you run init in it. If a team intentionally tracks those files, init renders worktree-relative launch commands and keeps the shared files unchanged when the same branch is checked out at a different path:

git worktree add ../my-feature feature-branch
codexa init ../my-feature        # non-interactive: config + hooks + a fresh index for the worktree

The worktree gets its own index (its HEAD and dirty state differ from the parent checkout's, so the parent's index would serve stale answers). If you automate worktree creation, add codexa init to that automation; tracked wiring remains Git-clean while the worktree-local ignored index is refreshed.