ai-codex

](https://claude.ai/code) [ [](https://www.typescriptlang.org/)

This project was entirely designed, written, and published by [Claude Code](https://claude.ai/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:

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]