ai-codex: a pre-built codebase index for AI assistants

The context tax ai-codex is trying to remove

Every new conversation with a coding assistant starts the same way. The assistant reads directories, opens files, and builds a model of the project before it can answer anything. The README frames this as the problem: assistants spend thousands of tokens exploring a codebase, and this happens every single conversation. The project's own description puts the cost at 50K+ tokens per conversation, though the README does not show the measurement behind that number.

ai-codex's answer is to do that exploration once, offline, and store the result as small reference files. The intended reader is not a human browsing the repository. It is the assistant itself, instructed to read the index first. The audience is narrow on purpose: teams using Claude Code, Cursor or a similar tool on a TypeScript codebase, where the same structural questions (what routes exist, what a page renders on, what a function is called) come up in every session.

Five markdown files and what each one holds

The generator writes to `.ai-codex/` by default and produces up to five files. `routes.md` groups API routes by resource and lists HTTP methods plus tags such as `[auth,db]`. `pages.md` is a page tree with `[client]` or `[server]` rendering tags. `lib.md` lists library exports as function signatures and classes. `schema.md` captures database fields, primary keys, unique constraints and relationships. `components.md` indexes components with their props, grouped by feature, with a `(c)` marker on client components.

The README states that files which do not apply are skipped, so a project without Prisma gets no `schema.md`. That is a sensible default: an empty file would still cost tokens, and a misleading one would cost more. The format is deliberately terse. A routes entry is a method list, a path and a tag list on one line, which is readable by a model and cheap to include in a prompt.

Installing ai-codex and generating a first index

The README's quick start is a single command run from the project root. It auto-detects the framework, so there is no init step and no config file required to get output.

npx ai-codex

After it finishes, the `.ai-codex/` directory should contain the files that apply to your stack. If you want the index somewhere your assistant already looks, the output directory is a flag:

npx ai-codex --output .claude/codex

Scanning can be narrowed the same way. The README gives `--include` and `--exclude` for directory selection and `--schema` for an explicit schema path. For repeated runs, a config file in the project root replaces the flags:

{
  "output": ".ai-codex",
  "include": ["src", "lib", "app"],
  "exclude": ["tests", "__mocks__"],
  "schema": "prisma/schema.prisma"
}

CLI flags override config file values, so a one-off run does not require editing the file. The package requires Node 18 or later according to `package.json`. To make the index useful, the README instructs you to point your assistant at it: for Claude Code, add a section to `CLAUDE.md` telling it to read `.ai-codex/routes.md`, `pages.md`, `lib.md`, `schema.md` and `components.md` before exploring the codebase. For Cursor and other AI IDEs, the README says to add the `.ai-codex/` directory to the assistant's context or rules file, without prescribing a specific mechanism.

Keeping the index from going stale

A generated index that nobody regenerates is worse than no index, because the assistant will trust it. The README addresses this with three refresh paths. A git pre-commit hook runs the generator quietly and stages the output:

# .git/hooks/pre-commit
npx ai-codex --quiet
git add .ai-codex/

An npm script does the same, and a GitHub Actions example runs `npx ai-codex`, stages `.ai-codex/` and commits only when the staged diff is non-empty. That last detail matters: the documented workflow commits generated files into the repository, which means every contributor's commits can touch the index. The upside is that the assistant gets a current index without a build step. The cost is diff noise and the risk of a merge conflict in a generated file. The README does not document a way to generate the index on demand at conversation time instead of committing it, and it does not document rollback or a dry-run mode.

Where detection stops: frameworks, ORMs and runtimes

Auto-detection is the feature that decides whether this tool fits. The README lists Next.js App Router, Next.js Pages Router, SvelteKit and a generic TypeScript fallback covering `src/`, `lib/`, `utils/` and `components/`. Anything else, a Django project or a Go service, falls outside the supported set, and the README does not claim otherwise.

Schema detection is broader but still enumerated. Prisma is found at `prisma/schema.prisma` or nested under `prisma/schema/`. Drizzle is looked for at a list of paths including `db/schema.ts`, `src/db/schema.ts`, `drizzle/schema.ts` and the SvelteKit convention `src/lib/server/db/schema.ts`, including split-file layouts where the schema path is a directory of TypeScript files. If your schema sits somewhere else, `--schema` takes an explicit path and the file extension selects the parser. There is no generic SQL parser mentioned, so a hand-written migration directory will not produce `schema.md`.

Runtime detection is narrower still. Node.js is the default. Cloudflare Workers is detected for SvelteKit through `adapter-cloudflare` in `svelte.config.js`, or through `wrangler.jsonc` or `wrangler.toml`, and in that case the generator extracts D1, R2 and KV bindings. The README states plainly that Next.js projects are always reported as Node.js, so a Next.js app deployed to Workers gets a Node-shaped index. That is a real limitation for edge-first projects, not a footnote.

A real alternative: asking the assistant to explore on demand

The default workflow for most teams is no index at all. The assistant greps and reads files as questions come up, guided by the repository structure and whatever the tool's own retrieval does. The difference is not accuracy so much as timing and cost. On-demand exploration reads the files that matter for the current question, which can be more precise than a pre-built summary. ai-codex instead front-loads a fixed structural summary that is always present and always the same shape.

That trade favors repositories where the structure is stable and the questions are broad. It works against repositories where the interesting context is in the bodies of a few large files, since a signature list in `lib.md` will not tell an assistant what a function actually does. It also duplicates a capability that some assistants already have: Claude Code and Cursor both offer ways to include reference files, which is exactly how the README proposes wiring the index in. Nothing here replaces retrieval; it changes what the assistant reads first. Note also that the project's own name collides with OpenAI's Codex products in search results, so teams searching for this tool should look for the repository rather than the product name.

Maintenance, licence and the cost of a committed index

The last push to the repository was on 2026-05-30, and the most recent release listed is v1.3.1 from 2026-05-13, a hotfix for `--version`. Before that, v1.3.0 added SvelteKit and Cloudflare Workers support and v1.2.0 added Drizzle ORM support, so the recent release history is framework and ORM coverage rather than core changes. `package.json` declares version 1.3.2, which is ahead of the newest listed release tag.

The dependency surface is small: `tsx` and `typescript` at runtime, `vitest` and `@types/node` for development. That keeps upgrade cost low in the usual sense, but the real maintenance burden is the generated output. Every framework upgrade can change what the scanner sees, and the README does not describe a compatibility matrix beyond the current detection rules. The project is MIT licensed, which permits commercial use and modification; the README notes the project was designed, written and published by Claude Code, and the licence file is the authoritative text. This is not legal advice, and teams with unusual redistribution requirements should read the LICENSE themselves.

Editorial conclusion

Adopt ai-codex if your team runs Claude Code or Cursor against a Next.js or SvelteKit repository and keeps paying the same context tax at the start of every conversation. Skip it if your project is not TypeScript, if your schema lives in an ORM the README does not list, or if you are not willing to commit generated files and keep them fresh. Before rolling it out, run npx ai-codex once and read the five files it writes; if routes.md or schema.md is missing entries you know exist, the index will mislead your assistant rather than help it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. skibidiskib/ai-codex on GitHub