Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
docs(guidance): sweeps via graft grep, orientation via graft map
Shrish Dwivedidf1745aea4d2
diff --git a/README.md b/README.mdindex 5d50e4e4..6b05f124 100644--- a/README.md+++ b/README.md@@ -192,6 +192,13 @@ graft callers <symbol> [dir] # who calls/references/imports/implements/egraft callees <symbol> [dir] # what a symbol calls/references/imports/implements/extends (no LLM, no key)graft impact <symbol> [dir] -d N # BFS over incoming edges — who breaks if this symbol changes (no LLM, no key)+graft grep "<regex>" [dir] # exhaustive regex search over indexed files, grouped by enclosing symbol (no LLM, no key)+graft grep "<regex>" --in <symbol> # narrow to one symbol/module group+graft grep "<regex>" -i --fixed # case-insensitive; treat the pattern as a literal string, not a regex++graft map [dir] # token-budgeted repo orientation — dir clusters, hubs, hotspots (no LLM, no key)+graft map --max-dirs N # raise/lower the number of directories shown+graft check [dir] # fail (exit 1) if graft/ has drifted from the codegraft check --json # print the drift report as JSON@@ -212,6 +219,44 @@ graft --dir <path> # use a context dir other than <repo>/graftgraft --version, -v # print the installed version and exit```+Method calls resolve through the receiver's type — constructor assignments+(`self.router = APIRouter()`) and type annotations, not just the call-site+name — so `callers`/`impact`/`grep --in` return calls bound to the right+type on method-heavy code, not every method anywhere with that name.++## Search & orient (`graft grep` / `graft map`)++`graft grep "<regex>"` is exhaustive over every indexed file and groups hits+by enclosing symbol, ranked by the same in-edge coupling `graft map` uses —+built for "every occurrence of this pattern" tasks where `graft ask`'s+ranked top-N isn't enough:++```+"NEEDLE" — 2 hits in 2 symbols across 1 files (searched 1 indexed files)++heavilyCalled · function · src/a.ts:L1-L3 · 3 in-edges+ L2: console.log("NEEDLE hit in heavilyCalled");++rarelyCalled · function · src/a.ts:L4-L6 · 0 in-edges+ L5: console.log("NEEDLE hit in rarelyCalled");+```++`graft map` is a token-budgeted first look at a repo — directory clusters+with file/symbol counts, each dir's local hubs, and the global hotspots —+all ranked by in-degree, no LLM, no key:++```+repo map — 105 files · 582 symbols · 1815 edges · typescript++src/ 54 files · 414 symbols hubs: set (bindings.ts, 38←), contextDirFor (node-file.ts, 11←), wiringPath (write.ts, 10←)+test/ 36 files · 68 symbols hubs: edge (graph-traverse.test.ts, 4←), graphOf (graph-traverse.test.ts, 4←), nodeStub (graph-traverse.test.ts, 3←)+viewer/ 5 files · 58 symbols hubs: $ (main.ts, 9←), activeGraph (main.ts, 5←), cvar (data.ts, 5←)+bench/ 8 files · 42 symbols hubs: makeClient (llm.ts, 3←), buildMarkdown (report.ts, 2←), judge (judge.ts, 2←)+scripts/ 2 files · 0 symbols++hotspots: set · method · src/graph/bindings.ts:L21-L23 · 38← contextDirFor · function · src/context/node-file.ts:L100-L103 · 11← wiringPath · function · src/graph/write.ts:L20-L22 · 10← ...+```+## Visualize it (`graft viz`)`graft viz` opens a local, interactive view of both graphs — no install, no devdiff --git a/src/claude/skill-template.ts b/src/claude/skill-template.tsindex 0bf2a2d3..33ec8f93 100644--- a/src/claude/skill-template.ts+++ b/src/claude/skill-template.ts@@ -29,6 +29,10 @@ same understanding costs thousands.symbol, or filename hits the node that covers it; \`graft/INDEX.md\` lists themall.+**First contact with an unfamiliar repo:** run \`graft map\` before exploring —+a token-budgeted orientation (dir clusters, hubs, hotspots) built straight from+the wiring graph, no LLM, no key.+**Match the tool to the task shape:**- **Understanding, explaining, locating where a change goes** — the node IS the@@ -41,10 +45,12 @@ same understanding costs thousands.change at the named \`file:line\` — never read the whole file to get oriented;the pack already oriented you.- **Exhaustive tasks — "every occurrence / every provider / every caller of- this pattern":** ranked results are top-N, not a complete list. Use graft to- orient (what is the pattern, where does it live), then ENUMERATE with grep- over the source and verify each hit. Ask alone will miss instances; that is- expected, not a graft failure.+ this pattern":** ranked results are top-N, not a complete list. Run+ \`graft grep "<literal>"\` instead — it's exhaustive over every indexed file,+ grouped by enclosing symbol, and tells you what it couldn't see (unreadable+ or unindexed files). Fall back to raw \`grep -rn\` only for files graft+ doesn't index (docs, configs, new files). Ask alone will miss instances;+ that is expected, not a graft failure.**Precise graph modes** — for structural questions, skip ranking and gostraight to precomputed edges:diff --git a/src/hosts/instructions.ts b/src/hosts/instructions.tsindex f49da7c3..14039423 100644--- a/src/hosts/instructions.ts+++ b/src/hosts/instructions.ts@@ -12,14 +12,17 @@ system and carry exact file:line spans, kept in sync with the code through git.For ANY task here — understanding how something works, finding where code lives,or scoping a change — get context from the graph before grepping or openingsource files. Re-ask freely (it's cheap) and reuse literal identifiers you-already have (symbol, error string, file name) as the query.+already have (symbol, error string, file name) as the query. New to this repo?+Run \`graft map\` first — a token-budgeted orientation (dir clusters, hubs,+hotspots), no LLM, no key.- Run \`graft ask "<your question>" --source\` → ranked nodes with the relevantcode spans inlined. Match the tool to the task shape: for understanding orediting, the top node IS the answer — cite its \`covers:\` file:line spans andedit straight from \`--source\`. For exhaustive tasks ("every occurrence /- every caller of this pattern"), ranked results are top-N, not complete — use- graft to orient, then enumerate with grep over the source and verify each hit.+ every caller of this pattern"), ranked results are top-N, not complete — run+ \`graft grep "<literal>"\` instead (exhaustive over indexed files, grouped by+ enclosing symbol), falling back to raw \`grep -rn\` only for unindexed files.- \`graft callers/callees <symbol>\` and \`graft impact <symbol> [-d N]\` giveprecomputed, exact edges — who calls/is called by a symbol, and the fullblast radius — for structural questions, skip ranking and use these directly.diff --git a/test/claude-skill-template.test.ts b/test/claude-skill-template.test.tsindex ca63d087..f6da133b 100644--- a/test/claude-skill-template.test.ts+++ b/test/claude-skill-template.test.ts@@ -15,4 +15,6 @@ test('skill template is a well-formed SKILL.md', () => {assert.match(body, /graft callees/, 'body teaches the callees command');assert.match(body, /graft impact/, 'body teaches the impact command');assert.match(body, /truncated/i, 'body tells the agent to follow up on truncated spans');+ assert.match(body, /graft grep/, 'body routes sweeps to graft grep');+ assert.match(body, /graft map/, 'body tells the agent to orient with graft map before exploring');});diff --git a/test/hosts-instructions.test.ts b/test/hosts-instructions.test.tsindex fac9aee2..b17b6f08 100644--- a/test/hosts-instructions.test.ts+++ b/test/hosts-instructions.test.ts@@ -11,6 +11,8 @@ test('canonical body names the three essentials', () => {assert.match(b, /every occurrence|enumerate with grep/i, 'teaches the exhaustive-task grep rule');assert.match(b, /callers/, 'teaches the callers/callees/impact commands');assert.match(b, /truncated/i, 'tells the agent to follow up on truncated spans');+ assert.match(b, /graft grep/, 'routes sweeps to graft grep');+ assert.match(b, /graft map/, 'tells the agent to orient with graft map before exploring');assert.ok(!/\bhook|statusline\b/i.test(b), 'no host-specific machinery in the shared body');});