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/af02cae9-5cb5-427e-84cc-af4d82374116

• 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 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). Click any node for full file documentation: docstring, symbol table with signatures, and import neighborhoods.

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).

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. Analysis outputs are available:

• KNOWLEDGE_BASE.md -- Full architecture reference with all classes, functions, imports, dependency graphs, UML class diagrams, security audit findings, community analysis, and more.
• readmenator-agent/ -- Agent-friendly, grep-optimized index.
  • INDEX.md -- Quick reference: what each file does
  • API.md -- Public function contracts
  • GOTCHAS.md -- Change warnings
  • SECURITY.md -- Findings by severity
• 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
  • REPORT.md -- Honest audit: coverage, confidence, limits

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.