mapping-codebases

npx skills add majiayu000/claude-skill-registry --skill mapping-codebases-oaustegard-claude-skills-0a4fd9b3 --agent claude-code

Same command for any agent — swap --agent for codex, cursor, copilot.

# 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:** ```bash # 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 ```bash # 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: ```markdown # auth/ *Files: 5 |

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
Generate maps for a codebase
python scripts/codemap.py /path/to/repo
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)
Common patterns