Graft README

Graft

A context governor for coding agents. Graft enforces read policy so agents consume the smallest structurally correct view of a codebase instead of dumping raw files into their context window.

TL;DR — Up and Running in 30 Seconds

What it is: Graft sits between your AI coding agent and the filesystem. Instead of dumping entire files into the context window, it returns the minimum structurally correct view — full content for small files, AST-derived outlines for large ones, hard refusals for secrets and binaries. Tool responses carry receipts so agents know exactly how much context they've consumed.

Why you want it: Agents that read files naively fill their context window with lockfiles, minified output, and 2,000-line modules they only needed 10 lines of. Graft fixes that automatically.

# Install and bootstrap your repo
npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp

# Start serving (MCP over stdio — point your agent at this)
npx @flyingrobots/graft serve

# Or try a governed read from the CLI right now
npx @flyingrobots/graft read safe src/app.ts

That's it. init scaffolds .graftignore, appends agent read guidance, and writes the client config requested by the flags you pass. serve starts listening on stdio. Your agent calls safe_read instead of reading files directly, and Graft handles the rest.

The Problem

AI coding agents read files the same way a first-year developer does: grab the whole thing, every time. A 2,000-line module goes straight into the context window. So does the lockfile. So does the compiled output. So does the .env.

Context windows are finite. Once they fill up, the agent starts forgetting what it already read. Performance degrades. Hallucinations increase. You burn tokens on noise.

Graft sits between the agent and the filesystem and enforces a simple rule: return the minimum structurally correct view.

• Small file? Full content.
• Large file? A structural outline — function names, signatures, line ranges. The agent can drill in with a range read if it needs a specific function body.
• Binary, secret, or lockfile? Hard refusal with a machine-readable reason code and a suggested alternative.

Tool responses carry receipts: bytes consumed, bytes avoided, session depth, policy decision. Agents can self-regulate. Operators can audit.

Why Graft?

• Parser-backed outlines. Outlines come from Tree-Sitter ASTs, not heuristic line-scanning. Function signatures, class hierarchies, and jump tables are structurally accurate across JavaScript, TypeScript, Rust, Python, Go, GraphQL, JSON, TOML, YAML, Markdown, and more.

• Machine-readable contracts. Tool responses carry versioned _schema metadata and decision receipts. Agents reason about outcomes without scraping prose. Receipts accumulate cumulative session stats so agents know when they're burning budget.

• Structural memory across Git history. WARP (Structural Worldline Memory) is the current git-warp-backed structural history layer. Query what changed structurally — which symbols were added, removed, or renamed — without dumping source into the agent context. Graft is converging on a StructuralReadingPort boundary so Echo can become the primary causal-history substrate after parity is proven.

• Session governance. The GovernorTracker watches for anti-patterns: runaway tool loops, late-session large reads, edit/bash thrash. Tripwire signals surface in receipts so agents and operators can act before context is exhausted.

• Industrial-grade daemon. A same-user local runtime manages multi-repo authorization, persistent monitors, and shared worker pools. WARP contexts stay warm within their exact repository, worktree, and actor lanes, while bare sidecar repositories keep one agent's working graph out of both the source repository and every other agent's lane.

Three Official Entry Points

Graft exposes capabilities through three official product entry points: CLI, MCP, and API. MCP has two runtimes: repo-local stdio for a single checkout and daemon-backed stdio for multi-repo sessions.

1. CLI — Operator and Debugging Workflows

npx @flyingrobots/graft read safe src/app.ts
npx @flyingrobots/graft struct since HEAD~3
npx @flyingrobots/graft struct dead-symbols --limit 20
npx @flyingrobots/graft symbol history createUser --path src/users.ts
npx @flyingrobots/graft review --base HEAD~1
npx @flyingrobots/graft review cooldown --pr 48

Each CLI process prints and exits, which keeps scripting predictable. Commands that use WARP structural history persist their graph in a stable private CLI sidecar, so later invocations can reuse that history without writing to the source repository. That stability is one operator lane per worktree: separate one-shot CLI processes in the same worktree intentionally share it. Parallel agents that need isolated working histories should use separate MCP sessions.

2. MCP — Agent Sessions

Repo-Local Stdio

The simplest path for single-repo agent work. The current checkout is the authority. No workspace binding required.

npx @flyingrobots/graft serve

Point your MCP client at this process. Graft speaks JSON-RPC over stdin/stdout. The same binary auto-detects non-TTY stdio and enters serve mode automatically — so npx @flyingrobots/graft with no arguments works as an MCP server when piped.

Daemon-Backed Stdio

A persistent same-user runtime for long-running or multi-repo agent work. Exact repository/worktree/actor WARP contexts stay warm within the daemon, and persistent monitors can keep structural history current without storing WARP refs or objects in the source repository.

# Start the daemon explicitly
npx @flyingrobots/graft daemon

# Or let the stdio bridge auto-start/connect to the daemon
npx @flyingrobots/graft serve --runtime daemon

Daemon sessions start unbound. The shortest agent flow is:

1. Call a routed repository tool such as safe_read with an explicit cwd anywhere inside the target Git worktree.
2. Graft resolves and opens the canonical containing worktree with the default daemon capability profile, then runs the call without changing the active workspace binding.
3. Optionally call workspace_list_opened to inspect the opened worktrees.

When several agents share one daemon-backed MCP session, repo tools can carry their own explicit route: pass cwd to safe_read, file_outline, read_range, changed_since, graft_diff, graft_since, graft_map, code_show, code_find, or code_refs to open and resolve that call against the requested worktree without changing the active workspace. A missing cwd still uses the active binding, so an unbound session needs either an explicit route or an explicit open/bind first.

Use workspace_open when you want to activate a worktree or configure its capabilities. For lower-level control-plane posture, use workspace_authorize followed by workspace_bind.

WARP persistence is private sidecar state, not source-repository state. By default, Graft creates bare repositories under ~/.graft/graphs/<project>/<worktree>/<actor>/warp.git, or under $GRAFT_ROOT_PATH/graphs when that variable is set. The readable path names carry identity suffixes, and separate worktrees and MCP sessions receive separate graph stores. Advanced graphRoot overrides fail closed when blank, symlink-aliased, or overlapping the source worktree or common Git directory.

See docs/SETUP.md for client-specific bootstrap and daemon control-plane configuration.

3. API — In-Process Integration

Embed Graft directly when you want structural reads or syntax data without spawning a subprocess or going through MCP transport.

Governed repo reads (same policy enforcement as MCP, no receipts):

import { createRepoWorkspace } from "@flyingrobots/graft";

const workspace = await createRepoWorkspace({ cwd: process.cwd() });
const result = await workspace.safeRead({ path: "src/app.ts" });
// result.projection: "content" | "outline" | "refused" | "cache_hit" | "diff"

In-process tool calls with receipts (full MCP behavior, no subprocess):

import { createRepoLocalGraft, callGraftTool } from "@flyingrobots/graft";

const graft = createRepoLocalGraft({ cwd: process.cwd() });
const outline = await callGraftTool(graft, "file_outline", { path: "src/app.ts" });

Editor-native syntax highlighting (Tree-Sitter WASM, no I/O, viewport-aware):

import { createProjectionBundle, ensureParserReady } from "@flyingrobots/graft";

await ensureParserReady();

const bundle = createProjectionBundle("src/app.tsx", liveEditorText, {
  basis: { kind: "editor_head", headId: "head-42", tick: 17 },
  viewport: {
    start: { row: 0, column: 0 },
    end: { row: 80, column: 0 },
  },
});
// bundle.syntax.spans — highlight ranges for the visible viewport only

createProjectionBundle owns the WASM buffer lifecycle internally. Use createStructuredBuffer directly if you need to hold a buffer across multiple operations and manage dispose() yourself.

Edict projection bridge (dirty .edict buffer to syntax/Core/Target IR):

import {
  createEdictCliProjectionProvider,
  createProjectionProviderRegistry,
  createStructuredBuffer,
} from "@flyingrobots/graft";
import { nodeProcessRunner } from "./your-process-runner.js";

const edictProjector = createEdictCliProjectionProvider({
  processRunner: nodeProcessRunner,
  cwd: process.cwd(),
  target: {
    coordinate: "echo.dpo@1",
    profileDigest: "sha256:1111111111111111111111111111111111111111111111111111111111111111",
    irDomain: "echo.span-ir/v1",
  },
});

const projectionRegistry = createProjectionProviderRegistry().register({
  language: "edict",
  extensions: [".edict"],
  provider: { kind: "edict", provider: edictProjector },
});

const buffer = createStructuredBuffer("demo.edict", liveEditorText, {
  basis: { kind: "editor_head", headId: "head-42", tick: 18 },
  projectionRegistry,
});

const syntax = buffer.syntaxSpans();
const edict = buffer.edictProjection();
// edict?.core and edict?.targetIr preserve available/blocked/failed slot truth.

This bridge invokes Edict's projection CLI over stdin JSONL. It does not execute Echo, admit bundles, or require the editor buffer to exist on disk. Hosts may pass language: "edict" with a registry for synthetic dirty buffers such as untitled editor tabs. Direct edictProjector injection remains supported for single-language hosts.

Quick Start

# 1. Bootstrap the repo: scaffold .graftignore, seed agent instructions
npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp

# 2. Start serving (repo-local stdio MCP)
npx @flyingrobots/graft serve

Contributing with public visibility

For bugs, capability requests, and ideas, start at GitHub Issues. That queue is the public view for priorities and discussion. Internal execution and design rigor still lives in docs/method/backlog/ and docs/design/ so details remain deterministic for contributors.

Documentation

Built with precision by FLYING ROBOTS