| name | readmenator |
| description | Zero-token static analysis codebase context. MCP-native AI agent integration. Use MCP tools for queries -- no LLM extraction, no KB file parsing, no token cost. Pure AST + regex. |
| trigger | /readmenator |
/readmenator
Turn any codebase into a queryable knowledge base using pure static analysis. No LLMs. No tokens. No cloud.
Architecture: MCP-first, KB-fallback
Agent (Claude) ──MCP tools──> readmenator MCP server ──> live queries (50-200 tokens)
\
──read file──> KNOWLEDGE_BASE.md ──> fallback (2000-8000 tokens)
The MCP server is the primary interface. The KNOWLEDGE_BASE.md file is the fallback for agents that don't support MCP tool calls.
Token savings with MCP:
| Query type | Without MCP (read KB.md) | With MCP (tool call) | Savings |
|---|
| Summary | 2000-8000 tokens | ~300 tokens | 85-96% |
| Symbol search | Full KB parse | ~150 tokens | 93-98% |
| Explain symbol | Parse KB for context | ~100 tokens | 95-99% |
| Path tracing | Parse KB for context | ~100 tokens | 95-99% |
| Daily (10 queries) | 20K-80K tokens | ~3K tokens | 85-96% |
Usage
/readmenator # ensure KB + MCP server exist, then use tools
/readmenator <path> # target a specific directory
/readmenator --rebuild # force regeneration
/readmenator serve <path> # start MCP stdio server
/readmenator --context-budget 500 # generate KB truncated to ~500 tokens
What ReadMenator is for
ReadMenator pre-computes a structural map of your codebase (statically, for free), then serves it via MCP tools so the AI agent never needs to read source files or parse large KB documents.
19 languages: C, C++, Python, Go, Rust, JavaScript, TypeScript, Java, C#, Shell, PHP, Dart, GDScript, Nim, Assembly, Ruby, Swift, Kotlin, Scala, Lua, Elixir.
What You Must Do When Invoked
If no path was given, use . (current directory). Do not ask the user for a path.
Step 1 -- Ensure the MCP server is ready
First, check if KNOWLEDGE_BASE.md exists. Generate it if not:
python3 -m readmenator TARGET_PATH --rebuild
If readmenator is not installed:
if [ -f "readmenator.py" ]; then
python3 readmenator.py TARGET_PATH
else
pip install readmenator && python3 -m readmenator TARGET_PATH --rebuild
fi
Replace TARGET_PATH with the actual path.
Step 2 -- Use MCP tools (primary path)
Do NOT read KNOWLEDGE_BASE.md as text. Use the MCP tools below instead. They return structured data at a fraction of the token cost.
Available MCP tools (when readmenator serve <path> is running):
| Tool | Purpose | Token cost |
|---|
readmenator.summary | Codebase overview | ~300 |
readmenator.query(text) | Free-text symbol search | ~150 |
readmenator.explain(name) | Full symbol detail | ~100 |
readmenator.path(symbol_a, symbol_b) | Dependency chain | ~100 |
readmenator.findings(min_severity) | Security issues | ~200 |
readmenator.security_summary | Security audit summary | ~100 |
readmenator.taint | Taint propagation paths | ~300 |
readmenator.hotspots(top_n) | Hotspot files | ~200 |
readmenator.cycles | Circular dependencies | ~200 |
readmenator.communities | Import communities | ~300 |
readmenator.layers | Architecture layers | ~200 |
readmenator.layer_violations | Layer rule violations | ~200 |
readmenator.rebuild | Full KB regeneration | N/A |
readmenator.update | Incremental update | N/A |
How to call MCP tools (Claude Desktop):
The MCP server communicates via stdin/stdout using JSON-RPC 2.0. Claude Desktop connects automatically when configured with:
{
"mcpServers": {
"readmenator": {
"command": "readmenator-mcp",
"args": ["/path/to/project"]
}
}
}
Or via Python directly:
{
"mcpServers": {
"readmenator": {
"command": "python3",
"args": ["-m", "readmenator._mcp_server", "/path/to/project"]
}
}
}
Step 2b -- Fallback: Read KNOWLEDGE_BASE.md (only if MCP unavailable)
If the MCP server is not running AND you cannot start it, read TARGET_PATH/KNOWLEDGE_BASE.md directly.
The file structure is deterministic:
- Header -- metadata (total files, symbols, imports)
- Statistics Dashboard -- file counts, fan-in/fan-out, language breakdown
- God Nodes -- most central files ranked by connectivity
- Community Analysis -- import-based groups with cohesion scores
- Structural Knowledge Map -- Mermaid graph (
mermaid ... )
- Architecture Reference -- grouped by language, each file lists its symbols
If --context-budget was used during generation, the KB starts with a compact summary section (first ~400 chars) followed by high-priority analysis sections, truncated to the specified token budget.
Step 3 -- Answer based on MCP tool results
For /readmenator (no subcommand): Call readmenator.summary and present the result.
For /readmenator query "<question>": Call readmenator.query(text="<question>").
For /readmenator explain "<symbol>": Call readmenator.explain(name="<symbol>").
For /readmenator path "<A>" "<B>": Call readmenator.path(symbol_a="<A>", symbol_b="<B>").
Step 4 -- Offer regeneration
When done, suggest:
"The knowledge base may be stale. Run /readmenator --rebuild to regenerate, or use readmenator.rebuild via MCP."
MCP Resources (structured data access)
For agents that support MCP resources:
| Resource | Content | Type |
|---|
readmenator://summary | Structured JSON: files, symbols, imports, langs, god nodes | JSON |
readmenator://graph | Full graph: nodes + edges | JSON |
readmenator://findings | All security findings grouped by severity | JSON |
readmenator://analysis | Complete analysis: communities, taint, hotspots, cycles | JSON |
readmenator://kb | Full KNOWLEDGE_BASE.md text | Markdown |
Comparison with graphify
| Aspect | graphify | readmenator |
|---|
| Extraction | LLM agents (tokens) | AST + regex (free) |
| Agent integration | MCP queries | MCP tools + resources |
| Community detection | Yes (Leiden) | Yes (label propagation) |
| Semantic edges | Yes (costs tokens) | No (structural only, free) |
| Security analysis | No | Yes (18 languages) |
| Taint propagation | No | Yes |
| Export formats | HTML, JSON, Obsidian | JSON, HTML, SVG, GraphML, Obsidian, SARIF |
| Token cost per query | ~200 (MCP query) | ~100-300 (MCP tool) |
| Regeneration cost | Token-based (LLM) | Zero (AST) |
Use readmenator when you want zero-token generation + minimal-token queries via MCP. Use graphify when you need semantic cross-document inference with LLM extraction.
Script location
