repodex

Give AI your entire codebase in 1% of the tokens.

Run one command, get a compressed codemap (tech stack, file tree, signatures, call graph) injected into CLAUDE.md.

#What the AI sees

# Overview

package.json:
  stack: react, vite, ts, tailwind
  scripts: dev, build, test
tsconfig.json: target: ES2020, paths: { "@/*": "./src/*" }
vite.config.ts: plugins: @vitejs/plugin-react

# File Tree

├── src/
│   ├── auth/
│   │   ├── login.ts
│   │   └── session.ts
│   ├── components/ImageViewer/index.tsx   ← single-child chains collapse
│   ├── knowledge/
│   │   └── [name]/index.md ×40            ← isomorphic sibling dirs fold to one pattern
│   ├── logs/
│   │   └── [id].json ×128                 ← machine-named files fold to a pattern
│   └── fixtures/
│       └── .json ×29                      ← large dirs fold by extension

# Signatures

<file path="src/auth/login.ts">
export async function login(email: string, password: string): Promise<Session>
export async function logout(sessionId: string): Promise<void>
</file>

No more "let me first explore your project structure." The AI just works.

#Setup

npm i -D repodex       # npm
pnpm add -D repodex    # pnpm
bun add -D repodex     # bun

npx repodex            # scan, compress, inject into CLAUDE.md

First run detects existing AI context files (CLAUDE.md, AGENTS.md, .cursorrules, etc.), adds injection markers, and writes repodex.config.ts.

#Configuration

// repodex.config.ts
import { defineConfig } from 'repodex'

export default defineConfig({
    // Which files to scan (root config files like package.json are always included)
    include: [
        'src/**',
    ],
    // Files to skip
    ignore: [],
    // How much detail per file: 'tree' = name only, 'compact' = signatures, 'full' = source
    fileDetailLevel: {
        // 'src/components/ui/**': 'tree',
    },
    // What gets injected into CLAUDE.md
    injectDetailLevel: 'tree',
    // Which files to inject the codemap into
    injectTargetFiles: ['CLAUDE.md', 'AGENTS.md'],
    // Inject call graph commands (context/impact/changes) into target files
    injectCallGraphInstructions: true,
    // Max tokens — keeps output within budget by auto-downgrading less important files
    maxTokens: 5_000,
})

#Smart allocation

When maxTokens is set, repodex scores every file by git recency and import centrality, then auto-downgrades low-signal files (compact → tree → drop) to fit the budget. High-traffic, recently-changed files keep full signatures.

#Call graph

Subcommands build the call graph on each invocation, always reflecting the latest code:

npx repodex context <symbol>   # who calls this? what does it call?
npx repodex impact  <symbol>   # what breaks if I change it? (risk-rated BFS)
npx repodex changes            # which symbols are touched by current git diff?

All support --json for structured output. These commands are auto-injected into CLAUDE.md so the AI uses them before modifying code.

#Watch mode

npx repodex --watch    # re-generate on file changes

#Vite plugin

import { repodex } from 'repodex/vite'
// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
    plugins: [repodex()],
})

When the dev server starts, repodex runs in watch mode alongside it — every source file or repodex.config.ts change re-injects the codemap. Shuts down with the dev server.

#License

MIT