LLM coding agents perform best when they understand the overall structure of a repository before reasoning about individual files. In most workflows today, agents repeatedly search the codebase, ingest files incrementally, and attempt to reconstruct architecture during reasoning. This costs time, increases token usage, and can reduce accuracy when decisions are made without a clear view of the full system.
CodeMapper provides a deterministic, script-generated navigation map of the repository so that, when injected into context, agents begin with an outline of the entire codebase—modules, entry points, symbols, and dependency wiring—before selecting which files to inspect. This reduces exploration overhead, improves change targeting, and lowers operational cost.
A common pattern is relying on LLMs to generate documentation or summaries of a repository. This introduces an additional failure surface: hallucinated, incomplete, or outdated structural descriptions.
CodeMapper instead uses traditional static analysis and scripted extraction to produce reliable, repeatable documentation artifacts that regenerate automatically after each change. While deterministic generation can be rigid, it guarantees structural accuracy and eliminates documentation drift caused by model-generated summaries.
-
Dependency wiring diagram Import Dependencies sections list concrete imports per module (including third-party dependencies), allowing agents to trace execution and data flow without opening files.
-
Repository boundary coverage Includes non-source project assets relevant to agent workflows (tests, configuration, requirements, README, example configs), enabling agents to understand how to run, validate, and modify the system safely.
-
Machine-parsable structural outline Consistent symbol markers (
[F],[C],[A],[M],[K], etc.) ensure reliable downstream parsing and tool integration. -
Operational navigation categories Quick Navigation sections are aligned with how agents reason about systems (Services/Business Logic, State Management, Configuration, Utilities, Tests).
CodeMapper generates an LLM-optimized structural navigation map containing:
- Codebase summary metrics (files, classes, functions, token estimates)
- Quick Navigation grouped by responsibility (services, auth, utilities, tests)
- Entry points and executable scripts
- Import dependency wiring per module
- Repository tree including configuration and test boundaries
- Class hierarchy overview
- Detailed per-file symbol outlines with consistent machine-parsable markers
These artifacts are designed to be injected into agent context at session start or retrieved dynamically by orchestration tooling.
Generate a navigation map:
python codemap.py --output CODEBASE_STRUCTURE.mdInclude the generated file at the start of agent sessions or load it through your agent orchestration layer so agents begin work with architectural context already available.
CodeMapper is intended to run automatically after repository updates:
- Local workflow: regenerate after feature development
- CI workflow: regenerate on each commit or pull request
- Agent pipelines: rebuild the map between sequential agent tasks so each agent receives an updated structural view
Because generation is deterministic, outputs remain stable and diff-friendly across runs.
- Deterministic structural documentation (no model hallucination)
- Minimal token footprint for agent initialization
- Machine-parsable symbol and dependency extraction
- CI-friendly regeneration keyed to repository state
- Faster, more accurate agent navigation of large codebases
███████╗ ██████╗ ███████╗████████╗███████╗██████╗
██╔════╝██╔═══██╗██╔════╝╚══██╔══╝██╔════╝██╔══██╗
█████╗ ██║ ██║███████╗ ██║ █████╗ ██████╔╝
██╔══╝ ██║ ██║╚════██║ ██║ ██╔══╝ ██╔══██╗
██║ ╚██████╔╝███████║ ██║ ███████╗██║ ██║
╚═╝ ╚═════╝ ╚══════╝ ╚═╝ ╚══════╝╚═╝ ╚═╝
PolyForm Noncommercial License 1.0.0
Copyright (c) 2026 Michael Foster foster@visualfinesse.com
Licensed under the PolyForm Noncommercial License 1.0.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at:
https://polyformproject.org/licenses/noncommercial/1.0.0/
The Software may be used for noncommercial purposes only. Any commercial use of the Software requires a separate commercial license. Please contact foster@visualfinesse.com .
Unless required by applicable law or agreed to in writing, the Software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.