{
  "markdown": "# Codexa\n\n[![Check](https://github.com/mirnoorata/codexa/actions/workflows/check.yml/badge.svg)](https://github.com/mirnoorata/codexa/actions/workflows/check.yml)\n[![npm](https://img.shields.io/npm/v/%40mirnoorata%2Fcodexa)](https://www.npmjs.com/package/@mirnoorata/codexa)\n\nCodexa is a local change-evidence layer for human and agentic software\nworkflows: committed-change receipts, plan conformance, blast-radius review,\nand verification crediting built on a deterministic codebase map.\n\nIn a pull request or terminal, Codexa reviews the committed base-to-head range\nand produces one receipt for developers, CI, and automation. If Codex or Claude\nCode is the editor, the same engine also shows what the agent read, what plan\nit saved, what changed, which checks would earn verification credit, and which\ngaps still need an honest handoff.\n\nIn plain English: it reads a repository, builds a compact index of the files,\nsymbols, imports, tests, risks, workflows, process traces, and graph clusters it\ncan prove, then gives Codex, Claude Code, or another MCP client small\nevidence-backed packets when direct source inspection is not enough. Exact,\nlocal work stays source-first instead of paying a mandatory context-tool tax.\nCodexa is meant to help an agent\nanswer questions like:\n\n- What should I read first?\n- What could this change break?\n- Which tests are relevant?\n- Did my final dirty tree match the plan I saved before editing?\n- Did the verification commands the agent reported actually prove anything?\n- What does this committed branch change, and what should a reviewer verify?\n\nIt is not an autonomous coding agent. It does not edit your source files through\nMCP. It is a context compiler, query server, and verification guide.\n\n## Why Codexa\n\nSeven capabilities are deliberately hard to find elsewhere:\n\n- **One committed-change receipt.** `codexa review` resolves an explicit Git\n  base and head without a shell, requires the head to match a clean indexed\n  checkout, and returns bounded identity, file changes, diff statistics,\n  graph impact, plan conformance, test recommendations, supplied execution\n  reported verification claims, verdict, and next actions. The CLI, GitHub Action, and advanced\n  MCP `change_review` operation use the same structured result. Observe mode\n  is the default and never blocks on heuristics; explicit fail mode blocks\n  only on local, range-bound plan drift or reported command failures.\n\n- **A drift loop.** `change_plan` snapshots per-file hashes plus symbol and\n  risk baselines before editing; `post_edit_review` diffs the real dirty tree\n  against that plan afterwards, rename-aware. When no plan was saved, the\n  pre-edit hook saves an implicit baseline automatically, so the review always\n  has a pre-edit reference; an explicit `change_plan` upgrades it with planned\n  scope, tests, and explicit task invariants. Distinct repeated attempts are\n  counted by task and plan revision; a mandatory replan remains latched until\n  the agent saves a newer accepted plan. Blocking is opt-in: only reviews\n  against an explicit plan can surface a blocking verdict to the host —\n  implicit baselines keep the loop informational.\n- **Exact checkout identity.** Every query validates that the index belongs to\n  the selected canonical worktree and current HEAD. A mismatched checkout,\n  copied index, changing Git probe, or dirty overlay that changes while an\n  authoritative result is being persisted fails closed. A stable dirty overlay\n  remains valid input to change planning and post-edit review; auto-refresh gets\n  one repair attempt and must pass the same identity check before any context\n  is returned.\n- **A verification ledger.** Commands the agent reports are parsed against a\n  faithful POSIX-shell subset before earning coverage credit: `npm test ||\n  true` earns nothing, `tsc --help` is vetoed as non-compiling, `sh -c`\n  wrappers are unwrapped with ambiguity failing closed. Scope stated plainly:\n  this detects structural exit-masking in *reported* commands — it cannot\n  detect a wholesale fabricated report. Targeted Playwright Test files receive\n  reported credit across direct, launcher, and package-script forms; unscoped,\n  project-only, list, UI, and zero-test-tolerant invocations stay uncredited.\n  The opt-in AutoVerify lane exists for execution-backed evidence. Coverage,\n  ledgers, and proof cards label that difference explicitly:\n  `executed-by-autoverify` evidence ranks above imported live-run manifests and\n  reported commands, while unauthenticated imported artifacts remain explicitly\n  `reported` rather than being presented as witnessed execution.\n- **Compaction-safe continuity.** Session decisions, rejected hypotheses,\n  invariants, run-artifact references, and stopping conditions are carried by\n  bounded task/session state. Compaction archives are published before active\n  detail is removed, and proof cards verify snapshot memory pointers against\n  the active store or the bounded archive.\n- **Graph-aware relational packets.** v0.7.0 precomputes bounded process\n  packets, functional module clusters, graph-view exports, and opt-in summary\n  prompts. `search` now reports raw exact-hit counts beside Codexa-ranked\n  anchors, so a \"zero grep hits\" task can still surface one ranked symbol or\n  file target plus related process and cluster context.\n- **A fail-closed eval.** The eval harness runs real `rg`/`git` baselines and\n  fails a scenario outright if the raw baseline does the job better. The\n  archived v0.2.0 release run passed 20/20 scenarios with packets averaging\n  0.66x the raw baseline output size — and the harness ships in this repo, so\n  you can re-run it yourself. See [Public Proof](#public-proof).\n\nLimits, stated up front: TypeScript/JavaScript and Python are the deep lanes\n(Rust/Go/Java are shallow; other languages get light file facts). Impact\nexpansion caps at graph depth 3. The tested envelope is repos around the\n~50K-LOC scale of Codexa itself — expect slower cold indexing and shallower\nranking on large monorepos. Everything runs locally: zero API keys and zero\nnetwork calls in the core paths.\n\n## Maintainer Expectations\n\nCodexa is maintained by one person, in spare time, with a deliberately narrow\nscope. That shapes how this repo works:\n\n- Response times are days to weeks, not hours.\n- Scope is narrow on purpose. Deep native language indexers, new LLM analysis\n  layers, broad IDE products, and general-purpose search modes are usually out\n  of scope.\n- Not every working PR will be merged. Open an issue first for anything beyond\n  a typo or small docs fix.\n- Security issues go through\n  [private advisories](https://github.com/mirnoorata/codexa/security/advisories/new),\n  not public issues. See [SECURITY.md](SECURITY.md).\n- Questions and \"is this the right tool?\" discussions belong in\n  [Discussions](https://github.com/mirnoorata/codexa/discussions), not the\n  issue tracker.\n\n## Quick Start\n\nCodexa requires Node.js 22 or newer.\n\nInstall from npm:\n\n```bash\nnpm install -g @mirnoorata/codexa\n```\n\nOr work from a checkout:\n\n```bash\ngit clone https://github.com/mirnoorata/codexa.git\ncd codexa\nnpm install\nnpm run build\nnpm link\n```\n\nWire Codexa into another repository:\n\n```bash\ncodexa init /path/to/project --policy-pack            # Codex CLI: .codex/config.toml + hooks + local proof policies\ncodexa init /path/to/project --claude --policy-pack   # also writes a repo-root .mcp.json for Claude Code\ncodexa init /path/to/project --ci                     # also writes a read-only pull-request review workflow\ncodexa session-start /path/to/project\ncodexa prove /path/to/project --task \"make this change safely\"\n```\n\nFor a start-to-finish first setup, see the\n[new user tutorial](https://github.com/mirnoorata/codexa/blob/main/docs/guides/new-user-tutorial.md).\nFor a host-focused install choice, see\n[No-Brainer Install Guide](https://github.com/mirnoorata/codexa/blob/main/docs/guides/no-brainer-install.md).\n\nAfter `codexa init`, the target repository gets a repo-local `.codex/config.toml`\nentry that lets Codex discover the Codexa MCP server automatically, and with\n`--claude` a repo-root `.mcp.json` so Claude Code discovers the same server\n(only the codexa entry is managed; other servers in an existing `.mcp.json`\nare preserved, and malformed JSON aborts the write). When init runs from an\nevictable npx cache, generated configs pin `npx -y @mirnoorata/codexa@<version>`\ninstead of the cache path so they keep working after a cache prune.\n\n## Codex Project Worktrees And Local Setup\n\nLinked git worktrees are wired the same way. Untracked `.codex/config.toml`\nand hook files stay host-local, so a fresh worktree is invisible to Codexa\nuntil you run init in it. If a team intentionally tracks those files, init\nrenders worktree-relative launch commands and keeps the shared files unchanged\nwhen the same branch is checked out at a different path:\n\n```bash\ngit worktree add ../my-feature feature-branch\ncodexa init ../my-feature        # non-interactive: config + hooks + a fresh index for the worktree\n```\n\nThe worktree gets its own index (its HEAD and dirty state differ from the\nparent checkout's, so the parent's index would serve stale answers). If you\nautomate worktree creation, add `codexa init` to that automation; tracked\nwiring remains Git-clean while the worktree-local ignored index is refreshed.\n\nThis repository also tracks a\n[Codex local-environment](https://learn.chatgpt.com/docs/environments/local-environment)\ndefinition at `.codex/environments/environment.toml`. On a local Linux/macOS\nhost (or Windows through WSL), its Bash setup installs locked dependencies,\nbuilds Codexa, initializes worktree-local `core` wiring, and publishes an\nidentity-bound receipt through a worktree-local Git ref. Native Windows uses\nthe tracked PowerShell override: it installs, builds, and proves `core` MCP\nconfig/index readiness with `--no-hooks`, then issues a receipt scoped to the\nnative-Windows MCP-only lane.\nBoth wrappers delegate to one Node orchestrator, which holds a cross-platform\nlock across clean dependency installation, build, init, receipt issuance, and\nstrict startup validation.\n\nIn the desktop composer, select the saved Codexa project, `Worktree`, the\nintended starting branch (normally `main`), and the `Codexa` local environment\nbefore the first prompt. Create and configure that Worktree chat on desktop;\nRemote on mobile may continue a supported desktop Codex chat but cannot select\nor configure local setup. Once the app has created the linked worktree, adopt\nthat checkout for the task instead of creating a second worktree. A successful\nsetup receipt is an immutable Git blob published through the worktree-local\n`refs/worktree/codexa/bootstrap-receipt` ref. Git provides the cross-platform\natomic publication boundary and keeps linked-worktree receipts isolated; no\nmutable `.codex` pathname is treated as receipt authority. The receipt binds\nthe complete regular-file `dist/` runtime manifest, not only the CLI entry\npoint, so a changed imported module invalidates full validation. SessionStart\nconsumes a lightweight durable subset: worktree and Git identity, package/lock\nand startup-procedure inputs, dependency-install seal, managed config/hooks,\nand Node runtime. Ordinary source, HEAD, index, or build-output evolution\ntherefore does not force a complete bootstrap rerun or block a safe index\nrefresh. The explicit `worktree-receipt validate` completion gate still\nrecomputes source, complete `dist/`, HEAD, and installed dependency inventory.\nShared adoption uses a trusted canonical Codexa CLI with `--scope adoption`.\nThat scope validates durable startup inputs, the complete generated runtime,\nand a single-pass, bounded manifest of the complete installed dependency tree\nwhile permitting ordinary source/HEAD evolution. Legitimate dependency\nhardlinks and in-tree executable links are supported; extraneous packages,\ncontent changes, or links escaping `node_modules` invalidate adoption. The\nreceipt is local freshness evidence and never authorizes a controller to\nexecute generated code from the worktree before validation.\n\nIf a Remote-SSH host creates the worktree without invoking local-environment\nsetup, treat it as source-ready only. Repair the active remote worktree and\nverify its observable readiness there:\n\n```bash\nbash .codex/worktree-bootstrap.sh\nnode dist/cli.js session-start \"$PWD\" --json --strict\n```\n\nThen reload or reopen that exact repaired checkout so the host can initialize\nits MCP server. Do not start a generic new Worktree chat: it may create a\nreplacement checkout, abandon the repair, and repeat the skipped-setup path.\nNeither the bootstrap receipt nor SessionStart can prove an already-running\nthread's MCP handshake.\nThat bootstrap receipt records local dependency/build/init setup only, scoped\nto either POSIX hooks or native-Windows MCP-only setup. It is locally validated\nfreshness evidence, not a signature or hostile-repository attestation.\nSessionStart validates the durable startup subset together with managed config\nand index state and still cannot attest the host's current-thread MCP handshake.\n\nCodexa binds an index to the canonical worktree root, Git top-level root,\nHEAD commit, and workspace-state digest. Context and review queries fail closed\nwhen that identity does not match the active checkout. Auto-refresh may make\none bounded repair attempt, but Codexa validates the rebuilt index again before\nserving an answer; `--no-auto-refresh` never serves a mismatched index.\n\nUseful flags: the default tool profile for fresh installs is `core` — only\n`search`, `change_plan`, and `capabilities` are advertised directly, which\nreduces the decoded `tools/list` JSON surface. The compact `capabilities`\ndispatcher keeps every non-core operation reachable through the same\noperation-specific validation.\n`--tools full` also exposes every operation directly, and re-running plain\n`codexa init` preserves whichever profile the repo already uses. Fresh and\ncore-profile Codex and Claude Code launches both pass `serve --tools core`, so\nthe server enforces the compact surface even when a client ignores Codex's\nadditional `enabled_tools` hint. `--agents-md` (opt-in) writes a managed\nCodexa workflow block into the repo's `AGENTS.md` for Codex, and `--claude-md`\n(opt-in) writes the same managed block into `CLAUDE.md` for Claude Code. The\nregion between the `<!-- >>> codexa managed -->` / `<!-- <<< codexa managed -->`\nmarkers is reserved: Codexa replaces it in place on every re-run (so the block\nstays current) and never edits anything outside it. Unbalanced or malformed\nmarkers abort the write instead of silently truncating the file.\n\n## Committed change receipts\n\nUse the receipt directly from a clean checkout. `head` must be the checked-out\ncommit so Codexa cannot combine a different Git object with the current index:\n\n```bash\ncodexa review . --base origin/main --head HEAD\ncodexa review . --base origin/main --head HEAD --format json\ncodexa review . --base origin/main --head HEAD --task-id my-saved-plan\n```\n\nThe default `--mode observe` reports findings and exits successfully. `warn`\nuses warning annotations in GitHub output but remains non-blocking. `fail`\nreturns exit code 2 only for range-bound local plan drift or a supplied\nstructured command report with a nonzero exit; missing heuristic\nrecommendations never become a blocking gate. Command and test claims are\nclassified by the existing verification ledger and remain explicitly\n`reported`, not witnessed execution.\n\n`codexa init . --ci` creates `.github/workflows/codexa-review.yml`. The managed\nworkflow has only `contents: read`, disables persisted checkout credentials,\nchecks out the exact pull-request head, and writes the receipt to the workflow\nsummary and annotations. It does not comment on pull requests. Codexa refuses\nto overwrite a workflow it does not own. Re-running `init --ci` updates only\nthe Codexa-managed workflow.\n\nFor portable plan comparison in CI, commit a redacted Codexa change-plan\nsnapshot inside the repository and pass `--plan-snapshot <path>` (or the\nAction's `plan-snapshot` input). The loader accepts only a bounded, valid,\nnon-symlink snapshot that resolves inside the repository. Local agent flows\nnormally use `--task-id` or MCP `change_review.taskId` instead. A repository\nfile is PR-controlled input, so portable plan conformance is advisory and never\nbecomes a blocking verdict; local cache plans must also bind to the reviewed\nmerge base before they can block explicit fail mode.\n\nThe installed command is `codexa`, and the server can also run ad hoc:\n\n```bash\nnpx -y @mirnoorata/codexa serve /path/to/project --auto-refresh\n```\n\nCodexa is also listed in the official MCP registry as\n`io.github.mirnoorata/codexa` for MCP clients that discover servers there.\n\nFor shared workspace launches such as `codexa serve /srv`, Codexa can route to\nthe active project recorded in `.codex/WORKING.md`. Selected session rows win;\nconflicting active focus, workspace default, or active-session evidence fails\nclosed instead of silently choosing the wrong repo. Use\n`CODEXA_WORKSPACE_SESSION=<session>` or `--workspace-session <session>` when\nserving a shared workspace root with multiple live workers.\n\n## Proof cards and policy packs\n\n`codexa prove` is the compact \"should I trust this agent handoff?\" view:\n\n```bash\ncodexa prove /path/to/project --task \"change auth timeout behavior\" --diff\n```\n\nIt reports:\n\n- index freshness and current dirty-tree state;\n- read-first files selected from the task and graph context;\n- saved `change-plan` snapshot status, including planned edit targets, planned\n  tests, and exact task invariants when a snapshot exists;\n- current task-lifecycle state, including any latched mandatory-replan stop;\n- a bounded decision log recovered from active session memory or its compaction\n  archive, with pointer-integrity diagnostics;\n- verification commands, ledger preview, and reported commands/tests/reports\n  classified with the same command-credit rules as `post-edit-review`;\n- explicitly selected, immutable live-run artifacts bound to the exact task,\n  HEAD, and workspace-state digest;\n- explicit trust tiers on coverage and ledger rows, so an agent-reported pass\n  cannot look equivalent to a fresh AutoVerify execution;\n- local policy-pack status and remaining proof gaps.\n\n`codexa policy-init /path/to/project` writes a small local policy pack under\n`.codex/policies/` (`verification.json`, `complexity.json`, `security.json`).\n`codexa init /path/to/project --policy-pack` creates the same pack during\ninitial setup. The files are plain JSON, are not executable, and are consumed\nby `codexa prove` as bounded local evidence. Neither init nor `policy-init`\noverwrite existing policy files unless `policy-init --force` is passed.\n\n## Works with any MCP host\n\nCodexa is deterministic and model-agnostic — its core indexing, ranking, and\nquery paths call no model and need no API keys, so it serves the same\nevidence-backed context to any agent host that speaks MCP: the OpenAI Codex CLI\n(repo-local `.codex/config.toml`), Claude Code (`codexa init --claude` writes a\nrepo-root `.mcp.json`; the bundled plugin under `integrations/claude-code/`\nships its own MCP server entry, hooks that auto-save the pre-edit baseline and\nsurface blocking drift verdicts to the model, and slash commands; `--claude-md`\nadds workflow steering — pick the plugin **or** `init --claude` for MCP wiring,\nnot both, or Claude Code will register the codexa server twice), and any client\nthat discovers it through the MCP registry. There is no per-model integration to do — the model lives in the\nhost, and Codexa is the host's context server. (The one exception is the\nopt-in, off-by-default semantic lane, which can call a configured embedding\nprovider such as OpenAI — see [Optional Lanes](#optional-lanes).)\n\n| Host | Best install | What Codexa adds | Notes |\n| --- | --- | --- | --- |\n| Codex CLI | `codexa init <repo>` | Repo-local MCP config, SessionStart, pre/post edit hooks, proof cards | Best default path. |\n| Claude Code | Claude plugin under `integrations/claude-code/` or `codexa init <repo> --claude` | Same MCP engine; the plugin additionally supplies SessionStart, PreToolUse, Stop, and slash commands | `init --claude` is MCP-only for Claude. Use plugin or `.mcp.json`, not both. |\n| Other local MCP hosts | MCP registry entry or `codexa serve <repo>` | Query-only codebase context, impact, drift review, test plans | Host must run where the repo is accessible. |\n| Managed cloud agents | Self-hosted sandbox with Codexa on loopback | Local proof layer without exposing a public Codexa server | Public remote HTTP is intentionally not shipped. |\n\nThe Codex plugin bundle under `plugins/codexa/` ships an MCP wrapper and skill,\nnot a post-edit hook. `codexa init` adds edit-scoped Codex hooks, but those run\nbefore later shell verification and do not claim final completion ownership.\nThe Claude plugin's Stop hook remains a useful advisory drift gate, but it does\nnot claim evidence-bearing completion ownership: the agent retains one final\n`post_edit_review` route for actual command reports and invariant reviews.\n\nResult-size discipline is built in: every tool description states its typical\noutput size, and structured results are budget-compacted with truncation\nrecords naming dropped fields. `CODEXA_MCP_STRUCTURED_BUDGET_BYTES` caps the\nserialized UTF-8 JSON bytes of the `structuredContent.data` subobject;\nmandatory envelope identity, lifecycle, and resource metadata is additional,\nso telemetry's `totalBytes` measures the complete reserialized result object.\nAnalysis tools whose evidence can expand accept `responseFormat: \"auto\"`,\n`\"concise\"`, or `\"detailed\"`; the already-bounded `freshness` result has no\nformat switch. Automatic and explicit concise delivery always return a bounded\nconcise receipt. When available, an immutable resource URI preserves the\nbounded detailed packet. If omitted detail is required for a safe decision and\nthat resource cannot be persisted or retrieved, the concise receipt becomes\nblocked and directs the caller to request explicit detailed output. Explicit\n`detailed` output is inline but still subject to a hard total-result bound. The\n`tools/list` surface is budgeted too: the per-tool output schema defaults to a\ncompact top-level contract\n(`CODEXA_MCP_OUTPUT_SCHEMA=full` restores the deep schema). Managed and bare\n`codexa serve` launches default to core, so manual MCP entries receive the same\nbounded surface without a migration step. Use `--tools full` only when an older\nclient requires direct names for every operation. Core advertises three direct\ntools while retaining the same logical operations through `capabilities`.\n\nThe deterministic transport benchmark reserializes decoded JSON and counts\nUTF-8 bytes. That is a provider-agnostic proxy, not a measurement of model input\ntokens, price, or provider-specific wire serialization. Its clean fixture\nsupports a reduction in tool advertisement plus capability-discovery bytes and\nthe hard worst-case result budget. Ordinary first and repeated task-result\nbytes were unchanged, so Codexa does not claim that core mode makes ordinary\nresult packets smaller.\n\n### Managed cloud agents\n\nCodexa's stdio transport is for a host running on the same machine as the\nrepository (Codex CLI, Claude Code). Its HTTP transport is **loopback-only by\ndesign** — non-loopback bind addresses and non-loopback `Origin` headers are\nrejected — so a hosted agent whose container runs in someone else's cloud (for\nexample a Claude Managed Agents session) cannot reach a local Codexa server over\nthe public network.\n\nThe supported way to give a managed cloud agent Codexa context is a\n**self-hosted sandbox**: run the agent's tool-execution container in your own\ninfrastructure, alongside a Codexa server, and point the agent's MCP config at\nCodexa on `127.0.0.1`. The agent loop stays on the provider's orchestration\nlayer; tool execution — and the Codexa connection — stay inside your trust\nboundary, where loopback HTTP is safe. An authenticated remote HTTP mode that\nwould let a provider-hosted container dial into Codexa directly is intentionally\n**not** shipped: exposing a codebase context server to the network needs an\nauth/origin policy Codexa does not yet have, so it is deferred rather than\nshipped insecure.\n\n## The Everyday Workflow\n\nUse Codexa selectively as a guardrail around code changes. A normal bounded\nagent task should usually use no more than two Codexa calls. Exact local work\nmay use zero. The narrow three-call safety exception is an ambiguous,\nmaterially risky edit in a host with no completion/Stop gate:\n`search -> change_plan -> post_edit_review`.\n\n1. Start with source tools when the target is exact and local.\n   Read the named files or symbols and use repository-native verification with\n   zero Codexa calls. A raw-sufficient `search` result is terminal for\n   discovery: work from the exact hits instead of requesting another context\n   packet. A materially risky edit may still warrant one `change_plan` after\n   the source has established the target.\n\n2. Spend one discovery call only when the target is ambiguous.\n   Use `search`, then stop if its raw results are sufficient. Use\n   `session_context` instead for genuinely broad or resumed work; do not stack\n   `session_context`, `search`, and `task_brief` for the same discovery need.\n\n3. Save a plan only for a non-trivial or materially risky edit.\n   `change_plan` with `saveSnapshot=true`, or CLI\n   `change-plan --save-snapshot`, records intended scope, targeted tests,\n   verification commands, and task invariants. For an ambiguous materially\n   risky edit, `search -> change_plan` normally uses the usual two calls.\n\n4. Edit and run the planned verification.\n   Use the targeted tests and commands already returned by `change_plan`.\n   Call `test_plan` only when that guidance remains unresolved or a dedicated\n   verification plan is explicitly requested.\n\n5. Let a true completion/Stop gate review after verification when one is\n   installed and able to carry the actual verification evidence. Codex's\n   `codexa init` hooks are edit-scoped and run before later shell verification;\n   the Claude plugin's Stop hook also lacks a trusted command/invariant ledger.\n   Both retain one final evidence-bearing review route. Without a qualifying\n   completion/Stop gate, an exact materially risky task may use\n   `change_plan -> post_edit_review`. If the target was also ambiguous, the\n   safety-preserving sequence is the narrow three-call exception\n   `search -> change_plan -> post_edit_review`. `post_edit_review` /\n   `post-edit-review` compares the actual dirty tree\n   with the saved snapshot, reports drift, checks declared task invariants, and\n   tells you whether to continue, run tests, inspect, or replan. Repeated\n   distinct attempts are accounted against a task-scoped loop budget; once the\n   budget trips, the stop remains latched until a new saved plan revision is\n   accepted.\n\n6. Produce formal proof only when the handoff needs it.\n   `proof_card` / `prove` binds policy changes, formal audits, releases, or\n   artifact handoffs to freshness, a saved plan snapshot, task invariants,\n   lifecycle status, local policies, and reported verification evidence.\n\nWhen a managed pre-edit hook exists and you skip the explicit plan, it saves an\nimplicit baseline of the dirty tree on the first edit. The review still gets\nchanged-since-baseline and head-drift accuracy, but only an explicit plan\nenables unplanned-scope drift detection.\n\nIn core mode, use `capabilities` to discover or invoke a non-core operation;\nfull mode also exposes each operation directly. Both paths use the same\noperation-specific schema and handler.\n\nAutomatic and explicit concise results stay within the concise result budget.\nWhen persistence succeeds, they also return a content-addressed URI for the\nbounded detailed packet under the active repository. The URI does not encode\nthe checkout path, remains\nresolvable only for that server session, and is pinned by a durable\nlive-session lease until that server shuts down. Concurrent MCP server\nprocesses share a hard per-repository ceiling of 256 result records and 256\nsession leases; a live owner's pins are never evicted merely because they are\nold. If a new unique pin, session lease, opaque route, or persistence write\nwould exceed its bound, Codexa keeps the response concise. It remains\nself-contained when the retained receipt is sufficient; when omitted detail is\nrequired for a safe decision and no URI is available, it returns a blocked\nreceipt that requests explicit detailed output.\nGraceful shutdown releases that server's leases; an abandoned lease is\nreclaimed only after its stale window and owner-process identity check.\nUnpinned records remain LRU-prunable within the 256-record disk bound.\nExplicit `responseFormat: \"detailed\"` returns a bounded detailed packet inline.\nOptional `CODEXA_MCP_TELEMETRY_PATH`\nrecords bounded mechanical byte/time events; byte accounting is synchronous,\nwhile file writes use a bounded queue off the response path. Graceful shutdown\nadds a content-free `session-complete` record; analysis excludes that footer\nfrom event totals and treats a missing footer as partial evidence. A relative\ntelemetry path is resolved once against the configured MCP launch root, so a\nlater workspace-focus change cannot split one server sequence across files.\nEach server session must use a unique destination that is absent at startup;\nthe runner is responsible for enforcing that freshness precondition. The\nwriter creates the path exclusively and leaves an existing path untouched,\nbut an analyzer cannot infer from valid file contents alone which run wrote it.\nTelemetry never changes tool authority or completion scoring.\n\nSelective MCP call budget:\n\n```text\nexact/local/source-sufficient -> source tools, zero Codexa calls\nambiguous/raw-sufficient -> search, then stop\nexact materially risky + completion/Stop gate -> change_plan(saveSnapshot)\nambiguous materially risky + completion/Stop gate -> search -> change_plan(saveSnapshot)\nexact materially risky + no completion gate -> change_plan(saveSnapshot) -> post_edit_review\nambiguous materially risky + no completion gate -> search -> change_plan(saveSnapshot) -> post_edit_review\n```\n\nThese are ceilings, not an automatic chain. Every additional call must be\njustified by unresolved ambiguity, material edit risk, or a missing completion\nreview gate; a returned tool name alone is not a reason to keep calling Codexa.\n\n## What Codexa Builds\n\nRunning `codexa index /path/to/project` writes generated files under the target\nrepo's `.codex/codebase/` directory:\n\n```text\n.codex/codebase/README.md\n.codex/codebase/codex-contract.md\n.codex/codebase/repo-map.md\n.codex/codebase/relational-packets.md\n.codex/codebase/relational-packets.json\n.codex/codebase/relational-graph.json\n.codex/codebase/packet-summary-prompts.ndjson\n.codex/codebase/risk-map.md\n.codex/codebase/placeholder-map.md\n.codex/codebase/test-map.md\n.codex/codebase/conventions.md\n.codex/codebase/workflows.md\n.codex/codebase/freshness.json\n.codex/codebase/index.json\n.codex/codebase/facts.ndjson\n.codex/codebase/modules/\n.codex/codebase/playbooks/\n```\n\nFor lay readers, these are the maps and checklists Codex reads. For engineers,\nthe durable machine-readable index is `index.json` plus `facts.ndjson`; the\nMarkdown files are compact human/agent-facing projections of the same facts.\n`relational-packets.md` is the read-first graph packet view for process traces\nand module clusters; the JSON companions are bounded machine-readable exports\nfor tools and graph visualizers. `packet-summary-prompts.ndjson` contains\nexplicit opt-in prompt records only — indexing does not call a model.\n\nGenerated cache and working state live under `.codex/cache/`. Codexa-owned cache\nwrites are allowed; source-file mutation is not exposed through MCP tools.\n\n## Main Commands\n\n| Command | Use it for |\n| --- | --- |\n| `codexa init <repo>` | Write repo-local Codex MCP config/hooks and index the repo (`--claude` for Claude Code, `--ci` for a read-only PR workflow, `--tools full` for every tool, `--agents-md` for an AGENTS.md workflow block). |\n| `codexa session-start <repo>` | Print a cheap versioned receipt with separate config, index, required local setup, and current-thread MCP activation states (`--json` for structured output; `--strict` for observable readiness gating). |\n| `codexa worktree-receipt issue\\|validate <repo>` | Issue bootstrap-bound setup evidence or validate it. Validation defaults to the full source/dist/dependency scope; `--scope startup` checks durable startup readiness and `--scope adoption` adds generated-runtime and installed-dependency integrity without binding source/HEAD. Issuance requires the orchestrator's pre-install startup fingerprint and pre-build source fingerprint. |\n| `codexa index <repo>` | Build `.codex/codebase/` artifacts once. |\n| `codexa watch <repo>` | Keep artifacts fresh during active edit sessions. |\n| `codexa status <repo>` | Check freshness and parser errors without refreshing. |\n| `codexa doctor <repo>` | Diagnose wiring, freshness, hooks, artifacts, and MCP readiness. |\n| `codexa repo-map <repo>` | Show ranked modules/files. |\n| `codexa search <repo> --query \"...\"` | Discover a target from natural language, identifiers, or broad prompts. |\n| `codexa find-context <repo> --query \"...\"` | Find matching files, symbols, and usage sites. |\n| `codexa explain <repo> --file path` | Explain a file. |\n| `codexa explain <repo> --symbol name` | Explain a symbol neighborhood. |\n| `codexa impact <repo> --file path` | Estimate blast radius for a file or symbol. |\n| `codexa diff-impact <repo>` | Summarize current dirty worktree impact. |\n| `codexa review <repo> --base <ref> --head HEAD` | Produce the shared committed-change receipt for terminal, JSON, or GitHub output. |\n| `codexa test-plan <repo> --diff` | Recommend targeted tests for current changes. Use `--file path` when there is no dirty diff but you already know the target. |\n| `codexa brief <repo> --task \"...\"` | Get the default read-first packet before editing. |\n| `codexa context-pack <repo> --task \"...\"` | Get a larger task-shaped context packet. |\n| `codexa focus-brief <repo> --task \"...\"` | Orient around a broad project question. |\n| `codexa callers <repo> --symbol name` | Find who calls or references a symbol/file. |\n| `codexa callees <repo> --file path` | Find what a symbol/file calls or references. |\n| `codexa dependency-path <repo> ...` | Find a bounded graph path between two files/symbols. |\n| `codexa workflow-path <repo> --query \"...\"` | Trace route, job, manifest, or workflow paths. |\n| `codexa change-plan <repo> --task \"...\" --save-snapshot --invariant \"...\"` | Save a pre-edit plan, dirty baseline, and bounded task invariants. Repeat `--invariant` as needed. |\n| `codexa post-edit-review <repo> --task-id ... --invariant-review '<json>' --artifact-id ...` | Review the final dirty tree against the saved plan, exact invariants, lifecycle budget, and selected ingested run artifacts. |\n| `codexa verification-artifact <repo> --file run-summary.json` | Safely ingest one bounded external live-run manifest and return its immutable artifact ID. |\n| `codexa prove <repo> --task-id ... --artifact-id ...` | Build a proof card using only explicitly selected, state-bound artifacts. |\n| `codexa semantic-index <repo> --provider ...` | Build optional semantic retrieval cache. |\n| `codexa static-analysis <repo> ...` | Import or optionally run external scanner reports. |\n| `codexa eval <repo>` | Run structured retrieval/verification benchmark scenarios. |\n| `codexa github-sync-check <repo>` | Diagnose GitHub source sync readiness. |\n| `codexa github-release <repo>` | Create release notes, tags, and GitHub Release entries. |\n| `codexa serve <repo>` | Start the core MCP context server over stdio; non-core operations remain reachable through `capabilities` (`--tools full` restores every direct tool name). |\n| `codexa serve <repo> --transport http --host 127.0.0.1 --port 8729` | Start loopback-only HTTP MCP. |\n\nMost context commands auto-refresh stale or missing Codexa artifacts before\nanswering. Use `--no-auto-refresh` when you intentionally want to inspect only\nthe stored index.\n\n## What It Understands\n\nCodexa indexes git-visible files and skips common generated or dependency\ndirectories. The source reader is intentionally small and deterministic.\n\nNative parser lanes:\n\n- TypeScript, TSX, JavaScript, and JSX through Tree-sitter plus TypeScript\n  compiler assist.\n- Python through Tree-sitter plus lightweight semantic assist.\n\nShallow deterministic lanes:\n\n- Rust declarations, imports, methods, calls, and tests.\n- Go packages, imports, functions, methods, types, constants, variables, and\n  tests with module-aware import resolution.\n- Java packages, imports, classes, interfaces, enums, records, methods, and\n  direct call-like usage.\n\nLightweight file lanes:\n\n- JSON manifests.\n- Markdown, MDX, RST, and text docs.\n- Shell scripts.\n- Systemd service files.\n\nFacts carry explicit confidence:\n\n- `authoritative`: syntax or git facts Codexa directly read.\n- `derived`: deterministic links, static assists, report-backed relationships,\n  and likely test relationships.\n- `heuristic`: framework hints, string references, dynamic behavior guesses, or\n  risk hints.\n- `fallback`: low-confidence context used only when nothing better is available.\n\nCodexa should never make heuristic-heavy output look stronger than it is.\n\n## Architecture For Engineers\n\nCodexa is a TypeScript package with five main layers.\n\n### 1. Indexing\n\nEntry point: `src/indexer.ts`.\n\nPipeline:\n\n1. Discover git-visible files and dirty state.\n2. Parse source files and reuse the content-hash parse cache where possible.\n3. Import external static-analysis and symbol-report facts.\n4. Apply TypeScript/Python semantic assists.\n5. Resolve imports, usage sites, aliases, test edges, and graph links.\n6. Rank files/modules with centrality, usage, churn, tests, dirty risk, and\n   bounded outcome signals.\n7. Build typed graph edges, workflow traces, functional clusters, and\n   relational packet exports.\n8. Record freshness, parser errors, and dirty hashes.\n9. Publish artifacts atomically.\n\nThe indexer uses a cross-process cache lock so parallel Codexa commands do not\nstampede artifact writes.\n\n### 2. Fact Model\n\nCore types live in `src/types.ts`.\n\nImportant fact types:\n\n- `RepoSnapshot`\n- `File`\n- `Symbol`\n- `UsageSite`\n- `ImportEdge`\n- `TestEdge`\n- `GraphEdge`\n- `WorkflowTrace`\n- `ModuleCluster`\n- `RiskSignal`\n- `ParserError`\n- `SessionMemoryEntry`\n\nImportant graph edge kinds:\n\n- `DEFINES`\n- `IMPORTS`\n- `CALLS`\n- `REFERENCES`\n- `TESTS`\n- `ROUTE`\n- `JOB`\n- `RISK`\n- `ROUTE_HANDLES`\n- `ROUTE_CALLS_STORE`\n- `STORE_DISPATCHES_ADAPTER`\n- `ADAPTER_REFERENCED_BY_MANIFEST`\n- `UI_CALLS_ENDPOINT`\n- `TEST_COVERS_WORKFLOW`\n- `IMPLEMENTS`\n- `EXTENDS`\n- `EXPORTS`\n- `TYPE_EXPORTS`\n\nRelationship claims can include `EdgeEvidenceV1`, which carries edge kind,\nsource, confidence, reason, path/symbol endpoints, optional range, and\nstale/degraded flags.\n\n### 3. Query Layer\n\nPublic query exports live in `src/queries.ts`, intentionally kept as a thin\nbarrel. Implementations live under `src/query/`.\n\nKey query modules:\n\n- `search.ts`: repo maps, raw/BM25/exact/symbol/semantic search, target\n  discovery, raw-exact-vs-ranked anchor reporting, and relational process /\n  cluster packet selection.\n- `context.ts`: `context_pack`, `task_brief`, `focus_brief`, and\n  `session_context`.\n- `impact.ts`: file/symbol blast-radius expansion and verification recipes.\n- `graph-traversal.ts`: callers, callees, and dependency paths.\n- `workflow.ts`: route/job/manifest workflow traces.\n- `change-plan.ts`: pre-edit plans and saved snapshots.\n- `post-edit.ts`: dirty-tree review against saved snapshots.\n- `test-plan.ts` and `tests.ts`: test recommendations and provenance.\n- `verification.ts`: command coverage, command envelopes, and verification\n  ledger entries.\n- `session-memory.ts`: cache-only working memory queries.\n\nQuery sessions (`src/query/session.ts`) carry the repo root, loaded index,\nfreshness, git state, command budget, warnings, provenance, changed files, and\nchanged symbols. Worktree inspection is allowed to degrade; an empty changed-file\nset with degradation warnings means \"unknown\", not \"clean\".\n\n### 4. MCP Server\n\nEntry point: `src/mcp.ts`.\n\nCodexa registers a query-only MCP server. Stdio is the default transport for\nlocal Codex use. Streamable HTTP is available only on loopback addresses unless\nfuture auth/origin policy is added.\n\nThe default core profile advertises three direct tools:\n\n```text\nsearch\nchange_plan\ncapabilities\n```\n\n`capabilities` dispatches every non-core operation through its own schema and\nhandler. Full mode advertises the complete direct-tool surface:\n\n```text\nfreshness\nrepo_map\nfind_context\nsearch\nplaceholder_report\nsymbol_context\nimpact\ndiff_impact\nchange_review\ntest_plan\ntask_brief\ncontext_pack\nfocus_brief\nsession_context\ncallers\ncallees\ndependency_path\nworkflow_path\nchange_plan\npost_edit_review\nproof_card\ncapabilities\nsession_memory\n```\n\nMCP resources expose generated `.codex/codebase/` artifacts. MCP prompts expose\nsmall workflow prompts for impact-before-edit, dirty-diff review, snapshot edit\nloops, and targeted test planning.\n\nMCP tools may update Codexa-generated artifacts or cache state when\nauto-refresh, snapshots, or session memory are enabled. They do not expose a\nsource-editing tool.\n\n### 5. Adapters, Packaging, And Release Tools\n\nAdapters:\n\n- `src/cli.ts`: Commander-based CLI.\n- `src/init.ts`: repo-local MCP config and hook setup.\n- `integrations/claude-code/`: Claude Code plugin, hooks, and slash commands.\n- `plugins/codexa/`: hookless Codex plugin bundle with manifest, skill, and MCP\n  wrapper; repositories initialized with `codexa init` supply the managed Codex\n  hooks separately.\n\nOperational tools:\n\n- `src/doctor.ts`: local readiness checks.\n- `src/github-sync.ts`: git/GitHub sync diagnostics.\n- `src/github-release.ts`: release notes, tags, and GitHub Release flow.\n- `scripts/*.mjs` and `scripts/*.sh`: source hygiene, privacy, package smoke,\n  public snapshot, benchmark, and publish gates.\n\n## Optional Lanes\n\n### Semantic Retrieval\n\nSemantic retrieval is opt-in and cache-based.\n\nBuild the cache:\n\n```bash\ncodexa semantic-index /path/to/project --provider openai\ncodexa semantic-index /path/to/project --provider local-command --command ./embed-jsonl\n```\n\nAfter the cache exists, query commands can use it automatically when the snapshot\nand provider settings match. `--semantic` forces diagnostics, and\n`--no-semantic` disables the lane for one call.\n\nOpenAI uses `OPENAI_API_KEY` and defaults to `text-embedding-3-small`.\n`local-command` receives JSONL on stdin and returns embedding records. Codexa\ndoes not ship a vector database and does not call embedding providers unless the\nsemantic cache/provider path is configured or explicitly forced.\n\n### LSP Assist\n\nLSP assist is read-only and bounded. Enable it with `--lsp` or\n`CODEXA_LSP=1` on supported query commands.\n\nCodexa can query:\n\n- `typescript-language-server --stdio`\n- `basedpyright-langserver --stdio`\n- `pyright-langserver --stdio`\n\nLSP failures are warnings in the packet, not hard failures. LSP never edits\nsource files.\n\n### Static Analysis Reports\n\nCodexa does not vendor Semgrep, CodeQL, ShellCheck, or other scanner engines.\nThe default safe shape is report ingestion:\n\n```bash\ncodexa static-analysis /path/to/project \\\n  --semgrep-report /tmp/semgrep.json \\\n  --codeql-report /tmp/codeql.sarif \\\n  --symbol-report /tmp/codexa-symbols.json \\\n  --scip-report /tmp/index.scip.json\n```\n\nCodexa also accepts a bounded `CodexaSymbolReportV1` JSON document so external\nlanguage tools can feed symbols and relationships into Codexa with `derived`\nconfidence. SCIP reports are accepted as JSON exported by `scip print --json`;\nCodexa converts them into the same bounded symbol-report lane and does not run\nor vendor SCIP indexers.\n\nScanner execution flags such as `--run-semgrep`, `--run-codeql`, and\n`--run-shellcheck` are explicit opt-ins. They run installed local tools under\nscrubbed environments and write reports under `.codex/static-analysis/`.\n\n### AutoVerify Hooks\n\n`codexa init` writes advisory hooks when Codex hooks are available:\n\n- `hook-pre-edit` silently saves an implicit pre-edit baseline when no\n  change-plan snapshot exists. If an invalid/blocked snapshot, degraded\n  worktree, or active writer prevents a reliable baseline, it emits one bounded\n  warning to run explicit `change_plan` with `saveSnapshot=true` before a\n  non-trivial edit.\n- `hook-pre-edit` also blocks when a task's repeated-loop budget has latched a\n  mandatory replan. Lifecycle read or validation failures fail closed with an\n  actionable diagnostic instead of silently disabling the guard.\n- `hook-post-edit` runs a bounded review after edit tools. Because it runs\n  before later shell verification, it does not replace one final\n  `post_edit_review` with the actual verification evidence.\n\nWith read-only autonomy, the post-edit hook performs one review, persists that\noutcome once, and skips AutoVerify candidate derivation entirely. With\nfull-access AutoVerify, it performs a non-persisted preview to select safe\ncommands and one final persisted review enriched with\nthe trusted runner reports. This keeps the two-pass path only where command\nexecution can add evidence.\n\nAutoVerify command execution is disabled unless user-owned autonomy is\n`full-access` or the environment sets `CODEXA_AUTOVERIFY=1` /\n`CODEXA_AUTOVERIFY=true`. Even then, AutoVerify is hook-only. MCP\n`post_edit_review` never spawns commands.\n\nThe general autonomy switch is `CODEXA_AUTONOMY`: `read-only` (aliases\n`readonly`, `off`) or `full-access` (aliases `full`, `bypass` — this grants\nthe same command-execution rights as user-owned full-access autonomy, so\ntreat it like a credential). `CODEXA_AUTOVERIFY` takes precedence when both\nare set, and an unrecognized `CODEXA_AUTONOMY` value fails with an error\ninstead of being silently ignored.\n\nAutoVerify is not a sandbox. Test code still runs locally with the user's file\npermissions. Codexa records whether verification mutated source/test/provenance\nstate and treats such reports as non-covering evidence.\n\n## Source Map\n\n| Path | Purpose |\n| --- | --- |\n| `src/cli.ts` | CLI command registration and option parsing. |\n| `src/indexer.ts` | Main index pipeline orchestration. |\n| `src/indexer/` | Discovery, parsing, graph stage, ranking, freshness, and artifact writing helpers. |\n| `src/parser/` | Tree-sitter and shallow language extraction. |\n| `src/resolver.ts` | Import, alias, usage, and symbol relationship resolution. |\n| `src/graph.ts` | Typed graph and workflow trace construction. |\n| `src/query/` | Query packets, edit planning, post-edit review, test planning, and verification logic. |\n| `src/mcp.ts` | MCP server creation and transport setup. |\n| `src/mcp/` | MCP tool/resource/prompt registration, runtime refresh, result compaction, and session-memory adapter code. |\n| `src/session-memory/` | Cache-only structured working memory store. |\n| `src/semantic-retrieval.ts` | Optional embedding cache build/query lane. |\n| `src/static-analysis.ts` | Static-analysis report import and optional scanner execution. |\n| `src/autoverify.ts` | Hook-only targeted verification runner. |\n| `src/github-sync.ts` | GitHub source-sync diagnostics. |\n| `src/github-release.ts` | GitHub Release and restore-note generation. |\n| `scripts/` | Hygiene, privacy, package, benchmark, and publish checks. |\n| `tests/` | Vitest coverage for indexing, MCP, CLI hooks, session memory, static analysis, packaging, and release helpers. |\n| `docs/architecture/` | Design notes for the context server and session memory. |\n| `integrations/claude-code/` | Claude Code plugin adapter and smoke tests. |\n| `plugins/codexa/` | Codex plugin package. |\n\n## Safety Boundaries\n\nCodexa is deliberately constrained:\n\n- Local-first by default.\n- Query-only MCP surface.\n- No source-mutating MCP tools.\n- No graph database.\n- No vector database.\n- No web UI.\n- No mandatory embeddings.\n- No always-on LSP daemon.\n- No hidden scanner execution.\n- No broad host-specific planning layer.\n- No project-specific private rules in the public setup path.\n\nContext commands can refresh generated `.codex/codebase/` artifacts. Snapshot\nand session-memory tools can write under `.codex/cache/`. Those are Codexa-owned\nstate paths, not source edits.\n\n## Testing And Verification\n\nCommon development commands:\n\n```bash\nnpm run typecheck\nnpm run lint\nnpm run privacy\nnpm test\nnpm run check\n```\n\n`npm run check` runs typecheck, source hygiene, release-path hygiene, privacy,\nClaude Code smoke tests, and the Vitest suite.\n\nRelease-oriented checks:\n\n```bash\nnpm run smoke:package\nnpm run benchmark:ci\nnpm run public:snapshot-check\nnpm run package:hygiene\nnpm run security:check\n```\n\n`security:check` runs the development gate, dependency audit, clean-tree public\nsnapshot verification, package hygiene, and installed-package smoke test. The\npublic snapshot check intentionally refuses a dirty tree so the verified archive\nmatches `HEAD`.\n\n`benchmark:ci` is self-preparing: it runs the same serialized clean-install,\nbuild, core-wiring, receipt, and strict-startup bootstrap used by a fresh\nworktree before measuring hot paths, then opts the SessionStart metric into\nstrict readiness with `--strict-session-start` and measures adoption-scope\nreceipt validation with `--verify-startup-contract`. The adoption metric binds\nthe complete installed dependency tree and built runtime, and fails above five\nseconds. Direct uses of the benchmark remain advisory unless those flags are\nsupplied, so an intentionally unwired fixture can still measure transport cost.\nThis avoids benchmarking an accidentally stale local build without silently\nchanging the benchmark target.\n\nGitHub Actions passes `--threshold-scale 1.5` to give variable shared runners\nbounded headroom without changing the checked-in product targets. Benchmark\nJSON and the job summary report the base target and the effective gate\nseparately, and identify target misses even when they remain inside that\nheadroom. The scale is explicit, applies uniformly, and is capped at `2`.\n\n## Public Proof\n\nCodexa has a structured eval harness:\n\n```bash\nnode dist/cli.js index /path/to/project\nnode dist/cli.js eval /path/to/project --suite all --seed codexa-v1-benchmark\n```\n\nThe eval scores structured query data, not prose. It compares Codexa packets\nagainst raw `rg`/`git status` baselines, tracks recall/precision/test\nrecommendations/context size, and can run ranking experiments without changing\nproduction ranking. The claim is deliberately falsifiable: a scenario fails\noutright if the raw-grep baseline does the job better, and the harness runs in\nCI on every push (`npm run eval:ci` in the check workflow, seeded per commit\nso the synthetic holdouts cannot be overfitted) — \"beats grep on its\nscenarios\" is a gate, not a one-off benchmark.\n\nMeasured results for v0.3.0 (seed `codexa-v030-eval`, full suite, archived\nin [`reports/benchmarks/v0.3.0-eval.json`](reports/benchmarks/v0.3.0-eval.json)):\n\n| Metric | Result |\n| --- | --- |\n| Scenarios passed | 20/20 (2 project, 12 synthetic anti-cheat, 6 historical fixture) |\n| File recall (mean) | 1.00 |\n| Precision@k (mean) | 1.00 |\n| Test recall (mean) | 1.00 |\n| Scenarios where raw `rg`/`git` beat Codexa | 0 |\n| Packet size vs. raw baseline output (mean) | 0.66x |\n| Over-budget packets | 0 |\n\nKnown imperfections in that run, recorded by the harness itself: 2\nfalse-positive impact files and 1 broad-retrieval failure\n(`synthetic-session-context-seedless`) — see the `calibrationSummary` block in\nthe archived report. The previous run is kept at\n[`reports/benchmarks/v0.2.0-eval.json`](reports/benchmarks/v0.2.0-eval.json).\n\nDo not update public benchmark claims without rerunning the eval on the current\ncheckout and current target.\n\n### Agent-level A/B evaluation\n\nThe retrieval gate above does not establish that an agent completes coding\ntasks better with Codexa. The opt-in\n[agent A/B harness](docs/guides/agent-ab.md) uses version-pinned Harbor\nexecution and digest-pinned base images to run the same coding agent and model\nin control and Codexa-treatment arms. A separate no-network verifier produces\nthe binary completion outcome; Codexa does not grade itself.\n\nThe checked-in task is a plumbing pilot, not a product benchmark. Credible\neffect claims require preregistered held-out tasks, paired repetitions, and\ntask-clustered analysis.\n\nThe archived GPT-5.6 Sol plumbing run is intentionally reported even though it\ndoes not demonstrate a Codexa completion benefit. Both arms completed both\nrepetitions (two both-pass pairs; descriptive absolute risk difference 0),\nwhile this easy task showed a large treatment efficiency penalty:\n\n| Mean per run | Control | Treatment | Treatment / control |\n| --- | ---: | ---: | ---: |\n| Verified completion | 2/2 | 2/2 | no difference |\n| Input tokens | 104,448 | 620,053 | 5.94x |\n| Cached input tokens | 86,272 | 552,064 | 6.40x |\n| Output tokens | 3,212 | 6,680.5 | 2.08x |\n| Reported cost | $0.230376 | $0.816392 | 3.54x |\n| Agent time | 87.849s | 164.996s | 1.88x |\n| Controller time | 128.603s | 205.863s | 1.60x |\n| Verifier-counted changed files | 2 | 2 | 1.00x |\n| Verifier-counted changed lines | 62 | 67 | 1.08x |\n\nThis is descriptive evidence from one simple task and two pairs, with no\ntask-clustered interval; it cannot establish a product effect or a causal\nmechanism. The treatment was a complete Codexa-enabled agent bundle, so the\n5.94x input ratio is not evidence of MCP-only causality. Agent-reported\ntreatment setup succeeded in both runs and structured trajectories recorded 13\nCodexa calls, while controls recorded none. Both\ntreatment runs also received a blocking `post_edit_review` inspection warning\nfor changed symbols even though the edited files exactly matched the saved file\nplan. One run made a second review call after supplying initially omitted\ninvariant evidence. That is observed process friction, not demonstrated safety\nvalue.\nThe immutable hashes, arm metrics, fidelity telemetry, and per-run outcomes are\narchived in\n[`reports/benchmarks/v0.10.0-agent-ab-pilot-v7.json`](reports/benchmarks/v0.10.0-agent-ab-pilot-v7.json).\n\nThat v0.10 treatment used the 13-call workflow recorded above. The current\nselective policy intentionally avoids that mandatory call chain. A full\nregistered, held-out experiment has not yet been rerun against the new policy,\nso the archived result remains evidence about the v0.10 treatment rather than\na general efficiency or efficacy claim for the current release.\n\nOne authenticated paired smoke on the same checked-in task provides a narrower\nregression check for the original 5.94x failure. It used Codex CLI 0.144.6,\nGPT-5.6 Sol at high reasoning effort, an ephemeral clean Codex home, identical\nprompts and fresh fixture checkouts, and the locally built core-profile server\nfrom candidate commit `97b84c9` as the treatment's only configured difference:\n\n| One-pair smoke | Control | Current Codexa treatment | Treatment / control |\n| --- | ---: | ---: | ---: |\n| Input tokens | 108,683 | 127,190 | 1.17x |\n| Cached input tokens | 76,032 | 109,568 | 1.44x |\n| Output tokens | 3,065 | 3,551 | 1.16x |\n| Codexa tool calls | 0 | 0 | no difference |\n| Public tests | pass | pass | no difference |\n| Committed hidden-behavior smoke | fail | pass | descriptive only |\n\nThe exact-path treatment correctly took the zero-call route, so the historical\n5.94x input-token regression did not reproduce; observed input overhead was\n1.17x. The treatment also passed all committed behavior cases plus 40 generated\ncases, while this single control run stripped leading/trailing C1 controls\nbefore validation. This is a non-confirmatory one-pair smoke, not a product\neffect estimate: it is not task-clustered, the runner differs by one patch\nversion from the archived experiment, and the ChatGPT-authenticated run emitted\nno comparable provider-cost metric.\n\nThe task now specifies Unicode General Category `Cc` explicitly. The separate\nverifier covers embedded plus leading/trailing C0, DEL, and C1 cases, including\ngenerated edge cases, and validation rejects transient task artifacts before\nhashing. Run a real authenticated provider preflight and validate an\nartifact-clean task tree before spending tokens on a registered experiment.\n\n## GitHub Release Timeline\n\nUse GitHub Releases as the visible source timeline for the current project.\n\nSource sync diagnostic:\n\n```bash\ncodexa github-sync-check /path/to/codexa-checkout\ncodexa github-sync-check /path/to/codexa-checkout --no-network\n```\n\nGitHub Release dry run and real release:\n\n```bash\nnpm run release:github:dry-run -- --tag v0.2.0\nnpm run release:github -- --tag v0.2.0\n```\n\nThe release command generates a changelog-style summary, changed-area summary,\nrestore commands, branch/worktree continuation commands, and forward-only PR rollback commands.\nOfficial releases should come from a clean `main` after the normal GitHub flow\nhas landed.\n\n## Release Automation\n\nRelease Please runs after pushes to `main`. It reads conventional commits,\nopens or updates a release PR with the package version and changelog changes,\nand creates the GitHub Release after that release PR is merged.\n\nThis does not publish npm on every main merge. Normal feature and fix PRs land\non `main` first, Release Please batches releasable changes into its release PR,\nand npm publishing stays downstream of the GitHub Release event.\n\nConfigure a `RELEASE_PLEASE_TOKEN` GitHub repository secret with a personal\naccess token that can create pull requests, tags, and releases. Do not use the\ndefault `GITHUB_TOKEN` for Release Please if npm publishing should happen\nautomatically, because releases created by `GITHUB_TOKEN` do not trigger the\nseparate `release: published` npm workflow.\n\n## npm Package Publishing\n\nThe npm package is published by GitHub Actions after the GitHub Release lane\npublishes a release. The trigger is `release: published`; pushed tags alone do\nnot publish to npm. The workflow checks the released tag, package identity,\nrepository URL, version availability, and `npm run security:check`, then runs:\n\n```bash\nnpm publish --registry https://registry.npmjs.org --access public --tag latest --provenance --ignore-scripts\n```\n\nFor the first public npm release, configure an `NPM_TOKEN` GitHub repository\nsecret with publish access. After the package exists and npm trusted publishing\nis configured, the workflow can remove token-based publishing while keeping the\nsame release gate and `--ignore-scripts` protection.\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.\n\nWhat usually fits:\n\n- Bug fixes with clear reproduction and regression tests.\n- Performance improvements with before/after measurements.\n- Documentation fixes.\n- Targeted improvements to existing commands or MCP tools.\n\nWhat usually does not fit:\n\n- New deep language indexers.\n- New LLM-based analysis layers.\n- Whole-file rewrites for style preference.\n- Heavy dependencies where a small deterministic helper is enough.\n- New source-mutating agent behavior.\n\nRun this before proposing code changes:\n\n```bash\nnpm run check\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 59525,
  "sha": "91b385b6362b85673788fac6fbe95d5c7b48fbdceaa2ca6b657277c665ae5f2b",
  "repo_slug": "mirnoorata/codexa",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mirnoorata_codexa_b2ebf3ef/readme"
}