Skip to content

graphify.md

Latest commit

 

History

History
138 lines (91 loc) · 3.89 KB

graphify.md

File metadata and controls

138 lines (91 loc) · 3.89 KB
Raw

graphify

Semantic knowledge graph for your codebase. Builds a queryable graph from source code using AST parsing across 25+ languages, then lets the agent answer conceptual questions without reading raw files.

Built by @safishamsi — integrated into OpenMono as a Bash-tool layer on top of the CLI.

What it does

graphify parses your project into a graph of nodes (classes, functions, modules, files) and edges (calls, imports, inherits, depends-on). Once built, the agent can query that graph directly instead of reading files one by one — making cross-file questions ~71× more token-efficient.

Output lives in graphify-out/ inside your project directory:

File Purpose
graphify-out/graph.json Machine-readable graph — what the agent queries
graphify-out/graph.html Interactive visual explorer — open in a browser
graphify-out/GRAPH_REPORT.md Human-readable summary of communities and key nodes

Setup

graphify is installed automatically by install.sh (Step 5 — agent and full roles). No manual install needed.

To build the graph for a project (one-time, per project):

openmono graphify           # installs if missing, builds graph, verifies

# Or directly from your project root:
graphify update .

CLI commands

All commands must be run from inside the project directory (graphify doesn't accept a path argument).

# Build / refresh
graphify update .              # full build (or incremental if graph exists)

# Query the graph
graphify query "how does auth work?"
graphify query "what manages session state?" --budget 100   # limit traversal depth

# Find connection between two concepts
graphify path "UserController" "TokenStore"

# Explain a specific node
graphify explain "ConversationLoop"

How OpenMono uses it

At startup, OpenMono checks for graphify-out/graph.json in the working directory. If found, it prints:

graphify graph detected — use: graphify query/path/explain via Bash.

The agent then uses Bash to run graphify commands when answering conceptual questions — before falling back to raw Grep. This is not an MCP server; graphify runs as a direct Bash subprocess.

Playbook

A built-in playbook at .openmono/playbooks/graphify/PLAYBOOK.md exposes explicit graph actions:

# Inside the agent REPL:
graphify query "session state"
graphify path "ConversationLoop" "TokenTracker"
graphify explain "ToolRegistry"
graphify build
graphify update

Sample questions to ask the agent

These are best answered by graphify rather than raw file reads:

What handles HTTP request routing?
What would break if I deleted TodoStore?
How does a request get from the controller to the database?
What calls the save method?
Which classes have the most dependents?
Explain the role of CliApp in this codebase.

Visualization

Open graphify-out/graph.html in a browser. The graph is interactive:

  • Click a node to inspect it (type, file, relationships)
  • Search nodes by name
  • Filter by community (clusters of related code)
  • Click neighbor links to traverse the graph

The agent will remind you to open this file when you ask about visualization.

Docker

graphify is baked into the agent image via pip3 install graphifyy in docker/Dockerfile.agent.

Build the graph on the host, then mount your project directory:

# Host — build the graph
cd ~/your-project
openmono graphify

# Start the agent — graph is accessible at /workspace/graphify-out/graph.json
WORKSPACE=~/your-project openmono agent

The graph is built on the host and accessed via the ${WORKSPACE}:/workspace volume mount. No rebuild needed inside the container.

Rebuilding

The graph does not auto-update. Rebuild after significant changes:

openmono graphify          # from any directory
# or
cd ~/your-project && graphify update .