codemap

Single-file Python tool that maps the architecture of a C++/CMake project into machine- and LLM-readable form, with a GUI for browsing.

Point it at a directory; get back a structured description of every class, method, inheritance edge, and build target.

What it extracts

• Files and includes — every source file, with includes resolved against in-tree headers
• Classes — full inheritance graph with public/protected/private inheritance
• Methods — signatures, return types, parameters, plus virtual / override / static / const / pure-virtual flags
• Fields — with types and access modifiers
• Composition — what classes a class holds as members
• Friends — friend class X declarations
• Call graph — who calls whom, qualified by namespace and class
• CMake build graph — targets, sources, link dependencies, find_package calls

Five export formats:

File	Purpose
map.json	Complete graph as JSON
architecture.md	Human-readable structure report
codemap_llm.txt	Compact format for pasting into LLM prompts
codemap.dot	Graphviz file (dot -Tsvg ... -o map.svg)
architecture.txt	Plain text version of the report

Install

Nothing to install. One Python file, stdlib only.

git clone https://github.com/Oveissheibani/codemap.git
cd codemap
python3 codemap.py

Requires Python 3.8+ and tkinter for the GUI (ships with standard CPython; on minimal Linux: apt install python3-tk).

Usage

GUI

python3 codemap.py

A welcome window opens with a folder picker. Pick your project, and the GUI builds the map and opens a browser with four tabs: file tree with per-file detail, CMake targets, an interactive dependency graph, and an overview. Save any export from File → Export.

CLI

python3 codemap.py /path/to/project              # build map and open GUI
python3 codemap.py /path/to/project --cli        # build only, no GUI
python3 codemap.py /path/to/project --no-semantic   # skip deep analysis (faster)

Output lands in <project>/_codemap/.

License

MIT — see LICENSE.