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
Merge branch 'main' of https://github.com/NanoNets/context-graph-engine
Shrish Dwivedi92d8ef6c8400
diff --cc graft/.graph/wiring.jsonindex 1171829d,8dd89cc8..8ae57e68--- a/graft/.graph/wiring.json+++ b/graft/.graph/wiring.json@@@ -1,8 -1,8 +1,8 @@@{"meta": {"version": 1,- "nodeCount": 687,- "edgeCount": 1786,- "nodeCount": 621,- "edgeCount": 1620,++ "nodeCount": 701,++ "edgeCount": 1823,"languages": ["typescript"]@@@ -2577,12 -2728,12 +2728,12 @@@"name": "skill-template.ts","kind": "file","path": "src/claude/skill-template.ts",- "span": "L1-L73",- "span": "L1-L71",++ "span": "L1-L77","signature": null,"exported": true,"origin": "ast",- "body_hash": "504bd803d05aa6812ffaaf1a745f1eecab2fcd3e41f9029e5f0bf7db12025afd",- "chars": 3767,- "body_hash": "56d89c215e3ba0175d9f1ae2cf8baabe104c45d2b5bf2c18557ba29a4e97520b",- "chars": 3725,++ "body_hash": "4e951868562ef41f827b4828dc1931cf1e645d2e57999308b1919f62de5af7fb",++ "chars": 4071,"summary_state": "pending","summary": null,"crux": null@@@ -2592,11 -2743,11 +2743,11 @@@"name": "skillTemplate","kind": "function","path": "src/claude/skill-template.ts",- "span": "L6-L72",- "span": "L6-L70",++ "span": "L6-L76","signature": "function skillTemplate(): string","exported": true,"origin": "ast",- "body_hash": "b882ca515f8601e55047f62c13837e42e8267c6d8f8c877329a4c7f8c73a2d7b",- "body_hash": "687db45aebaf068cd90725a5fb01283394e6a3dc84be034fc828e8a11b1f4e48",++ "body_hash": "a556c949cf0d4da9758a04f07d3a0d2ba7b7630e947aca38bdaad8430ee73a2f","summary_state": "pending","summary": null,"crux": null@@@ -3256,12 -3407,12 +3407,12 @@@"name": "cli.ts","kind": "file","path": "src/cli.ts",- "span": "L1-L415",- "span": "L1-L363",++ "span": "L1-L430","signature": null,"exported": true,"origin": "ast",- "body_hash": "5d7096b1320ec7422299df6fed455208659e6d91d76d1cb6c81bc9e9a0bc046d",- "chars": 17906,- "body_hash": "305a20f34e586f22be7eee9b5d3084586d96e1edfec50a819deb4c83978ee265",- "chars": 16131,++ "body_hash": "16405afe8b55c6c376785cbd9ddb2854631f6985ab287b5ac230189bf360d00e",++ "chars": 18761,"summary_state": "stale","summary": "This file implements the `graft` CLI tool for building and maintaining a context graph from code, ensuring it stays in sync with the repository.","crux": {@@@ -3308,7 -3459,7 +3459,7 @@@"name": "traverseAction","kind": "function","path": "src/cli.ts",- "span": "L242-L248",- "span": "L254-L260",++ "span": "L257-L263","signature": "function traverseAction(kind: import(\"./graph/traverse-cli.js\").TraverseKind)","exported": false,"origin": "ast",@@@ -6756,12 -6344,12 +6907,12 @@@"name": "instructions.ts","kind": "file","path": "src/hosts/instructions.ts",- "span": "L1-L61",- "span": "L1-L62",++ "span": "L1-L65","signature": null,"exported": true,"origin": "ast",- "body_hash": "36cac50d0acd13aaadb2459199cd9fc9e4ae60a955b62fd592175d2a81835de6",- "chars": 2389,- "body_hash": "b86b1f2dcc4d0b1e393c89f39cb772f76d5c592393f758603cfc20373fd98821",- "chars": 2427,++ "body_hash": "1dddea660f4d5e65952faf2beee42f04153ccab893658e75bda1dce6c0245b18",++ "chars": 2627,"summary_state": "pending","summary": null,"crux": null@@@ -6771,7 -6359,7 +6922,7 @@@"name": "cursorRule","kind": "function","path": "src/hosts/instructions.ts",- "span": "L40-L47",- "span": "L41-L48",++ "span": "L44-L51","signature": "function cursorRule(): string","exported": true,"origin": "ast",@@@ -6785,11 -6373,11 +6936,11 @@@"name": "instructionBody","kind": "function","path": "src/hosts/instructions.ts",- "span": "L6-L38",- "span": "L6-L39",++ "span": "L6-L42","signature": "function instructionBody(): string","exported": true,"origin": "ast",- "body_hash": "5b5f2c1d46bcf84a58b255e183baf95ce52319002cd06aee6f8757cf846164da",- "body_hash": "8cc2c40fcc950972a65305ce9773fa1e2bd0e99af84531af60f6ab1420b76697",++ "body_hash": "9003c83453867680b4936696a28bb8086e14e432bb3c3debc4d7e5ab5ab7a0be","summary_state": "pending","summary": null,"crux": null@@@ -6799,7 -6387,7 +6950,7 @@@"name": "kiroSteering","kind": "function","path": "src/hosts/instructions.ts",- "span": "L49-L55",- "span": "L50-L56",++ "span": "L53-L59","signature": "function kiroSteering(): string","exported": true,"origin": "ast",@@@ -6813,7 -6401,7 +6964,7 @@@"name": "windsurfRule","kind": "function","path": "src/hosts/instructions.ts",- "span": "L57-L60",- "span": "L58-L61",++ "span": "L61-L64","signature": "function windsurfRule(): string","exported": true,"origin": "ast",@@@ -7203,12 -6791,12 +7354,12 @@@"name": "tools.ts","kind": "file","path": "src/mcp/tools.ts",- "span": "L1-L221",- "span": "L1-L193",++ "span": "L1-L243","signature": null,"exported": true,"origin": "ast",- "body_hash": "ee469ba03cc30f58916d1b6ab624664242fd3c743832e25f617b5a8b15d0530c",- "chars": 9923,- "body_hash": "2f134f9db2767f3595dbd3db26849ef5fb6e23bf58c3019d73e1f716c9eef7db",- "chars": 8152,++ "body_hash": "26d386319a711ec0eb758a2561513dc05e164f2c4d5828b6089b41db2b0a715b",++ "chars": 10847,"summary_state": "pending","summary": null,"crux": null@@@ -7218,11 -6806,11 +7369,11 @@@"name": "callTool","kind": "function","path": "src/mcp/tools.ts",- "span": "L133-L220",- "span": "L120-L192",- "signature": "function callTool( root: string, name: string, args: Record<string, unknown>, ): { text: string; isError: boolean }",++ "span": "L149-L242",+ "signature": "function callTool( root: string, name: string, args: Record<string, unknown>, dirOverride?: string, ): { text: string; isError: boolean }","exported": true,"origin": "ast",- "body_hash": "aeeebfde3d08b44b32953ecc1b8f6358f1958fe6728baa378b2dcb1c306ff1ef",- "body_hash": "5001ab4af1ff126fc4c0361469b41b8a7c3e44f1c26fb64d103d0a0fb3ec55be",++ "body_hash": "ff7c769fef542a2ef86fd774fd9ad72aee3dc1745d295a675c530f76c530dab2","summary_state": "pending","summary": null,"crux": null@@@ -7232,7 -6820,7 +7383,7 @@@"name": "renderMatches","kind": "function","path": "src/mcp/tools.ts",- "span": "L121-L131",- "span": "L108-L118",++ "span": "L137-L147","signature": "function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string","exported": false,"origin": "ast",@@@ -9185,12 -8348,12 +9378,12 @@@"name": "mcp-server.test.ts","kind": "file","path": "test/mcp-server.test.ts",- "span": "L1-L67",- "span": "L1-L66",++ "span": "L1-L68","signature": null,"exported": true,"origin": "ast",- "body_hash": "69674cd877124d732de6426d45e9ad9d90031a3da4dfe8be54d893ebf1513337",- "chars": 2582,- "body_hash": "7cd0e518acabc53f7285a65502a76331813da3ed224b70795ce39801b666c2ee",- "chars": 2569,++ "body_hash": "4d828181f0a8c645f00097ab43c2bdcf5bc65da276e83b7503bc2888ae09f254",++ "chars": 2604,"summary_state": "pending","summary": null,"crux": null@@@ -9214,12 -8377,12 +9407,12 @@@"name": "mcp-tools.test.ts","kind": "file","path": "test/mcp-tools.test.ts",- "span": "L1-L279",- "span": "L1-L188",++ "span": "L1-L290","signature": null,"exported": true,"origin": "ast",- "body_hash": "68ce4d5883e0812cc246d9731bf4c1049a6db68b17646765d01161654d522b77",- "chars": 12154,- "body_hash": "36116ac8d25d8e7aa0dc185bc4171041602523889d693ee1f25f532c397446f0",- "chars": 8150,++ "body_hash": "22d3a32a85a0ba1542969786e8bda07d3df02ee068554d4070f705d30d7239dc",++ "chars": 12646,"summary_state": "pending","summary": null,"crux": nulldiff --cc graft/src/claude/skill-template.mdindex ea4f4582,bb11a369..4b6deeb8--- a/graft/src/claude/skill-template.md+++ b/graft/src/claude/skill-template.md@@@ -1,3 -1,3 +1,3 @@@# src/claude/skill-template.ts- - skillTemplate · function · L6-L72 — function skillTemplate(): string-- skillTemplate · function · L6-L70 — function skillTemplate(): string++- skillTemplate · function · L6-L76 — function skillTemplate(): stringdiff --cc graft/src/cli.mdindex 40fb37f3,dc1ff14d..36f27da2--- a/graft/src/cli.md+++ b/graft/src/cli.md@@@ -2,6 -2,6 +2,6 @@@This file implements the `graft` CLI tool for building and maintaining a context graph from code, ensuring it stays in sync with the repository.-- engineFrom · function · L41-L44 — Creates an instance of the Graft engine configured with the specified context directory.-- fmt · function · L80-L84 — Formats a record of counts into a human-readable string for console output.-- traverseAction · function · L254-L260 — function traverseAction(kind: import("./graph/traverse-cli.js").TraverseKind)+- engineFrom · function · L43-L46 — Creates an instance of the Graft engine configured with the specified context directory.+- fmt · function · L82-L86 — Formats a record of counts into a human-readable string for console output.- - traverseAction · function · L242-L248 — function traverseAction(kind: import("./graph/traverse-cli.js").TraverseKind)++- traverseAction · function · L257-L263 — function traverseAction(kind: import("./graph/traverse-cli.js").TraverseKind)diff --cc graft/src/hosts/instructions.mdindex 2f439f6a,f63ea87f..1ae906f8--- a/graft/src/hosts/instructions.md+++ b/graft/src/hosts/instructions.md@@@ -1,6 -1,6 +1,6 @@@# src/hosts/instructions.ts- - instructionBody · function · L6-L38 — function instructionBody(): string- - cursorRule · function · L40-L47 — function cursorRule(): string- - kiroSteering · function · L49-L55 — function kiroSteering(): string- - windsurfRule · function · L57-L60 — function windsurfRule(): string-- instructionBody · function · L6-L39 — function instructionBody(): string-- cursorRule · function · L41-L48 — function cursorRule(): string-- kiroSteering · function · L50-L56 — function kiroSteering(): string-- windsurfRule · function · L58-L61 — function windsurfRule(): string++- instructionBody · function · L6-L42 — function instructionBody(): string++- cursorRule · function · L44-L51 — function cursorRule(): string++- kiroSteering · function · L53-L59 — function kiroSteering(): string++- windsurfRule · function · L61-L64 — function windsurfRule(): stringdiff --cc graft/src/mcp/tools.mdindex 6159e69c,5c6e5de5..0348feb6--- a/graft/src/mcp/tools.md+++ b/graft/src/mcp/tools.md@@@ -1,6 -1,6 +1,6 @@@# src/mcp/tools.ts-- ToolDef · interface · L15-L19 — interface ToolDef-- unknownSymbolText · function · L26-L28 — function unknownSymbolText(query: string): string-- renderMatches · function · L108-L118 — function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string-- callTool · function · L120-L192 — function callTool( root: string, name: string, args: Record<string, unknown>, ): { text: string; isError: boolean }+- ToolDef · interface · L18-L22 — interface ToolDef+- unknownSymbolText · function · L29-L31 — function unknownSymbolText(query: string): string- - renderMatches · function · L121-L131 — function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string- - callTool · function · L133-L220 — function callTool( root: string, name: string, args: Record<string, unknown>, dirOverride?: string, ): { text: string; isError: boolean }++- renderMatches · function · L137-L147 — function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string++- callTool · function · L149-L242 — function callTool( root: string, name: string, args: Record<string, unknown>, dirOverride?: string, ): { text: string; isError: boolean }diff --cc src/hosts/instructions.tsindex 14039423,91819990..a6e38f61--- a/src/hosts/instructions.ts+++ b/src/hosts/instructions.ts@@@ -12,17 -12,18 +12,21 @@@ system and carry exact file:line spansFor 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 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 — run- \`graft grep "<literal>"\` instead (exhaustive over indexed files, grouped by- enclosing symbol), falling back to raw \`grep -rn\` only for unindexed files.+ code spans inlined (each hit's ≤8-line crux by default; \`--full\` for whole+ definitions when the crux isn't enough). 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.++ 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 skeleton <file>\` → every definition's signature + span, ~10× cheaper+ than reading the file; use it to skim an API surface.- \`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 --cc src/mcp/tools.tsindex 91a124e1,31833c92..3e3952a3--- a/src/mcp/tools.ts+++ b/src/mcp/tools.ts@@@ -142,12 -128,18 +158,18 @@@ export function callToolconst query = String(args.query ?? '');if (!query) return { text: 'graft_ask requires a query', isError: true };const limit = typeof args.limit === 'number' ? args.limit : 5;- const engine = new Graft();+ const engine = new Graft({ contextDir: dirOverride });- const r = engine.ask(root, query, { limit, source: true });+ const r = engine.ask(root, query, { limit, source: true, full: args.full === true });return { text: formatAsk(r), isError: false };}+ case 'graft_skeleton': {+ const file = String(args.file ?? '');+ if (!file) return { text: 'graft_skeleton requires a file', isError: true };- const r = skeleton(root, file);++ const r = skeleton(root, file, { contextDir: dirOverride });+ return { text: formatSkeleton(r), isError: !r.entries.length && !!r.note };+ }case 'graft_check': {- const engine = new Graft();+ const engine = new Graft({ contextDir: dirOverride });const r = engine.check(root);const g = engine.checkGraph(root);const parts = [formatCheckReport(r)];diff --cc test/mcp-tools.test.tsindex 05f472a4,3b30a795..6ab6e266--- a/test/mcp-tools.test.ts+++ b/test/mcp-tools.test.ts@@@ -59,22 -47,10 +59,23 @@@ function fileScopeRepo(): stringreturn d;}-test('TOOLS lists all six tools with schemas', () => {+/** Five top-level dirs, one file each — enough groups that a small `max_dirs`+ * actually drops some, so the `graft_map` `max_dirs` arg has something to+ * prove it's wired through to `buildRepoMap`. */+function multiDirRepo(): string {+ const d = mkdtempSync(join(tmpdir(), 'graft-mcptools-multidir-'));+ for (const dir of ['aaa', 'bbb', 'ccc', 'ddd', 'eee']) {+ mkdirSync(join(d, dir), { recursive: true });+ writeFileSync(join(d, dir, 'x.ts'), `export function ${dir}Fn(): number {\n return 1;\n}\n`);+ }+ execFileSync(process.execPath, ['--import', 'tsx', 'src/cli.ts', 'build', d], { stdio: 'pipe' });+ return d;+}+- test('TOOLS lists all seven tools with schemas', () => {++test('TOOLS lists all eight tools with schemas', () => {assert.deepEqual(TOOLS.map((t) => t.name), ['graft_ask',+ 'graft_skeleton','graft_check','graft_blast_radius','graft_callers',@@@ -202,77 -176,12 +203,87 @@@ test('graft_blast_radius: unknown symboassert.match(r.text, /check spelling/);});+test('graft_grep round-trips a hit on the built fixture, grouped by enclosing symbol', () => {+ const d = builtRepo();+ const r = callTool(d, 'graft_grep', { pattern: 'add' });+ assert.equal(r.isError, false);+ assert.match(r.text, /"add" — \d+ hits? in \d+ symbols? across \d+ files? \(searched \d+ indexed files\)/);+ assert.match(r.text, /src\/math\.ts/);+});++test('graft_grep: no hits is a soft (non-error) result with the loud fallback note', () => {+ const d = builtRepo();+ const r = callTool(d, 'graft_grep', { pattern: 'noSuchPatternAnywhere' });+ assert.equal(r.isError, false);+ assert.match(r.text, /no hits for "noSuchPatternAnywhere"/);+ assert.match(r.text, /grep -rn "noSuchPatternAnywhere"/);+});++test('graft_grep: missing pattern and unbuilt repo are soft errors', () => {+ const d = builtRepo();+ const r1 = callTool(d, 'graft_grep', {});+ assert.equal(r1.isError, true);+ assert.match(r1.text, /requires a pattern/);++ const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-grep-bare-'));+ const r2 = callTool(bare, 'graft_grep', { pattern: 'add' });+ assert.equal(r2.isError, true);+ assert.match(r2.text, /graft build/);+});++test('graft_map round-trips a repo orientation on the built fixture', () => {+ const d = builtRepo();+ const r = callTool(d, 'graft_map', {});+ assert.equal(r.isError, false);+ assert.match(r.text, /^repo map — \d+ files · \d+ symbols · \d+ edges/);+ assert.match(r.text, /src/);+ assert.match(r.text, /hotspots:/);+});++test('graft_map: unbuilt repo is a soft isError with the no-graph message', () => {+ const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-map-bare-'));+ const r = callTool(bare, 'graft_map', {});+ assert.equal(r.isError, true);+ assert.match(r.text, /graft build/);+});++test('graft_map: max_dirs arg is honored — the MCP escape hatch for dropped dirs', () => {+ const d = multiDirRepo();++ const capped = callTool(d, 'graft_map', { max_dirs: 1 });+ assert.equal(capped.isError, false);+ assert.match(capped.text, /\+4 more directories not shown/);++ const raised = callTool(d, 'graft_map', { max_dirs: 10 });+ assert.equal(raised.isError, false);+ assert.doesNotMatch(raised.text, /more directories? not shown/);+});++test('callTool honors a dirOverride for a graph built in a non-default dir', () => {+ const { repo, graphDir } = customDirRepo();++ // With the override pointing at the actual graph location, tools find it.+ const check = callTool(repo, 'graft_check', {}, graphDir);+ assert.equal(check.isError, false);+ assert.match(check.text, /graph check: OK/);++ const callers = callTool(repo, 'graft_callers', { symbol: 'add' }, graphDir);+ assert.equal(callers.isError, false);+ assert.match(callers.text, /calls ← sub \(src\/math\.ts:/);++ // Without the override, tools fall back to the default `<repo>/graft`,+ // which doesn't exist here — must report no graph, not silently succeed.+ const noOverride = callTool(repo, 'graft_callers', { symbol: 'add' });+ assert.equal(noOverride.isError, true);+ assert.match(noOverride.text, /graft build/);+});+++ test('graft_skeleton returns signatures for a file, errors on unknown file', () => {+ const d = builtRepo();+ const r = callTool(d, 'graft_skeleton', { file: 'src/math.ts' });+ assert.equal(r.isError, false);+ assert.match(r.text, /graft skeleton — src\/math\.ts/);+ assert.match(r.text, /function add {2}function add\(a: number, b: number\): number/);+ const miss = callTool(d, 'graft_skeleton', { file: 'src/nope.ts' });+ assert.equal(miss.isError, true);+ });