codexa

# Codexa

[![Check](https://github.com/mirnoorata/codexa/actions/workflows/check.yml/badge.svg)](https://github.com/mirnoorata/codexa/actions/workflows/check.yml)
[![npm](https://img.shields.io/npm/v/%40mirnoorata%2Fcodexa)](https://www.npmjs.com/package/@mirnoorata/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](#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](https://github.com/mirnoorata/codexa/security/advisories/new),
  not public issues. See [SECURITY.md](SECURITY.md).
- Questions and "is this the right tool?" discussions belong in
  [Discussions](https://github.com/mirnoorata/codexa/discussions), not the
  issue tracker.

## Quick Start

Codexa requires Node.js 22 or newer.

Install from npm:

```bash
npm install -g @mirnoorata/codexa
```

Or work from a checkout:

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

Wire Codexa into another repository:

```bash
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](https://github.com/mirnoorata/codexa/blob/main/docs/guides/new-user-tutorial.md).
For a host-focused install choice, see
[No-Brainer Install Guide](https://github.com/mirnoorata/codexa/blob/main/docs/guides/no-brainer-install.md).

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:

```bash
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.

This repository also tracks a
[Codex local-environment](https://learn.chatgpt.com/docs/environments/local-environment)
definition at `.codex/environments/environment.toml`. On a local Linux/macOS
host (or Windows through WSL), its Bash setup installs locked dependencies,
builds Codexa, initializes worktree-local `core` wiring, and publishes an
identity-bound receipt through a worktree-local Git ref. Native Windows uses
the tracked PowerShell override: it installs, builds, and proves `core` MCP
config/index readiness with `--no-hooks`, then issues a receipt scoped to the
native-Windows MCP-only lane.
Both wrappers delegate to one Node orch