Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

docs(guidance): sweeps via graft grep, orientation via graft map

Shrish Dwivedidf1745aea4d2
diff --git a/README.md b/README.md
index 5d50e4e4..6b05f124 100644
--- a/README.md
+++ b/README.md
@@ -192,6 +192,13 @@ graft callers <symbol> [dir] # who calls/references/imports/implements/e
graft 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 code
graft check --json # print the drift report as JSON
@@ -212,6 +219,44 @@ graft --dir <path> # use a context dir other than <repo>/graft
graft --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 dev
diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.ts
index 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 them
all.
+**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 go
straight to precomputed edges:
diff --git a/src/hosts/instructions.ts b/src/hosts/instructions.ts
index 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 opening
source 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 relevant
code spans inlined. Match the tool to the task shape: for understanding or
editing, the top node IS the answer — cite its \`covers:\` file:line spans and
edit 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]\` give
precomputed, exact edges — who calls/is called by a symbol, and the full
blast 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.ts
index 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.ts
index 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');
});