codebase-index

Pre-indexes a Next.js/TypeScript codebase into 5 compact markdown files so AI coding assistants (Claude Code, Cursor, etc.) can skip the "explore the repo" phase that normally burns 10-20 tool calls and tens of thousands of tokens at the start of every conversation.

Usage

npx codebase-index

Or from a local checkout:

node bin/index.js --dir /path/to/your/project

Options:

-d, --dir <path>    Project root to scan (default: current directory)
-o, --out <path>    Output directory (default: .codebase-index)
--claude-md          Append a pointer to CLAUDE.md automatically

This writes 8 files into .codebase-index/:

| File | Contents | |---|---| | index.md | Start here. A manifest: what each file is for, when to read it, and a source fingerprint (file count + latest mtime) so you can tell if the index has gone stale | | routes.md | Every API route (App Router route.ts + Pages Router pages/api), its HTTP methods, and a heuristic auth flag | | pages.md | Full page tree for both routers, with client/server flags and layout/loading/error presence | | lib.md | Every exported function/const/class in lib/, utils/, helpers/, hooks/, services/, with its signature | | schema.md | Prisma models compressed to key fields only (id, unique, relations, required scalars) | | components.md | Every component in components/ and ui/ with its detected props | | flows.md | For every page: the component tree it renders and every API route it calls, matched back to routes.md | | env.md | Every process.env.X variable name referenced in source — never values — cross-checked against .env.example for unused/undeclared vars |

Then add one line to your CLAUDE.md (or run with --claude-md to do it automatically) telling Claude to read these files before exploring the codebase.

How it works

Everything is done with targeted regex/text parsing against the raw source — there's no TypeScript compiler, no AST, no dependencies at all. That's a deliberate trade-off:

• Pro: zero install cost, runs instantly even on large repos, no risk of the parser itself falling out of date with your TS version.
• Con: it's a heuristic, not a type-checker. Unusual patterns (re-exports, higher-order component factories, computed prop types, non-standard route file layouts) can be missed or partially captured. Each generated file says so and points back at the source file.

flows.md in particular is a real (if shallow) static analysis: it parses each page's import statements, resolves them to files on disk, and walks that import graph up to 5 levels deep, collecting every capitalized (component-style) import and every fetch() / axios.*() call it finds along the way — including ones buried inside an imported lib/ helper, not just calls written directly in the page. It does not follow dynamic import(), conditionally-rendered branches, or calls made through a service layer it can't statically resolve (e.g. a generic apiClient.request(config) wrapper) — those show up as "no matching route found" or don't appear at all. Treat it as a fast first pass, not a guaranteed-complete call graph.

Re-run the tool whenever the codebase changes meaningfully (a package.json script or a pre-commit hook works well). The output is fully regenerated each time — never hand-edit the .codebase-index/*.md files, since your edits will be overwritten.

Supported project shapes

• Next.js App Router (app/ or src/app/), including route groups (name), dynamic segments [id], catch-all [...slug], and optional catch-all [[...slug]]
• Next.js Pages Router (pages/ or src/pages/), including pages/api
• Prisma (prisma/schema.prisma or a few common alternate locations)
• Any .ts/.tsx/.js/.jsx project for the lib.md and components.md scanners, even without Next.js

Known gaps (not yet covered)

Being upfront about what this index does not give an agent, so nobody assumes coverage that isn't there:

• Server Actions ('use server' functions) — only route.ts API handlers are indexed; a project using Server Actions for mutations instead has no coverage in routes.md/flows.md yet.
• middleware.ts — centralized auth/redirect logic isn't read, so routes.md's per-file auth heuristic can be wrong for projects that gate access at the middleware layer instead of inside each route.
• package.json scripts and dependencies — not surfaced anywhere; an agent still has to open package.json itself to learn how to run tests/build/lint.
• Shared type definitions (types/, *.d.ts) — referenced by name in lib.md/ components.md signatures but not indexed themselves.
• Inline destructured props — components.md only matches a named XProps type/interface; function Foo({ a, b }: { a: string }) written inline is missed.

None of these are architectural blockers — each would be a new scanner following the same scanX(root) / renderXMd(data) pattern as the existing ones.

Extending it

Each output is a self-contained scanner in src/scanners/, exporting a scanX(root) function that returns structured data and a renderXMd(data) function that turns it into markdown. To support another ORM (Drizzle, TypeORM), duplicate schema.js and swap the parser; to add a new index file, add a new scanner and call it from src/index.js (and add a row to it in src/utils/manifest.js so index.md points to it too).