@dreamtree-org/graphify

Turn a folder of code into a queryable, persistent knowledge graph — and then use it the way a coding agent actually needs to: get the working set for a task, the blast radius of a change, the minimal tests to run, a structural review of a diff, and an architecture check — each in one command, inside a token budget.

Works with any coding agent that can shell out or speak MCP (Claude Code, Cursor, Windsurf, Cline, Codex, opencode, Amp, Gemini CLI, ...). No LLM API key required — extraction is tree-sitter AST parsing, deterministic and offline.

Why

Agents re-read codebases from scratch every session and burn most of their tokens finding the right files. A graph fixes retrieval, but node lists alone still leave the agent to chase files. graphify closes the loop: its answers are task-shaped — actual code snippets, test lists, impact checklists, diffs — not just structure.

Token savings depend on the shape of your repo: graph answers have a roughly fixed cost (they fill toward their token budget), so the win grows with how much code a naive file read would have pulled in. Measured with graphify benchmark: up to ~8x on this repository (~100 files, deep cross-file structure), closer to ~1.5x on small, tightly-organized libraries — and on a trivial question in a tiny repo, reading the file directly can be cheaper. Run graphify benchmark on your own repo before quoting a number.

Install

npm install -g @dreamtree-org/graphify
# or, without installing:
npx @dreamtree-org/graphify .

A default run does more than build the graph — it also makes it instantly usable by the AI agents your project already has: it installs the graphify skill/rules files and registers the project-scoped MCP server. Claude Code is always set up (.claude/skills/graphify/SKILL.md + .mcp.json); Cursor, Windsurf, Cline, AGENTS.md hosts, and Gemini CLI are set up when their config dir/file is detected in the project. All writes are idempotent and never touch your existing config (.mcp.json entries for other servers, user content in AGENTS.md, ...). Opt out with --no-install.

Build the graph

graphify .                      # full pipeline: detect -> extract -> build -> cluster -> analyze -> report -> export
graphify <path>                 # same, on a path
graphify <github-url>           # git clone --depth 1, then the pipeline
graphify . --update             # incremental — cached extractions for unchanged files (warm rebuilds ~3x faster)
graphify . --no-viz             # skip graph.html
graphify . --leiden             # Leiden instead of Louvain community detection
graphify . --watch              # rebuild on file change
graphify . --mysql <dsn>        # also extract a MySQL schema (mysql://user:pass@host:port/db) into the same graph
graphify . --mcp                # start the MCP stdio server instead of running the pipeline
graphify . --no-install         # skip the automatic agent skill + MCP config install

Outputs land in graphify-out/: graph.json (GraphRAG-ready), graph.html (interactive, fully offline), GRAPH_REPORT.md (plain-language audit: god nodes, surprises, open questions).

Languages: TypeScript/JavaScript (JSX, CommonJS, decorators, re-exports — deepest coverage), Python, Go, Rust, Java, C#, Ruby, plus MySQL schemas. Cross-file references are resolved in a whole-corpus pass, so imports land on real definitions, not guesses.

Ask the graph

graphify context "<task>"       # THE first call for any task: a token-budgeted pack of the actual
                                #   code (real snippets at real line ranges), graph-ranked (--budget)
graphify query "<question>"     # BFS/DFS traversal — fuzzy and identifier-aware: natural-language
                                #   words match camelCase symbols, typos still resolve (--budget tokens)
graphify affected "<node>"      # reverse impact analysis — everything that transitively depends on
                                #   a node, grouped by depth, blast radius split by confidence
graphify tests "<node>"         # minimal test files worth running for a change (static, no coverage
graphify tests --changed [rev]  #   instrumentation) — or for the whole working-tree diff
graphify review <base> [head]   # structural review between two git revs: added/removed/rewired
                                #   symbols, each with blast radius + suggested tests
graphify check                  # architecture guardrails from graphify.rules.json — exits 1 on
                                #   violations, so agents and CI can gate on it
graphify path "<A>" "<B>"       # shortest path between two named nodes
graphify explain "<node>"       # a node's location, community, and every edge in/out
graphify benchmark [q...]       # measure the token savings on your own repo

Close the loop

graphify save-result --question Q --answer A --nodes id... --outcome useful|dead_end|corrected
graphify reflect                # aggregate results into graphify-out/reflections/LESSONS.md
                                #   (recency-weighted; agents read it at session start)
graphify hook install           # auto-rebuild (incremental) after every commit and pull
graphify install --platform all # install the agent skill/rules + project MCP config: claude,
                                #   cursor, windsurf, cline, agents (AGENTS.md: Codex/opencode/Amp),
                                #   gemini — a plain `graphify .` run already does this for
                                #   detected hosts

With hooks installed the MCP server always serves a fresh graph — it re-reads graph.json on every tool call.

Cross-project graphs

graphify global add [path]      # register a built project (name from package.json)
graphify global build           # merge all registered projects into one global graph
graphify merge <dirA> <dirB>    # one-shot merge (--out <dir>)

Per-project node ids are namespaced; shared dependencies (module:lodash) stay unprefixed, so repos that use the same packages are automatically bridged in the merged graph.

MCP server

graphify --mcp (or the graphify-mcp binary) exposes context, query, path, explain, affected, and tests as MCP tools over stdio. No network listener.

You normally never start it by hand: the default pipeline run registers it in the project's MCP config (.mcp.json for Claude Code, .cursor/mcp.json for Cursor, .gemini/settings.json for Gemini CLI) as npx -y @dreamtree-org/graphify --mcp, so the host launches it on demand — and teammates who pull the repo get it with zero setup.

Guardrails file

graphify.rules.json at the repo root (this repo dogfoods its own):

{
  "rules": [
    {
      "name": "extractors-stay-cli-agnostic",
      "from": "src/extractors/**",
      "disallow": ["src/cli/**", "src/mcp/**"],
      "reason": "language extractors are pure library code"
    }
  ]
}

What this does NOT do

• No network listener — the MCP server is stdio-only.
• No code execution from source content — AST parsing only, never eval/exec.
• No shell: true / string-built shell commands.
• No credential leakage — MySQL DSN credentials never appear in graph output, reports, or logs (only the credential-free mysql://host:port/db form does).

Full threat model: docs/SECURITY.md. Architecture and design notes: docs/ARCHITECTURE.md.

Development

npm install
npm run build
npm test        # ~300 unit tests, no network, no side effects outside temp dirs
npm run lint

License

MIT