Graft

Graft is a command-line tool that gives coding agents like Claude Code, Cursor, and Codex a durable map of a codebase instead of making them rediscover it on every task. It parses the repo with tree-sitter across twenty-three languages, groups the results into a curated set of markdown nodes — one per subsystem, key file, or concept — and writes them to a local graft/ folder that behaves like a regenerable cache rather than a committed artifact. Each node carries a plain-English summary, the crux lines that hold the actual logic, links to related nodes, and space for hand-written notes that survive regeneration.

The structural layer (graft build, graft check, graft ask, graft grep, graft map, graft callers) is pure tree-sitter and needs no model or API key; an optional --deep pass adds LLM-written summaries and per-symbol cruxes under whichever provider and key the user configures. graft init wires the tool into a project’s coding agents, registering an MCP server with six retrieval tools and, for Claude Code specifically, a live statusline and post-edit hooks that keep the graph synced automatically. The project backs its cost and speed claims with a published benchmark harness and a 50-instance SWE-bench Verified run comparing a cold agent against one wired to Graft.

What You Get

• Structural code graph with zero setup - graft build runs deterministic tree-sitter parsing across 23 languages with no LLM call and no API key required, producing a per-symbol wiring graph plus per-file cards.
• LLM-written concept nodes - graft build --deep groups file summaries into a curated set of markdown nodes with typed links (depends_on, part_of, uses, implements, produces), using whichever LLM provider and key you configure.
• Always-fresh queries - ask, grep, callers, skeleton, and map re-stat the working tree before answering (~3ms when nothing moved), so results reflect uncommitted edits without a background daemon.
• Native agent wiring - graft init detects installed coding agents and writes each one’s native instruction file or skill file (AGENTS.md, GEMINI.md, .claude/skills/graft/SKILL.md, .cursor/rules/graft.mdc, and more) without touching the rest of the project’s own instructions.
• MCP server with six tools - graft_find_code, graft_file_api, graft_trace_calls, graft_find_all, graft_repo_map, and graft_check_freshness expose the graph to any MCP-capable agent.
• Deep Claude Code integration - a live statusline showing graph size and staleness, automatic post-edit graph resync, and blast-radius warnings when an edited file has dependents.

Common Use Cases

• Onboarding an AI agent to a large codebase - a team wires Graft into Claude Code or Cursor once so every new task starts from a pre-built map instead of a cold exploration pass.
• Reducing agent token spend and latency - projects paying for agent tool calls run graft build --deep to cut redundant grep/read cycles the project’s own benchmark measured at roughly 42% fewer tokens and 60% less time per task.
• PR-time blast-radius review - graft blast --base origin/main --format markdown posts a comment naming every area a diff’s changed lines reach, so reviewers see downstream impact without walking the call graph by hand.
• Auditing whether an agent’s context is stale - graft check fails CI with a drift report when the committed graph no longer matches the code, catching a graph nobody rebuilt after a refactor.
• Exploring an unfamiliar repo interactively - graft viz serves a browsable graph in the terminal or exports a static site, giving a human the same map the agent uses.

Under The Hood

Architecture Graft is organized as a CLI (src/cli.ts, built on Commander) that dispatches into domain-scoped modules — graph/ for the tree-sitter wiring graph and workspace federation, context/ for the markdown node build/check pipeline, ask/ for retrieval and ranking, ai/ for provider-agnostic LLM calls, hosts/ for per-agent wiring (Claude, Cursor, Codex, Gemini, and others), claude/ for Claude Code’s deeper statusline/hooks integration, brain/ for the hosted Trail Brain sync feature, and mcp/ for the six-tool MCP server. The Graft class in src/engine.ts is the thin programmatic entry point wrapping buildContext/checkContext/buildGraph/ask, so the CLI and the MCP server share the same underlying pipeline. A workspace root with multiple git children federates query commands (ask, build, callers, check, grep, map) across them via graph/workspace-cli.ts, and every read command re-verifies the working tree against the last build’s fingerprint before answering, so a stale on-disk graph never silently answers a query.

Tech Stack Written in strict TypeScript (Node >=20, ES2022, NodeNext modules) with tree-sitter and per-language grammar packages (Go, Java, Kotlin, PHP, Python, R, Swift, TypeScript, plus a WASM fallback) for parsing, commander for the CLI surface, @anthropic-ai/sdk and openai for the pluggable LLM providers, d3-force for the interactive graft viz layout, and vscode-languageserver-protocol/vscode-jsonrpc for the optional compiler-grade LSP edge enrichment. The build pipeline is tsc plus a small esbuild-based viewer bundler; native addons are compiled through node-gyp.

Code Quality The suite runs on Node’s built-in test runner rather than a third-party framework, with over 120 test files enumerated explicitly by a custom runner script to sidestep a real cross-platform glob-expansion bug the project hit in CI. GitHub Actions runs the suite on both Ubuntu and Windows matrices deliberately — the README-adjacent CI comments document a specific class of path-separator bug that a POSIX-only matrix had missed — alongside CodeQL static analysis and an OpenSSF Scorecard workflow. TypeScript strict mode is enabled project-wide, and error handling in the CLI layer routes through dedicated status/debug formatting helpers rather than bare try/catch swallowing.

What Makes It Unique Graft’s distinguishing choice is representing agent context as plain, git-diffable markdown files an agent reads the same way it reads any other file, rather than embeddings or a vector index — no similarity search, no server to keep warm. It backs that design with a published, methodologically explicit benchmark (a judge model with a required-keyword correctness floor, cache-aware cost accounting) and an independent SWE-bench Verified run against the official harness, rather than only asserting speedups. The freshness model — restating the working tree in milliseconds before every query so answers include uncommitted edits — is also a deliberate alternative to index-then-poll designs common in competing tools.