Most codebases are cities. Cogmap is the satellite view.
Cogmap is a Python CLI tool that parses a codebase, builds a weighted dependency graph with graph-theory metrics, and exports it as an interactive cognitive map.
It's not just "AST → diagram." It's "make large systems understandable."
- 🔍 Deep parsing — modules, classes, functions, imports, call graph (static)
- 📊 Graph metrics — degree centrality, betweenness centrality, fan-in/fan-out
- 🌡 Cognitive heatmap — color nodes by criticality (red = core, blue = leaf, gray = dead)
- 🏗 Architectural smell detection — God modules, circular imports, dead modules, high fan-in
- 📦 Multiple export formats:
- Interactive HTML (D3.js, click nodes for details)
- Mermaid diagram
- JSON graph (for further tooling)
We recommend using a modern Python tool manager like uv or pipx to install cogmap in an isolated environment.
uv tool install cogmap
# Or run directly without installing
uvx cogmap analyze ./my_projectpipx install cogmappip install cogmap
# or from source:
git clone https://github.com/yourusername/cogmap
cd cogmap && pip install -e .# Analyze a project
cogmap analyze ./my_project
# Export interactive HTML map
cogmap export --format html
# Export Mermaid diagram
cogmap export --format mermaid
# Show stats + smell report
cogmap stats
# Options
cogmap analyze ./project --ignore tests,migrations --collapse-stdlib --depth 3| Format | Description |
|---|---|
cogmap.html |
Interactive D3.js force graph, click nodes for stats |
cogmap.md |
Mermaid diagram, paste into mermaid.live |
cogmap.json |
Raw graph JSON for further tooling |
-
cogmap explain <file>— AI-powered module summarization - JavaScript/TypeScript parser
- Graphviz / PlantUML exporters
- Git blame overlay (who owns what)
MIT