Codebase Knowledge Graph

Rayu CLI has first-class integration with codebase knowledge graphs. You can build, query, and maintain a navigable graph of your source tree, helping you understand complex architectures and run context-aware operations instantly.

The graph lives at:

graphify-out/
  graph.json      ← the full graph data
  GRAPH_REPORT.md ← human-readable summary (communities, god nodes, surprising edges)
  graph.html      ← interactive 2D/3D visualization (open in a browser)

The graph is generated by graphify, which extracts code structure deterministically via AST analysis and combines it with semantic extraction (using LLMs or parallel subagents) for documentation, papers, images, and videos.

Why this exists. Navigating a large codebase (2,000+ TypeScript/JavaScript files in Rayu's case) is expensive in context window tokens. Running queries locally against graph.json using /graphify query or /graphify explain avoids costly whole-repo scans, saving time and API limits.

1 ── Quick Orientation

Open graphify-out/GRAPH_REPORT.md (relative to the directory you analyzed). The top sections give you high-level context immediately:

SectionWhat it tells you
God NodesThe most connected functions or modules (e.g., logForDebugging, logError, logEvent, jsonStringify, getGlobalConfig) representing key cross-cutting concerns.
CommunitiesSemantic clusters of files detected via modularity-based community detection (e.g., Agent & Session Management, CLI Command System, Tool Execution, MCP & Plugin System, Security & Permissions, UI Components, Context & State, Type Definitions, Error Handling).
Surprising ConnectionsInferred relationships between symbols that aren't structurally linked but share high semantic similarity (e.g., resolveHookPermissionDecision() → canUseTool()).
HyperedgesShared multi-step workflows or groups of nodes that participate in a common flow (e.g., GitHub App Setup flow, Plugin command system, Caching, Transports).

2 ── Using graphify inside Rayu

Rayu loads the /graphify skill dynamically from external directories (e.g. ~/.agents/skills/graphify or .kiro/skills/graphify). When the skill is active, you can query or update the graph using natural language.

2.1 Ask a question about the codebase (BFS query)

/graphify query "How does the slash command /clear work — which handler, which UI component?"

This performs a Breadth-First Search (BFS) on the graph and traces: command registration → handler function → state mutation → UI update, returning specific file paths and symbols.

2.2 Shortest path between two concepts

/graphify path "src/commands/clear/conversation.ts" "src/state/AppStateStore.ts"

Returns the call-chain connecting the clear-conversation command to the app state store, including every intermediate symbol.

2.3 Explain a symbol

/graphify explain "getGlobalConfig"

Traces all callers, callees, file locations, and references for that function.

3 ── Maintenance and Rebuilding

3.1 Install the CLI

To run graphify manually in your shell, install the command-line tool via pip or uv:

# Recommended: Install via uv tool
uv tool install --upgrade graphifyy

# Or install via pip
pip install --upgrade graphifyy --break-system-packages

3.2 Rebuild the Graph

You can rebuild or update the graph from the root of your project:

# Full extraction (AST + semantic extraction)
graphify extract .

# Re-extract only modified files (fast, incremental)
graphify update . --no-cluster
graphify cluster-only .
  • update . --no-cluster: Incremental file detection and AST re-extraction, writing a fresh graph.json.
  • cluster-only .: Re-runs local community detection and updates the report (GRAPH_REPORT.md) and visualization (graph.html).

3.3 Semantic Extraction Configuration

By default, structural (AST) extraction is run for code. For markdown documents, PDFs, and images, graphify uses semantic extraction:

  • Set GEMINI_API_KEY or GOOGLE_API_KEY to run fast semantic extraction via Gemini (pip install 'graphifyy[gemini]').
  • If no key is set, the graphify skill falls back to using parallel agent subagents inside your session to extract entities and relationships.

3.4 Exclude files

To ignore build outputs, test runner caches, or vendor directories, create a .graphifyignore file in the scan root (it supports the same syntax as .gitignore).

4 ── Visualizing Interactively

Open graphify-out/graph.html in any browser:

  • Search-as-you-type across all symbols in the project.
  • Click any node to highlight its structural and semantic connections.
  • Interactive community color-coding to visually explore boundaries and subsystems.