Mapping Codebases

Generate _MAP.md files that provide a hierarchical view of code structure without reading every file.

Installation

CRITICAL - Use uv for dependency installation in Claude Code:

# In Claude Code environments, ALWAYS use uv with --system flag:
uv pip install --system tree-sitter-language-pack

# Only fall back to pip if uv is not available

Why uv? Claude Code environments have uv pre-installed for efficient package management. Using uv is faster and preferred.

Quick Start

# Generate maps for a codebase
python scripts/codemap.py /path/to/repo

What It Produces

Per-directory _MAP.md files listing:

• Directory statistics (file count, subdirectory count)
• Subdirectories (with links to their maps)
• Symbol hierarchy with kind markers: (C) class, (m) method, (f) function
• Function signatures extracted from AST (Python, partial TypeScript)
• Line number references (:42 format) for direct navigation
• Import previews
• Markdown ToC for .md files (h1/h2 headings only for brevity)
• Other Files section listing non-code files (JSON, YAML, shell scripts, etc.)

Example output:

# auth/
*Files: 5 | Subdirectories: 1*

## Subdirectories
- [middleware/](./middleware/_MAP.md)

## Files

### handlers.py
> Imports: `flask, functools, jwt, .models`...
- **login** (f) `(username: str, password: str)` :15
- **logout** (f) `()` :42
- **AuthHandler** (C) :58
  - **__init__** (m) `(self, config: dict)` :59
  - **validate_token** (m) `(self, token: str)` :72
  - **refresh_session** (m) `(self, user_id: int)` :95

### README.md
- Authentication Module `h1` :1
- Installation `h2` :5
- Configuration `h2` :12

## Other Files
- config.yaml
- setup.sh

Supported Languages

Python, JavaScript, TypeScript, TSX, Go, Rust, Ruby, Java, HTML, Markdown.

Commands

python scripts/codemap.py /path/to/repo                    # Generate maps
python scripts/codemap.py /path/to/repo --skip locale,tests # Skip specific directories
python scripts/codemap.py /path/to/repo --clean             # Remove all _MAP.md
python scripts/codemap.py /path/to/repo -n                  # Dry run (preview)

Skip Patterns

Use --skip to exclude directories that add noise without value:

# Common patterns
--skip locale,migrations,tests              # Django projects
--skip locales,__snapshots__,coverage       # JavaScript projects
--skip target,docs                          # Rust projects

Default skip patterns: .git, node_modules, __pycache__, .venv, venv, dist, build, .next

Workflow Integration

1. Run codemap.py on the target repo first
2. Read _MAP.md at repo root for overview (high-level structure)
3. Navigate to relevant subdirectory maps as needed (drill down)
4. Read actual source files only when necessary

Maps use hierarchical disclosure - you only load what you need. Even massive codebases (1000+ files) stay navigable because each map remains focused on its directory.

Post-Generation: Making Maps Persistent

CRITICAL - After generating maps, integrate them into the development workflow:

In Claude Code Environments (Persistent Repos)

After generating _MAP.md files, ALWAYS update or create the repository's CLAUDE.md file to document the maps:

# Check if CLAUDE.md exists in the repo root
if [ -f CLAUDE.md ]; then
    # Add a section about the code maps (if not already present)
    echo "Found existing CLAUDE.md - will add _MAP.md documentation"
else
    # Create CLAUDE.md with map documentation
    echo "No CLAUDE.md found - will create one with map documentation"
fi

Add this section to CLAUDE.md:

## Code Maps

This repository has navigable code maps generated via the mapping-codebases skill.

### Using the Maps

- Start with `_MAP.md` at the repository root for a high-level overview
- Each directory has its own `_MAP.md` showing:
  - Subdirectory links for hierarchical navigation
  - File-level symbol exports (classes, functions, methods)
  - Import previews
  - Function signatures (Python, partial TypeScript)

### Keeping Maps Fresh

Maps are generated from AST analysis and can drift from source code. To refresh:

```bash
python /path/to/mapping-codebases/scripts/codemap.py .

Consider adding a git pre-commit hook to auto-update maps (see mapping-codebases skill documentation).

**Why this matters:** Claude Code sessions are persistent. Documenting the maps in CLAUDE.md ensures future Claude instances (and developers) know the maps exist and how to use/maintain them.

### In Claude.ai Chat Environments (Ephemeral)

If working in a Claude.ai chat session (web/mobile):

1. **Use the maps immediately** - the session is ephemeral, so use them while they exist
2. **Tell the user** to add instructions to their Project Instructions if they want to use maps in future conversations:

I've generated _MAP.md files for this codebase. Since

...