code-mapper

Overview

code-mapper is a zero-dependency Python CLI that scans a project directory and produces a single PROJECT_CONTEXT.md — a structured snapshot containing a file tree, Mermaid class diagram, module dependency graph, and a ranked symbol index. It replaces the costly pattern of an LLM reading every source file to orient itself, cutting that token spend by 72–85%. Built for developers who use LLM coding assistants daily and want to stop “paying” for orientation on every session.

Key Features

• Generates four sections in one pass: file tree, class diagram, dependency graph, and symbol index
• 72–85% token reduction vs reading raw source files (benchmarked across projects from 800 to 4,600 lines)
• Python files parsed with the built-in ast module for exact output; 9 other languages supported via regex
• Works as a standalone script or as a Claude Code subagent (@code-mapper map this project)
• Zero dependencies — Python 3.9+ stdlib only
• Supports --stdout for preview/piping and sub-directory mapping for large monorepos

Technical Decisions

Mermaid was chosen as the diagram format because it is the most token-dense visual representation modern LLMs understand natively — roughly 2× cheaper than PlantUML and 24× cheaper than draw.io XML for the same diagram. Python uses the ast module for exact, typed output including docstrings and @dataclass/@abstractmethod detection; all other languages fall back to regex, which handles standard code patterns reliably without pulling in any third-party parser. The symbol index covers what diagrams can’t — exact function signatures that let an LLM call the right methods without reading implementations.