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-codexLast scanned: 5/30/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-30T15:15:43.443Z",
"npmAuditRan": true,
"pipAuditRan": true
}ai-codex is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by skibidiskib. Generate a compact codebase index for AI assistants — saves 50K+ tokens per conversation. It has 271 GitHub stars.
Yes. ai-codex passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/skibidiskib/ai-codex" and add it to your Claude Code skills directory (see the Installation section above).
ai-codex is primarily written in TypeScript. It is open-source under skibidiskib on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh ai-codex against similar tools.
No comments yet. Be the first to share your thoughts!
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.
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
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 --quiet
git add .ai-codex/
{
"scripts": {
"codex": "npx ai-codex --quiet",
"precommit": "npx ai-codex --quiet && 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/ 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/schema.prisma (or nested under prisma/schema/)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 filesOverride with --schema <path> for either ORM (file extension determines the parser).
| 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. |
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.*, *-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