ai-codex

[](https://claude.ai/code)

[](LICENSE)

[](https://www.typescriptlang.org/)

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:

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
git add .ai-codex/

npm Script

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

CI/CD