by skibidiskib
Generate a compact codebase index for AI assistants — saves 50K+ tokens per conversation
# Add to your Claude Code skills
git clone https://github.com/skibidiskib/ai-codexThis 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.
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.
Run it in your project root:
npx ai-codex
No comments yet. Be the first to share your thoughts!
That's it. It auto-detects your framework and generates the index.
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).
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
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.
## 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]
[client] / HomePage
[server] /products ProductsPage
[client] /products/:id ProductDetailPage
[server] /cart CartPage
[client] /checkout CheckoutPage
## lib
cart-utils.ts
fn calculateTotal
fn applyDiscount
fn formatPrice
auth.ts fn validateSession
stripe.ts fn createPaymentIntent
## Product
id String PK
categoryId String
-> Category, OrderItem[], Review[]
**Order** id(PK) | userId | status -> User, OrderItem[]
**User** id(PK) | email(UQ) -> Order[], Review[]
## components
(c) CartDrawer items, onRemove, onCheckout
(c) ProductCard product, onAddToCart
PriceDisplay amount, currency
(c) SearchBar onSearch, placeholder
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
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.
# .git/hooks/pre-commit
npx ai-codex
git add .ai-codex/
{
"scripts": {
"codex": "npx ai-codex",
"precommit": "npx ai-codex && git add .ai-codex/"
}
}
# 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"
| Framework | Auto-detected | What it scans |
|-----------|:------------:|---------------|
| Next.js (App Router) | Yes | app/api/**/route.ts, app/**/page.tsx, lib/, components/ |
| Next.js (Pages Router) | Yes | pages/api/**, pages/**, lib/, components/ |
| Generic TypeScript | Yes | src/, lib/, utils/, components/ |
Prisma schema is auto-detected at prisma/schema.prisma.
node_modules/, .next/, dist/, build/, .git/.d.ts declaration files, .map source maps, .min.js minified files*.backup.*, *-backup-*)components/ui/git checkout -b my-featurecd /path/to/your/project && npx tsx /path/to/ai-codex/src/generate-codex.ts--watch) for continuous regenerationMIT