ReadMenator

A token-free, offline, production-grade polyglot codebase knowledge graph & architectural analyzer.

No LLMs. No tokens. No cloud costs. Pure static analysis via AST + regex.

ReadMenator builds production-grade codebase knowledge graphs and architectural health reports 100% offline. Identify structural risks, security flaws, and change impact patterns instantly across 19 languages.

https://github.com/user-attachments/assets/af357bca-fd48-4ef7-a1bb-43b39c51af58

• https://pypi.org/project/readmenator/
• https://grisuno.github.io/ReadMenator/

Supported Languages (19)

C, C++, Python, Go, Rust, JavaScript, TypeScript, Java, C#, Shell, PHP, Dart, GDScript, Nim, Assembly, Ruby, Swift, Kotlin, Scala, Lua, Elixir.

What ReadMenator Does Better Than Graphify

Installation

pip install readmenator 

or install from path

pip install .

Usage

Generate knowledge base

python -m readmenator /path/to/project --rebuild

Creates KNOWLEDGE_BASE.md with Table of Contents, Statistics Dashboard, Architectural Layers, God Nodes, Community Analysis, Surprising Connections, Suggested Questions, UML Class Diagram, Mermaid graph (internal edges + community subgraphs), and Architecture Reference. A link to the knowledge base is automatically injected into the project's README.md.

Export formats

python -m readmenator /path/to/project --export-all                # JSON + HTML + SVG
python -m readmenator /path/to/project --json                      # graph.json (GraphRAG-ready)
python -m readmenator /path/to/project --html                      # graph.html (interactive vis.js)
python -m readmenator /path/to/project --svg                       # graph.svg (static)
python -m readmenator /path/to/project --graphml                   # graph.graphml (Gephi/yEd)
python -m readmenator /path/to/project obsidian                    # Obsidian vault (wikilinks)
python -m readmenator /path/to/project wiki                       # Agent wiki (index + community pages)
python -m readmenator /path/to/project components                # Component diagrams (analysis.json + graph LR markdown + index.html)
python -m readmenator /path/to/project lint-wiki                  # Wiki health check
python -m readmenator /path/to/project lint                        # Architecture violations (exit 1 on errors)
python -m readmenator /path/to/project strip-dead-code             # Orphaned symbol report
python -m readmenator /path/to/project generate-rules              # Generate .cursorrules file
python -m readmenator /path/to/project refactor-monolith           # Refactoring plans + executable scripts

Query, explain, and path trace

python -m readmenator /path/to/project query "What classes handle HTTP?"
python -m readmenator /path/to/project explain Database
python -m readmenator /path/to/project path SymbolA SymbolB

Analysis

python -m readmenator /path/to/project analyze          # community + god nodes + questions
python -m readmenator /path/to/project layers           # architectural layer detection

Advanced Architectural Insights (Out of the Box)

ReadMenator goes beyond simple visualization. It runs complex graph algorithms locally to give you deep insights into your code's health:

• Change Impact Analysis: Know exactly which files are highly coupled. ReadMenator calculates direct and transitive dependents so you can predict what will break before you refactor.
• Hotspot Detection: Automatically ranks files by combining cognitive complexity (symbol richness) and graph centrality to pinpoint technical debt.
• Taint Propagation Mapping: Traces how risky imports (like subprocess or OS-level sinks) propagate transitively through your codebase dependency graph.
• Community & Layer Detection: Automatically groups files into structural layers (utility, business logic, infrastructure) and highly cohesive communities using label propagation.

Automation

python -m readmenator /path/to/project update           # incremental (SHA256 cache)
python -m readmenator /path/to/project watch            # auto-rebuild on file changes
python -m readmenator /path/to/project analyze          # Analyze the proyect

Run tests

python -m readmenator --test

UML Class Diagram

ReadMenator auto-generates Mermaid classDiagram from parsed class-level symbols across all supported languages. UML diagrams are embedded in KNOWLEDGE_BASE.md by default.

python -m readmenator /path/to/project uml              # Print UML class diagram

Interactive System Maps

ReadMenator builds five interactive physics-driven diagrams from scanned topology and writes them to readmenator-maps/ on every run: architecture, workflow, sequence, dataflow, and lifecycle. Each file is a vis.js network with draggable nodes, live physics, search, focus passport with full file documentation, upstream/downstream reach, directed route probing, role comparison, guided chapters, dark/light themes, keyboard shortcuts, hash deep links, and client-side PNG and JSON export. Cards state the primary scope honestly ("N of M files"); the full per-file listing lives in KNOWLEDGE_BASE.md.

python -m readmenator /path/to/project diagrams        # Export all 5 vis.js maps + gallery index (needs network)
python -m readmenator /path/to/project diagram sequence # Export one vis.js map (draggable nodes, live physics)
python -m readmenator /path/to/project pages           # Publish docs/ static site: gallery index + maps (GitHub Pages ready)

Maps are physics-driven vis.js documents (engine loaded from a CDN pinned in Config). Hover a node for a preview card; click it to dim everything outside its neighbourhood and open a passport with metric tiles, an ego mini-map (used-by on the left, imports on the right, every dot clickable), the docstring, a filterable symbol table with signatures, and Back history. Links are first-class too: hover one for a card, click it for a link passport (what depends on what, mutual dependencies, community bridges, role crossings, parallel links, both neighbourhoods) and share it with #edge=<from>~<to>.

The Force Graph Explorer (readmenator-maps/graph-force.html, featured in the gallery with a real ForceAtlas2 thumbnail) draws every file, community, layer and external in a 2D map or a 3D space:

• Deterministic start. Every node ships ForceAtlas2 (LinLog) start positions for 2D and 3D, scaled to the link distance, so the map opens already clustered and identical on every load instead of exploding from random positions.
• Exact selection. Hover, click, drag and right-click are hit-tested in the page against the positions drawn in the same frame, so the pointer always picks what is under it, including labels and curved edges, in both 2D and 3D.
• 3D without planets. The 3D view keeps the WebGL engine for links, arrows and flow particles, but draws files as flat document tiles (communities as hexagons, layers as diamonds, externals as triangles) on an overlay synced to the camera, with depth fade, group halos, readable labels, camera fly-to and an optional orbit.
• Node actions. Passport with PageRank, symbols, docs and grouped neighbours; reach Upstream (used by, the blast radius), Downstream (uses) or Both at 1, 2, 3 or all hops; isolate, hide, pin by dragging (2D), copy path; right-click menu for all of it; double-click isolates.
• Edge actions. Hover and click any dependency edge for a passport that reads the relation as a sentence and flags mutual dependencies, edges that close an import cycle, upward layer crossings and community bridges.
• Exploration. Path finder (Shift+click, P, or the menu) that prefers a directed route and explains it hop by hop; color by community, layer or language (clusters follow the grouping); node and edge type filters; layouts force, clusters, layer rings (shells in 3D) and dependency tree.
• Lenses for logic bugs. Import cycles (Tarjan SCC), files nothing imports (entry points or dead code), disconnected files, and PageRank hubs.
• Deep links restore the view: #node=<id>&view=3d&layout=cluster&color=layer&dir=up&depth=2, #path=<a>~<b>, #lens=cycles, #edge=<key>. The page also exposes window.ReadmenatorExplorer for console scripting.

The Edge Bundle Explorer (readmenator-maps/graph-bundle.html, its own gallery card next to the force graph, readmenator . bundles to export it alone) is the hierarchical edge bundling view from the video, live. It needs no network: one canvas, no CDN.

• Circle (2D). Files sit on a ring grouped into community arcs (hubs first); every resolved import is a B-spline routed through the community tree, so thick bundles are the real seams between subsystems.
• Sphere (3D). The same hierarchy on a globe: each community owns a contiguous cap sized by its file count, wires dive through the core between caps. Drag to rotate, wheel to zoom, optional auto-rotate; selecting a file or community flies the camera to face it.
• Crossing reduction. Communities that talk the most sit next to each other (weighted chaining plus 2-opt), hubs sit mid-arc, and barycentric sweeps move each file toward its neighbours; on the sphere every file takes the cap point facing its neighbours. Each step is kept only when total bundle length drops.
• Reading it. Hover a file: cyan wires are what it imports, pink what imports it. Click to pin it (imports and importers listed, one click to open it in the force graph in 2D or 3D). Click an arc, cap label or legend row to focus a community (inside/out/in counts, cohesion, top flows to other communities).
• Controls. Beta slider (0 straight chords, 1 fully bundled, recomputed live), crossing-only filter, direction (both, imports, imported by), color by community, layer or language, search, PNG export, light/dark theme. Deep links: #view=3d&node=<id>&group=<key>&beta=0.7&color=layer&dir=out&cross=1; console API window.ReadmenatorBundles.

API Reference (Sphinx / Doxygen style, zero tokens)

Every run writes readmenator-apidocs/, a deterministic API reference built from source, not from an LLM:

• Signatures from the code. Python gets a full ast pass (annotations, defaults, / and * markers, decorators, properties, class and static methods, dataclass fields, __all__, inferred raises and return behaviour). The other 18 languages reuse the parsers, recover the comment block above each declaration, nest members into their type by brace or indentation span, and split signatures into typed parameters and return types.
• Docstrings in any convention. Google, NumPy, reStructuredText/Sphinx, Javadoc/JSDoc/PHPDoc/KDoc/Doxygen (@param, \brief, {type}, [name=default]), C# XML doc comments, and Rustdoc sections all parse into the same parameters / returns / raises / examples / notes / see-also model.
• Cross-references. Base classes link to project types (with subclasses), header prototypes lend their docs to C definitions, overrides inherit base docs, and every callable lists precise callers and callees (Python receivers are typed from constructors, annotations, and self.attr assignments, so app.run() resolves to App.run and unproven obj.x() calls are dropped). Backticks, Sphinx roles and {@link} in prose become links.
• Pages. index.md (modules by package with coverage), one page per module with a Mermaid class diagram and call graph, classes.md (hierarchy), genindex.md (A-Z), COVERAGE.md, architecture.md, api.json, and an offline searchable index.html browser.
• Doc linting like Doxygen. DOC001 undocumented, DOC002 parameter not documented, DOC003 documented parameter not in the signature (stale docs), DOC004 return not documented, DOC005 raised exception not documented.

readmenator . apidocs                       # write readmenator-apidocs/
readmenator . doc-coverage --fail-under 80  # CI gate: exit 1 below 80%

Architecture and Execution Flows (interactive, offline)

Open readmenator-maps/flows.html (featured first in the maps gallery, also readmenator-apidocs/flows.html and the Flows tab of readmenator-apidocs/index.html). Every diagram is computed from the source and laid out by readmenator's own layered (Sugiyama-style) engine, then drawn as SVG in the page: no Mermaid, no CDN, no network.

• Tiered architecture. Communities become components; a weighted Eades-Lin-Smyth feedback-arc-set ordering makes most imports point downward, tiers are longest-path levels, implied edges are removed by transitive reduction, and the few imports that go upward (the minimal set that closes every cycle) are drawn as red dashed arrows and listed as "fix first". Click a component to see every file with its purpose and importer count.
• Control flow of each entry point (Python ast): decisions as diamonds (yes to the right, no continues down, so if/elif dispatchers become a tall ladder instead of a wide fan), loops with back arrows, try/except, with, returns and raises. Each step names the project functions it calls and shows what they do (docstring summary resolved through the typed call graph).
• Call tree in real call order (numbered arrows, repeats dashed, recursion red), with Owner.method, file:line and docstring per box.
• Cross-file sequence of the same walk.
• Viewer. Fit width, 100 %, zoom, fullscreen, SVG download, drag to pan, Ctrl+wheel to zoom, hover highlights a node's arrows, click opens a panel with the signature, docs, called functions, files, and a link into the API reference. Wide ranks wrap into extra rows, so a diagram never collapses into a thin strip.

readmenator . flows      # write readmenator-maps/flows.html only

KNOWLEDGE_BASE.md and readmenator-apidocs/architecture.md carry the same diagrams as Mermaid for GitHub. The legacy structural map now wraps every community into a grid (MERMAID_GRID_COLUMNS), caps external boxes (MERMAID_MAX_EXTERNALS) and runs left to right; UML is split into diagrams of at most UML_CLASSES_PER_DIAGRAM classes, so none of them renders as a strip.

Component Diagrams

readmenator-diagrams/ holds a component architecture map built with zero tokens: analysis.json (components with key entities and file/line spans, relations with method-level call evidence), overview.md with the graph LR diagram, one page per expandable component, and index.html — the diagram drawn as an offline interactive page in the readmenator dark theme (layered left-to-right boxes enriched with key symbols, layer colors and PageRank hubs, labeled arrows weighted by call/import evidence, hover descriptions, click-to-component, pan/zoom, PNG export). The maps gallery links it with a Component Diagrams card that opens a self-contained copy living inside the maps directory itself, so the link never leaves the site (safe on GitHub Pages project subpaths, where ../.. hrefs would escape the project). The docs site ships the markdown in its reader. No external service needed: structure and call evidence are pure static analysis; a local Ollama daemon only ever enriches prose descriptions, and only when OLLAMA_ENABLED is set.

python -m readmenator /path/to/project components  # rebuild only the diagrams

Serve the docs/ directory directly with GitHub Pages (Settings -> Pages -> Deploy from branch -> folder docs/). The gallery index.html links every map with relative paths, works fully offline, and needs no build step. The site also ships llms.txt (the llms.txt convention), so agents browsing the published site get a plain-markdown map of the wiki, agent docs, and knowledge base instead of parsing HTML. Once docs/ holds a gallery, every --rebuild refreshes it (video and docs included).

Overview Video

readmenator . video renders a synthwave mp4 from real scan data in eleven acts: layers, god nodes, blast-radius tree, communities, Emergence (ForceAtlas2 LinLog with adaptive speed, animated from seeded chaos to convergence, nodes sized by PageRank with random-surfer particles on the hottest edges), Orbit (the force graph laid out by ForceAtlas2 in 3D and flown by a camera: color by community, layer and language in turn, a tour that zooms into the largest communities with their cohesion and seams, then the 1-hop reach of the top hub), The Wiring (Holten hierarchical edge bundling: files on a circle by community, imports routed as B-splines through the community tree, a spotlight sweeping each community and a live flow ranking), The Sphere (the 3D layout folds onto a globe of community caps and every import bundles through its core), and code DNA. A closing invitation shows both explorers spinning with their paths, so viewers know where to go next. Set an act's duration (VIDEO_ORBIT_S, VIDEO_SPHERE_S, VIDEO_INVITE_S, ...) to 0 to drop it with its card. Two acts come from the flow engine: X The Tiers (the architecture assembles tier by tier, then the upward imports that break the layering flash red with a "fix first" list) and XI Execution (a camera follows the main entry point's call tree in real call order, a light packet travels along each call, and a side panel shows the callee, its file:line and docstring). Motion uses quintic smootherstep easing, scenes crossfade into each other (VIDEO_TRANSITION_S), and the 3D camera acts get shutter motion blur (VIDEO_MOTION_BLUR_SAMPLES). The circle and sphere acts share the explorer's crossing-reduction ordering.

GraphRAG for agents (zero tokens to build, cheap to query)

readmenator-graphrag/ is a GraphRAG index built without any language model: entities (files, symbols, concepts, external modules, project memory), typed relationships (defines, imports, calls, inherits, documents), source text units (each symbol's real code span), and a report hierarchy (Louvain communities, Louvain themes over the community graph, a project root) whose sentences are all measured facts: PageRank, fan-in, findings, cycles, hotspots, layer violations.

readmenator . ask "how are communities detected"      # auto mode
readmenator . ask "PageRank seeds" --local            # BM25 + Personalized PageRank (HippoRAG style)
readmenator . ask "main subsystems and risks" --global --budget 1500   # map-reduce over reports
readmenator . graphrag                                # rebuild only the index

MCP: tool readmenator.graphrag and resource readmenator://graphrag.

Project memory and agent skills

readmenator-agent/MEMORY.md is the cross-session context file: purpose and domain vocabulary, detected workflow commands, declared rules, style norms and definition of done quoted from AGENTS.md / CLAUDE.md / CONTRIBUTING.md / .cursorrules with file:line, measured baselines (docstring coverage, naming, findings, cycles), risks, and a session log preserved across rebuilds:

readmenator . remember "Retries capped at 3: the bank bans clients after 4 failures" --kind business
readmenator . memory            # print it (MCP: readmenator.memory / readmenator.remember)
readmenator . skills            # install agent skills into .claude/skills/

Notes are indexed by GraphRAG, so ask surfaces recorded business rules next to the code they govern. Four packaged skills (readmenator-orient, readmenator-ask, readmenator-change, readmenator-memory) teach any agent the protocol; run installs them automatically when the project already has a .claude/ directory.

Agent-Ready Output (zero tokens)

readmenator-agent/ is built for agents that grep and read:

• MANIFEST.json records git_commit: compare it with git rev-parse HEAD to know whether the docs are stale before trusting them. It also lists every document with its line count and approximate token cost.
• Every document stays under 500 lines. Larger ones are paged as NAME_p2.md, so grep with NAME*.md.
• INDEX.md gives each file a one-sentence purpose and a "Used by" count (blast radius at a glance).
• API.md lists one line per public function, and GOTCHAS.md ranks blast radius without counting tests.
• readmenator never rescans its own generated output.

GitHub Wiki

Mirror the wiki, agent docs, recipes, and KNOWLEDGE_BASE.md into the repository's GitHub wiki. Pages get a sidebar, cross-links, and source permalinks pinned to the current commit:

readmenator . --rebuild                  # regenerates everything AND publishes the GitHub wiki
readmenator . gh-wiki                    # publish the wiki only
readmenator . gh-wiki --dry-run          # render pages into readmenator-ghwiki/ (no git calls)

Requirements: the wiki is enabled, its first page was created once in the web UI, and git can push (for example after gh auth setup-git). Pages written by hand are never deleted. Only pages that readmenator generated earlier are replaced.

Generate Class Stubs in Other Languages

Translate extracted class structures into target language declarations:

python -m readmenator /path/to/project --c++            # C++ class declarations
python -m readmenator /path/to/project --java           # Java class declarations
python -m readmenator /path/to/project --csharp         # C# class declarations
python -m readmenator /path/to/project --kotlin         # Kotlin class declarations
python -m readmenator /path/to/project --scala          # Scala class declarations
python -m readmenator /path/to/project --swift-classes  # Swift type declarations
python -m readmenator /path/to/project --dart-classes   # Dart class declarations
python -m readmenator /path/to/project --ruby-classes   # Ruby class declarations
python -m readmenator /path/to/project --go-classes     # Go type declarations
python -m readmenator /path/to/project --rust-classes   # Rust type declarations
python -m readmenator /path/to/project --php-classes    # PHP class declarations
python -m readmenator /path/to/project --python-classes # Python class declarations

Supported target languages (12): C++, Java, C#, Python, Go, Rust, PHP, Kotlin, Scala, Swift, Dart, Ruby.

Architecture

Security

• Symlinks rejected
• File size capped at 10 MB
• Directory depth limited to 20
• No absolute paths in source code
• No external network calls in any module
• All exceptions silently caught during parsing

License

AGPL-3.0

Knowledge Base

This project has been analyzed by ReadMenator, a zero-token polyglot static analysis tool. Regenerate with pip install readmenator && readmenator . --rebuild. Analysis outputs:

• KNOWLEDGE_BASE.md -- Full architecture reference with all classes, functions, imports, dependency graphs, UML class diagrams, security audit findings, community analysis, taint paths, hotspots, cycles, and more.
• readmenator-agent/ -- Agent-friendly, grep-optimized index.
  • INDEX.md -- Quick reference: what each file does
  • SYMBOLS.md -- Every symbol with file:line
  • ARCHITECTURE.md -- Internal dependency pairs + external imports
  • API.md -- Public function contracts
  • GOTCHAS.md -- Change warnings (blast radius, cycles, hotspots)
  • SECURITY.md -- Findings by severity with fix hints
  • MEMORY.md -- Rules, workflow, style, deliverables, session log
  • MANIFEST.json -- Freshness (git_commit + source_fingerprint) + read order
  • KB_<subsystem>.md -- Per-subsystem context
  • recipes/*.md -- Grounded task guides (add-function, fix-cycle, ...)
• readmenator-wiki/ -- Navigable wiki (start here for the big picture).
  • index.md -- Entry point: overview, reading order, god nodes, connections
  • community_*.md -- One synthesis page per code community
  • connections.json -- Typed bridges between communities
  • queries.md -- Suggested questions + answer log
  • REPORT.md -- Honest audit: coverage, confidence, limits
• readmenator-graphrag/ -- Zero-token GraphRAG index.
  • index.json + REPORTS.md -- Query with readmenator . ask "<question>"
• readmenator-apidocs/ -- API reference (Sphinx/Doxygen style).
  • index.md + modules/*.md -- Signatures, parameters, returns, raises, examples, call graphs
  • architecture.md -- Tiered architecture + execution flows (control flow, call tree, sequence)
  • classes.md, genindex.md, COVERAGE.md -- Hierarchy, A-Z index, doc coverage + warnings
  • index.html + api.json -- Offline searchable browser and machine-readable model
• readmenator-maps/ -- Interactive gallery (index.html).
  • 5 system maps: architecture, workflow, sequence, dataflow, lifecycle
  • graph-force.html -- Force-graph explorer (2D/3D, reach, paths, lenses)
  • graph-bundle.html -- Edge bundle explorer (circle + sphere)
  • components.html -- Component diagrams
• docs/ -- Static site (GitHub Pages ready).
  • Gallery copy + llms.txt (agent entry point) + md/ docs + video
• readmenator-diagrams/ -- Component diagrams.
  • analysis.json + graph LR markdown + per-component pages + index.html
• readmenator-rules/ -- Suggested Semgrep rules (*.yml), yara_rules.yar (YARA-lite) + exclusions.yaml (false-positive blocklist)
• readmenator.mp4 -- Cinematic synthwave overview video
• .cursorrules -- Generated AI assistant rules
• readmenator_audit.sarif -- SARIF v2.1.0 audit (when security scan is on)

Cache (.readmenator_cache/), packaged agent skills (.claude/skills/), and the GitHub wiki mirror are also produced on run/--rebuild.

AI agents: Read readmenator-wiki/index.md first for the big picture, then readmenator-agent/INDEX.md for grep-friendly lookup. Developers: Read KNOWLEDGE_BASE.md for full architecture reference, open readmenator-maps/index.html for the visual gallery.