Graft

graft

graft/ holds a graph of this repo: small markdown nodes that each explain one part in prose and name the exact file:line spans they cover, plus a wiring graph of who-calls-what. Querying a node costs a few hundred tokens; rebuilding that understanding by reading source costs thousands, and misses the edges.

Each command below is a local graft command, needs no API key, and returns in under a second. There are six of them. Pick the one that fits the task, run it, act on the answer; don't chain tools hoping for more. Most tasks need one call.

The tools

1 · graft ask "<question>" --source: locate + understand (the default)

Ranked retrieval over the graph, routed automatically between prose nodes and the wiring graph, returning the top hits with exact file:line.

• --source inlines the code at each hit, the ≤8-line crux of each definition, so the result IS the code you need, no follow-up file read. Add --full only when the crux is too small to act on.
• --in <path> narrows to a subtree before ranking; -n N caps results (default 8).
• Use it when the question is conceptual or locational: "how does auth work", "where is rate-limiting handled", "what assembles the request pipeline".
• One ask usually answers. A genuinely multi-part question needs one ask per distinct sub-aspect, never the same question reworded. Few or weak hits mean switch tool (grep / skeleton / callers), don't re-ask.

2 · graft grep "<pattern>": exhaustive find

Regex (or --fixed for a literal) over every indexed file, hits grouped by enclosing symbol and ranked by coupling; it also reports files it couldn't read.

• Use it when you need every occurrence: all call sites, all uses of a constant, all providers. ask is ranked top-N and will miss instances; grep won't. One grep replaces a spray of asks.
• Search a short symbol name or literal, not a full guessed signature: an over-specific regex (func (s *Server) GenerateHandler) returns nothing even when the code is indexed. If a grep misses, loosen it (drop the receiver and signature, keep the bare name) and retry graft grep — do NOT switch to raw grep -rn, which is slower and unranked.
• -i case-insensitive; --in <path> scopes to a subtree. Raw grep -rn is only for files graft genuinely doesn't index (docs, configs, brand-new files).

3 · graft skeleton <file>: a file's API at a glance

Signatures-only view of one file (every function / method / type with its span) in ~200 tokens, ~10x cheaper than reading the file.

• Use it when you need "what's in this file / what can I call here" before editing or wiring into it. One skeleton is the whole answer for a file; don't re-skeleton the same file, and don't skeleton every file map already named.

4 · graft callers <symbol>: the exact edges

Precomputed call/reference edges, not a text search. Symbol can be bare (Foo), qualified (Class.method), or package-qualified (pkg.Fn).

• default --direction in: who calls/references this; run before you rename, delete, or change its signature.
• --direction out: what this symbol itself calls/depends on (the old callees).
• --depth N: walk transitively N hops for the full blast radius (the old impact); --depth 2 is the usual "what breaks if I touch this".
• --depth all: the entire connected closure — every source reachable through the edges. Reach for this before a refactor, rename, or any multi-file change: it surfaces the sibling and downstream files (platform variants, a module you must split out) that a single-file edit would miss.

5 · graft map: orientation for an unfamiliar repo or area

A token-budgeted tour: directory clusters, per-directory hubs, and global hotspots, straight from the wiring graph.

• Use it when you land in a repo cold or are asked for "the architecture". map alone is the answer: read the hub cards it names; do NOT then skeleton or ask your way through every subsystem it lists. --max-dirs N widens it.

6 · Lifecycle: graft build / graft check

Every tool above refreshes the graph itself before answering, so what those tools return always describes the code as it is right now — including edits you just made and have not committed. You do not need to run build after editing.

One caveat, if you grep the markdown under graft/ directly: those cards are a projection, rebuilt at the end of the turn rather than on each query, so after an edit they can lag. The tools above never do — prefer them, and treat a card's spans as stale if you have edited that file this turn.

build is for the LLM layer (--deep adds a concept map; skip unless asked); check fails when graft/ is stale, for CI.