Codemap

Generate a structured index of every export in the codebase so you can find existing functionality before writing new code.

Why this exists

AI assistants frequently rewrite functions that already exist in a codebase. They search for files by name or grep for keywords, but miss things because they don't know what's available. A codemap solves this by building a searchable index of every exported function, type, constant, and component. Instead of reading the whole index, you grep it for related terms before writing new code.

What it produces

A CODEMAP.md file at the project root containing:

• Every exported function with its signature
• Every exported type, interface, enum, class, and constant
• Grouped by package/directory with a table of contents
• Summary stats (total files, exports, functions, types, etc.)

How to generate

Step 1: Detect project structure

Look for source directories. Common patterns:

• Monorepo: packages/*/src, apps/*/src, libs/*/src
• Single package: src/
• Next.js: auto-detected via next.config.{js,mjs,ts}, scans entire project root
• Check pnpm-workspace.yaml or workspaces in package.json for workspace roots

Identify the language:

• TypeScript/JavaScript: .ts, .tsx, .js, .jsx files
• Python: .py files
• Go: .go files
• Rust: .rs files

Step 2: Run the generator script

The bundled script handles TypeScript, JavaScript, Python, Go, and Rust projects:

node .claude/skills/codemap/scripts/generate.mjs

The script:

• Walks all source directories
• Extracts exports via regex (no dependencies needed)
• TypeScript/JavaScript: functions, async functions, generators, arrow functions, types, interfaces, enums (including const enum), classes (including abstract), constants, namespaces, React components, re-exports, declare modifiers, multi-line signatures
• Python: functions (def, async def), classes, UPPER_CASE constants, __all__ filtering, _private exclusion, docstring handling
• Go: exported functions (capitalized), methods with receivers, struct/interface types, grouped const/var/type blocks, return types
• Rust: pub fn/pub async fn/pub unsafe fn, structs, enums, traits, type aliases, constants, statics, modules, pub use re-exports, pub(crate)/pub(super) filtering
• Skips tests, dist, node_modules, build artifacts, __pycache__, venv, vendor, target/, block comments
• Auto-detects project type from package.json, pyproject.toml, go.mod, Cargo.toml
• Groups files by package/directory
• Writes CODEMAP.md to project root

If the script fails or your language isn't supported, fall back to Step 2b.

Step 2b: Manual generation (any language)

If the bundled script doesn't fit the project, generate the map manually:

1. Use Glob to find all source files (exclude tests, build output, vendor)
2. Use Grep to find export patterns:
   • TypeScript/JS: ^export (function|const|type|interface|class|enum|default)
   • Python: ^(def |class |__all__) in non-test files
   • Go: ^func [A-Z] (exported = capitalized)
   • Rust: ^pub (fn|struct|enum|trait|type|const|mod)
3. For each file with exports, record the file path and list of exports
4. Group by directory/package
5. Write CODEMAP.md using the format below

Output format

# Codemap

> Auto-generated. Do not edit manually.
> Last updated: YYYY-MM-DD

## Packages

- [package-name](#anchor) (N files)

---

## package-name

### `path/to/file.ts`
- fn **functionName** (param1, param2)
- type **TypeName**
- const **CONSTANT_NAME**

---

## Stats

- **Files**: N
- **Total exports**: N
- **Functions**: N
- **Types**: N

Step 3: Add to .gitignore

CODEMAP.md is a local development artifact. Add it to .gitignore:

echo "CODEMAP.md" >> .gitignore

Step 4: Add a convenience script (optional)

If the project has a package.json, add a script:

{
  "scripts": {
    "codemap": "node .claude/skills/codemap/scripts/generate.mjs"
  }
}

Step 5: Add the rule to project instructions

Add these lines to the project's CLAUDE.md (or equivalent AI instructions file) under rules or conventions:

## Codemap

`CODEMAP.md` is an auto-generated index of every exported function, type, constant, and component in this codebase. It exists so you can find existing code before writing duplicates.

- At the start of each session, regenerate it: `node .claude/skills/codemap/scripts/generate.mjs`
- Before writing new code, grep `CODEMAP.md` for related terms to check if the functionality already exists. Do NOT read the entire file.
- Example: before writing a date formatter, run `grep -i "format\|date\|time" CODEMAP.md`
- If `CODEMAP.md` doesn't exist yet, run the generate command first.

If no CLAUDE.md exists, create one with these rules.

Why grep, not read: On large codebases CODEMAP.md can be thousands of lines. Loading it wholesale wastes context. Targeted grep against it gives you exactly the exports you need without the noise.

When to regenerate

• Always at the start of a new coding session (this is the primary trigger)
• After adding new files or significant refactoring
• When the user asks to update/refresh the map

Customization

The generator script uses these defaults that may need adjustment per project:

Source directories: Auto-detected from workspace config. Override by editing the SOURCE_DIRS array in the script.

Skip patterns: Tests (__tests__, .test., .spec.), build output (dist, .next, build), node_modules. Add project-specific patterns (e.g., generated code, vendor) to SKIP_PATTERNS.

Grouping: Files are grouped by top-level directory. For monorepos, the script groups by package name. Adjust getPackageLabel() for custom grouping.