ai-codex

This project was entirely designed, written, and published by Claude Code (Anthropic's AI coding assistant). The concept, implementation, documentation, and examples were all generated in a single conversation session.

Generate a compact codebase index that gives AI coding assistants instant context about your project structure. Instead of wasting 50K+ tokens on file exploration at the start of every conversation, your AI assistant reads a pre-built index and gets to work immediately.

Why

Every time you start a conversation with an AI coding assistant (Claude Code, Cursor, GitHub Copilot, etc.), it spends thousands of tokens exploring your codebase -- reading files, scanning directories, building a mental model. This happens every single conversation.

ai-codex solves this by generating compact, structured reference files that capture:

• Every API route with its HTTP methods
• Every page with its rendering strategy (client vs. server)
• Every library function signature
• Your database schema (key fields, relationships)
• Your component tree with props

The result: 5 small files that replace 50K+ tokens of exploration, every time.

Quick Start

Run it in your project root:

npx ai-codex

That's it. It auto-detects your framework and generates the index.

Output

By default, files are written to .ai-codex/ in your project root:

File	What it contains
routes.md	API routes grouped by resource, with HTTP methods
pages.md	Page tree with client/server rendering tags
lib.md	Library exports -- function signatures, classes
schema.md	Database schema -- key fields, FKs, relationships
components.md	Component index with props, grouped by feature

Files that don't apply are skipped (e.g., no schema.md if you don't use Prisma).

Configuration

CLI Flags

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

Config File

Create a codex.config.json in your project root:

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

CLI flags override config file values.

Output Format Examples

routes.md

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

## orders
GET,POST     /api/orders [auth,db]
GET          /api/orders/:id [auth,db]
POST         /api/orders/:id/refund [auth,db]

pages.md

[client]   /                                                  HomePage
[server]   /products                                          ProductsPage
[client]   /products/:id                                      ProductDetailPage
[server]   /cart                                               CartPage
[client]   /checkout                                           CheckoutPage

lib.md

## lib
cart-utils.ts
  fn calculateTotal
  fn applyDiscount
  fn formatPrice
auth.ts  fn validateSession
stripe.ts  fn createPaymentIntent

schema.md

## Product
  id                     String    PK
  categoryId             String
  -> Category, OrderItem[], Review[]

**Order** id(PK) | userId | status -> User, OrderItem[]
**User** id(PK) | email(UQ) -> Order[], Review[]

components.md

## components
(c) CartDrawer  items, onRemove, onCheckout
(c) ProductCard  product, onAddToCart
    PriceDisplay  amount, currency
(c) SearchBar  onSearch, placeholder

Integration with AI Assistants

Claude Code

Add this to your CLAUDE.md:

## Codebase Index
Pre-built index files are in `.ai-codex/`. Read these FIRST before exploring the codebase:
- `.ai-codex/routes.md` -- all API routes
- `.ai-codex/pages.md` -- page tree
- `.ai-codex/lib.md` -- library exports
- `.ai-codex/schema.md` -- database schema
- `.ai-codex/components.md` -- component tree

Cursor / Other AI IDEs

Add the .ai-codex/ directory to your AI assistant's context or rules file. Most AI coding tools support a way to include reference files.

Auto-Refresh

Git Pre-Commit Hook

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

npm Script

{
  "scripts": {
    "codex": "npx ai-codex --quiet",
    "precommit": "npx ai-codex --quiet && git add .ai-codex/"
  }
}

CI/CD

# GitHub Actions example
- name: Update codebase index
  run: npx ai-codex
- name: Commit index
  run: |
    git add .ai-codex/
    git diff --cached --quiet || git commit -m "chore: update codebase index"

Supported Frameworks

Framework	Auto-detected	What it scans
Next.js (App Router)	Yes	app/ or src/app/ (api/**/route.ts, **/page.tsx), lib/, components/
Next.js (Pages Router)	Yes	pages/ or src/pages/ (api/**/*.ts, **/*.tsx excl. _app/_document/_error), lib/, components/
SvelteKit	Yes	src/routes/ (+server.ts routes, +page.svelte pages), src/lib/, components
Generic TypeScript	Yes	src/, lib/, utils/, components/

Schema sources are auto-detected from multiple ORMs:

• Prisma at prisma/schema.prisma (or nested under prisma/schema/)
• Drizzle 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, or src/lib/server/db/schema.ts (SvelteKit convention) — including split-file layouts where <base>/schema/ is a directory of .ts files

Override with --schema <path> for either ORM (file extension determines the parser).

Supported Runtimes

Runtime	Auto-detected	What it detects
Node.js	Yes (default)	Standard Node project
Cloudflare Workers	Yes (SvelteKit)	adapter-cloudflare in svelte.config.js, or wrangler.jsonc/wrangler.toml — extracts D1, R2, KV bindings. Next.js projects are always reported as Node.js.

What Gets Skipped

• node_modules/, .next/, dist/, build/, .git/, .worktrees/, __pycache__/, .turbo/, .cache/, coverage/, .nyc_output/, .parcel-cache/, and ai-codex's own output (.ai-codex/, .claude/)
• .d.ts declaration files, .map source maps, .min.js / .min.css minified files
• Backup files (*.backup.*, *-backup-*)
• shadcn/radix UI primitives (button, dialog, etc.) in components/ui/

Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b my-feature
3. Make your changes
4. Test on a real project: cd /path/to/your/project && npx tsx /path/to/ai-codex/src/generate-codex.ts
5. Submit a pull request

Ideas for Contributions

• Support for more frameworks (Remix, Astro)
• Support for more ORMs (TypeORM, Knex)
• Watch mode (--watch) for continuous regeneration
• Token count estimation in output
• Support for Python projects (FastAPI, Django)

License

MIT