Codexa

Codexa

Understand the code. See what a change could affect. Check the evidence.

Codexa helps developers and AI coding assistants work on a repository with more context and fewer guesses. It builds a local map of your code, connects files to their dependencies and tests, and produces readable reports about proposed and completed changes.

Think of it as a map and a change checklist for your project. The person—or coding assistant—still drives. Codexa points out the bridge you might want to check before taking the truck across it.

Use it from a terminal, with Codex, Claude Code, or another compatible coding assistant, or in GitHub Actions to help review pull requests. The core needs no API key, hosted account, or database. Codexa is free and MIT-licensed; your AI assistant and any optional hosted services have their own requirements and costs.

Get started · Connect an assistant · Everyday use · GitHub reviews · Troubleshooting · Full reference

Maintainer expectations: Codexa is a focused project maintained by one

person in spare time. Expect replies in days to weeks. Please discuss larger

changes before opening a PR; see Contributing.

What does it actually do?

For example, changing a login timeout can affect more than one number. Codexa can help locate the setting, identify code that uses it, suggest related tests, and flag edits outside the agreed scope. Its findings depend on what it can read and connect in your repository; it cannot predict every runtime behavior.

Codexa supplies context and checks. Your editor or assistant makes the edits, and your project's tests establish whether the behavior works. A green-looking report is useful evidence, not a force field.

Quick start

You need Node.js 22 or newer, npm (included with Node.js), Git, and a local Git repository—the project folder you want to inspect. You do not need to clone Codexa itself or install an AI assistant to use the terminal commands.

1. Install

Run these commands in a terminal:

node --version

git --version npm install -g @mirnoorata/codexa codexa --version

2. Try it on your project

Replace /path/to/project with your repository's actual folder path. Quote the path if it contains spaces. In the examples below, . means “this folder.”

cd /path/to/project

codexa index . codexa repo-map .

index reads the repository and creates the local map. repo-map shows the ranked files and modules. This terminal-only path needs no assistant setup.

Ask a question relevant to your project:

codexa search . --query "login timeout"

This is an example query, not a built-in demo: results depend on your code. For ongoing use, follow the generated-files guidance and choose your assistant setup below.

No global install? Prefix commands with npx -y @mirnoorata/codexa, for example npx -y @mirnoorata/codexa index /path/to/project. npm may download the package; the default indexing itself runs locally.

Connect your coding assistant

Codexa uses MCP (Model Context Protocol), the connection that lets an AI assistant ask external tools for information. The assistant runs the model; Codexa provides repository context. Install and sign in to your chosen assistant separately.

Codex

From your project folder:

codexa init . --agents-md

codexa session-start .

This creates the index, adds the Codexa server to .codex/config.toml, installs Codex startup/edit hooks, and adds a small managed workflow block to AGENTS.md. Omit --agents-md if you want to manage your own agent instructions. If a Codexa plugin already supplies your MCP connection, avoid registering a second server for the same repository.

Open or reload that same project in Codex and trust it when prompted. Project-scoped MCP configuration is loaded only for trusted projects. In Codex CLI, /mcp shows active connections; see the official MCP setup guide.

A successful session-start check confirms observable setup and index state; it cannot prove that an already-running assistant has loaded the server.

Windows: use codexa init . --agents-md --no-hooks for native Windows MCP-only setup. The generated shell hooks require a POSIX environment such as WSL. macOS and Linux can use the standard command above.

Claude Code

For the simplest connection:

codexa init . --claude --claude-md --no-hooks

codexa session-start .

This also writes the server entry to .mcp.json and workflow guidance to CLAUDE.md. Restart Claude Code in that repository and approve the project MCP server if prompted. --no-hooks disables Codexa's Codex hooks; this setup gives Claude tools and instructions, without Claude hooks or slash commands.

Want automatic startup guidance, a review hook, and commands such as /codexa-plan and /codexa-review? Use the bundled Claude Code plugin. Choose either the plugin or the .mcp.json connection above to avoid duplicate servers.

Other MCP clients

Configure a local command server in your client's MCP settings:

{

"mcpServers": { "codexa": { "command": "codexa", "args": ["serve", "/path/to/project", "--auto-refresh"] } } }

Replace the path and adapt the outer configuration format to your client. The client must be able to find codexa and access the repository. It launches the server; serve is not an interactive chat command.

Fresh installs expose three tools: search, change_plan, and capabilities. That small menu is intentional: capabilities provides access to the remaining operations. Use --tools full with init or serve if your client needs every operation listed directly.

The default connection uses a local process. Optional HTTP transport binds only to the local machine; Codexa does not ship a public remote server.

The everyday workflow

Use Codexa when it resolves uncertainty. A small fix in a known file may need only direct inspection and the project's normal tests. No ceremony is required for changing a comma. A change spanning several files benefits more from planning and review.

For a coding assistant, a useful request is:

Find where login timeouts are handled. Use Codexa if the target or impact is

unclear. Before a substantial edit, save a change plan. Make the change, run

the relevant checks, and review the result against the plan. Tell me what

remains unverified.

You can also run that workflow yourself. This example assumes your repository has src/auth.ts; substitute a real file and task:

codexa change-plan . --task "Adjust the login timeout" --file src/auth.ts --task-id login-timeout --save-snapshot

Read the plan, make the edits, and run the checks appropriate to your project. Then review the work before committing, while the edits are still visible as local changes:

codexa post-edit-review . --task-id login-timeout

Report checks you actually ran with --ran-command. For example, only if `npm test` is a real check in your project and you ran it:

codexa post-edit-review . --task-id login-timeout --ran-command "npm test"

That flag records a claim; it does not execute the command. Codexa checks whether the reported command could cover the relevant work. A command that hides failures, such as npm test || true, does not earn credit. Codexa cannot detect a completely fabricated report.

For a formal handoff, codexa prove . --task-id login-timeout summarizes the saved plan, available evidence, and unresolved gaps. Supply actual command reports or selected verification artifacts when the handoff needs them.

Startup and edit hooks reduce manual steps, but their reviews do not replace one final review with the actual test evidence. Detailed workflow, invariants, and repeat-attempt controls are in the reference.

A few useful commands

Run these from the project root, using your own file names and questions:

Most context commands refresh an outdated index automatically. Use codexa --help, codexa --help, or the command reference for more options.

Review pull requests

Codexa can generate a report for a committed branch without an AI assistant. From a clean checkout of that branch, with origin/main available locally:

git fetch origin

codexa review . --base origin/main --head HEAD codexa review . --base origin/main --head HEAD --format json

Replace origin/main if your repository uses a different base branch. Codexa compares changes since the branches' common ancestor. HEAD must match the checked-out commit, and the index must represent that clean checkout.

To add the same review to GitHub Actions:

codexa init . --ci

Review and commit the generated .github/workflows/codexa-review.yml with your normal PR process. It checks out the PR's exact head, uses read-only repository permissions, and writes results to the Actions summary and annotations. It does not post PR comments or run your project's tests. Keep your existing CI.

The default observe mode reports findings without blocking on them. warn adds warning annotations. Explicit fail mode can block on local plan drift, an unavailable requested local plan, or reported command failures. Suggested but unrun tests alone do not fail the review. Invalid inputs and setup errors can fail in any mode.

See committed change receipts for plan comparison, trust limits, and CI options.

What gets written to your repository?

| `