CodeMap

The problem

Every coding-agent session starts by rediscovering the same thing: what is in this repository, where does it live, what calls what. That rediscovery is search, and search is the single most expensive thing an agent does: dozens of file reads and greps, paid for at full token price, producing an understanding that is thrown away when the session ends. Then the next session pays for it again.

The obvious fix is to write the map with an LLM. That trades one problem for a worse one.

What was built

A static analyzer that reads the codebase and emits a deterministic markdown atlas: summary metrics, category-grouped navigation, entry points, per-module import wiring, a file tree, the class hierarchy, and a symbol outline. An agent loads it once at the start of a session instead of searching.

The atlas reports its own cost back to the reader, in the file:

This navigation map is ~375 tokens. Include it in every session to avoid expensive codebase searches.

Against a real C# backend it extracted 52 files, 55 classes and 242 methods.

The decision that matters

No language model touches the map. The README states the reason plainly: LLM-generated documentation "introduces an additional failure surface: hallucinated, incomplete, or outdated structural descriptions."

A map that is confidently wrong is worse than no map, because the agent trusts it and searches nowhere else. So Python goes through the standard library's ast parser: exact class bases, decorators, annotated assignments, entry points detected by inspecting the comparison node rather than matching text. Twenty-three other languages fall back to hand-written extractors, and the docstring says so rather than implying uniform fidelity.

The output is deterministic. Directory walks sort. The tree sorter uses a fixed key placing dunder names first, then private, then digit-leading, then alphabetical. Import wiring and entry points sort by path. Three consecutive runs over the same corpus produce byte-identical files, verified by md5, and still identical after stripping the generated timestamp.

That determinism is what makes it usable in a pipeline. A map that reshuffles on every run produces noisy diffs, and a noisy diff is one nobody reads.

Zero dependencies. Standard library only, in a tool whose whole purpose is to be cheap to run everywhere.

Where it stands

Public on GitHub. It runs, and its output is stable and correct. It is not packaged for distribution (no release, no CI), and the categorisation logic has a known sharp edge worth recording: path segments are matched by exact keyword below four characters and by prefix above it, specifically to avoid matching orm inside format. The docstring names that bug because it was hit.