ai-codex trades a codebase walk for five markdown files

Five markdown files replace the exploration pass

The pitch is a token budget. Every time a conversation starts with an assistant, thousands of tokens go into reading files and building a mental model of the repository, and the README states that this happens on every single conversation. ai-codex writes a compact structured reference instead, and claims that five small files stand in for more than fifty thousand tokens of exploration.

What goes in the five files is fixed. `routes.md` holds every API route with its HTTP methods. `pages.md` holds every page with its rendering strategy, client or server. `lib.md` holds library exports, function signatures and classes. `schema.md` holds the database schema with key fields, foreign keys and relationships. `components.md` holds the component tree with props.

Files that do not apply are skipped, and the README gives the example: no `schema.md` at all if the project does not use Prisma. So the count is an upper bound rather than a promise, which is the right way round for an index meant to be read on every request.

One command, and the framework is detected for you

Run it in the project root:

npx ai-codex

There is nothing to configure before that. The tool detects the framework, works out where the routes and pages live, and writes into `.ai-codex/` in the project root by default. The package itself is small in the way that matters for a tool you run on every commit: the executable is `bin.js`, the generator entry is `src/generate-codex.ts`, and the only runtime dependencies are tsx and TypeScript.

The detection table covers four shapes, all automatic. Next.js with the App Router reads `app/` or `src/app/`, taking `api/**/route.ts` and `**/page.tsx` alongside `lib/` and `components/`. Next.js with the Pages Router reads `pages/` or `src/pages/`, taking `api/**/*.ts` and any `.tsx` except `_app`, `_document` and `_error`. SvelteKit reads `src/routes/` for `+server.ts` routes and `+page.svelte` pages, plus `src/lib/`. Generic TypeScript projects fall back to `src/`, `lib/`, `utils/` and `components/`.

Flags override codex.config.json, and only four are documented

The four flags cover the decisions people reach for first:

npx ai-codex --output .claude/codex     # custom output directory
npx ai-codex --include src lib           # only scan these directories
npx ai-codex --exclude tests __mocks__   # skip these directories
npx ai-codex --schema prisma/schema.prisma  # explicit schema path

The same four keys exist in a `codex.config.json` in the project root, and the precedence is stated plainly: CLI flags override config file values. The file form carries arrays:

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

A fifth flag shows up in every example of keeping the index fresh and is not in that list: `--quiet`. Since v1.3.1 was released as a hotfix for `--version`, there is at least one more working flag outside the documented set, which is worth knowing before you conclude a flag is unsupported.

routes.md and pages.md are lists, not prose

The output format is deliberately terse, because terseness is the point. Routes are grouped by resource, with the methods aligned in a column and the middleware or dependencies in brackets:

## products
GET,POST     /api/products [auth,db]
GET,PUT,DELETE /api/products/:id [auth,db]
POST         /api/products/:id/images [auth]

Pages get a rendering tag and a component name on one line each, which is what lets an assistant know before opening a file whether it is client or server code:

[client]   /                                              HomePage
[server]   /products                                          ProductsPage
[client]   /products/:id                                      ProductDetailPage

The other three files follow the same shape. `lib.md` groups exports by file with function names under each. `schema.md` gives a field list per model with primary key markers and arrow references to related models, and also has a compact one line form for smaller schemas. `components.md` marks components with a letter and lists their props. No file contains prose, which is why an assistant can read all five cheaply.

Schema detection is a list of paths, and the extension picks the parser

The database file is found by convention rather than by configuration, and the search list is long for Drizzle. Prisma is looked for at `prisma/schema.prisma`, including the nested layout under `prisma/schema/`. Drizzle is looked for at `db/schema.ts`, `src/db/schema.ts`, `lib/db/schema.ts`, `src/lib/db/schema.ts`, `app/db/schema.ts`, `src/app/db/schema.ts`, `database/schema.ts`, `drizzle/schema.ts`, and `src/lib/server/db/schema.ts`, which is called out as the SvelteKit convention. Split file layouts count too, where the base schema path is a directory of `.ts` files rather than one file.

Both ORMs can be overridden with `--schema <path>`, and the note about which parser runs is short: the file extension decides. That is a sensible rule for a tool with two supported schemas, and it also means the override is only as good as the extension you point it at.

What is extracted from the schema is structural rather than semantic: key fields, primary and foreign keys, and relationships. Enum values, indexes and generated columns are not mentioned anywhere in the visible documentation, so treat the schema file as a map rather than a data dictionary.

Cloudflare Workers is only visible through SvelteKit signals

Two runtimes are recognised. Node.js is the default and needs no signal beyond being a Node project. Cloudflare Workers is detected, but only as a SvelteKit thing: the marker is `adapter-cloudflare` in `svelte.config.js`, or a `wrangler.jsonc` or `wrangler.toml` file in the project. When it fires, the tool extracts D1, R2 and KV bindings, which is the part that matters for an assistant reasoning about what a worker function can actually reach.

The limitation is stated in the same row: Next.js projects are always reported as Node.js, whatever their deployment target. So a Next.js app on Workers is indexed as Node, and its bindings are not extracted.

There is no entry for any other runtime. The table has two rows, and the second one is conditional on a SvelteKit marker, so an edge or container deployment outside those two shapes is simply not described to the assistant by this tool.

The skip list decides what your index will never mention

An index is only as good as its exclusions, and this one is explicit. Build and cache directories are skipped: `node_modules/`, `.next/`, `dist/`, `build/`, `.git/`, `.worktrees/`, `__pycache__/`, `.turbo/`, `.cache/`, `coverage/`, `.nyc_output/` and `.parcel-cache/`. So is the tool's own output, both `.ai-codex/` and `.claude/`, which matters because an index of an index would be circular.

Generated artefacts are skipped as well: `.d.ts` declaration files, `.map` source maps, and `.min.js` and `.min.css` bundles. So are backup files matching `*.backup.*` or `*-backup-*`. And UI primitives from shadcn or radix inside `components/ui/` are left out, on the reasoning that button and dialog components are noise next to your own.

That last exclusion is the one to check against your own tree. If a project keeps real behaviour in `components/ui/`, those files will be missing from the index with no marker saying so. Nothing in the output format records what was skipped, so the index looks complete either way.

Version 1.3.2 sits one ahead of the newest tag

The tags tell a fast story: v1.2.0 added Drizzle ORM support on 26 April 2026, then v1.3.0 and v1.3.1 both landed on 13 May 2026, one adding SvelteKit and Cloudflare Workers and the other a hotfix for `--version`. The package file then declares version 1.3.2, which is one higher than anything tagged, and the default branch last moved on 30 May 2026. So the published artefact and the working tree are already a patch apart, which matters if you pin a version and expect the Cloudflare binding extraction your version might not have.

Two packaging details are odd enough to notice. The `main` field points at `src/generate-codex.ts`, a TypeScript source file, so anything resolving the package as a library rather than as a command would need a TypeScript loader. And TypeScript is a runtime dependency rather than a development one, alongside tsx, which is consistent with running the source through tsx at execution time.

The repository also commits its own `.ai-codex/` output at the root, next to `SPEC.md`, `FORMAT.md` and `tests/`, which is the project dogfooding the index it sells. The author field in the package file is empty, and the README states that the concept, implementation, documentation and examples were all generated by Claude Code in a single conversation session.

Editorial conclusion

Fit for a TypeScript or Next.js repository where an assistant re-explores the same routes on every session and you are willing to commit generated markdown that then has to be kept in step with the code. Less fit for a mixed monorepo, since the framework detection covers one Next.js app, one SvelteKit app or generic TypeScript directories, and the schema parser is chosen by file extension. Before adopting it, decide who regenerates the index and when, since a stale index is worse than no index for a tool whose only job is to be trusted first, and check whether the skip list is excluding files you actually want described.

Frequently asked questions

Official sources

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