{"slug": "show-hn-sonde-a-local-code-graph-for-ai-agents-that-refuses-to-guess", "title": "Show HN: Sonde, a local code graph for AI agents that refuses to guess", "summary": "Sonde, a local code-context engine for AI coding agents, claims to match agentic search recall on structural tasks while using 3x less context, 8x fewer tool calls, and 147x less wall-clock time, based on benchmarks on a 19,409-line TypeScript repository. The tool, published on GitHub by Cheppu Labs, indexes repositories into a symbol-level graph in SQLite and exposes three MCP tools, but it scores 0.00 on behavioral queries without shared vocabulary.", "body_md": "A local code-context engine for AI coding agents. Sonde indexes a TypeScript,\nPython, or Swift repository into a symbol-level graph in SQLite and exposes\nthree MCP tools — `find_symbols`\n\n, `query_graph`\n\n, and `get_impact_radius`\n\n— so an\nagent can answer *who calls this*, *what breaks if I change it*, and *which\ntests relate to it* in one call instead of a search loop.\n\nThe honest claim is **not** \"finds what grep cannot\". A competent agentic search\nloop finds the same structural evidence — we measured it, on a real 19,409-line\nrepository, and it scored 1.000 recall on every task.\n\nThe claim is **the same answers for a fraction of the cost, inside a budget**:\n\n| On real production TypeScript | Sonde | Agentic search |\n|---|---|---|\n| Recall on structural tasks | 1.00 |\n1.00 |\n| Tool calls | 1.0 |\n8.0 |\n| Context tokens | 1,262 |\n3,621 |\n| Latency | 263 ms |\n38,602 ms |\n| Runs that blew the token budget | 0 of 6 |\n3 of 6 |\n\nSonde matches the baseline's answers on every structural task while using ~3× less context, 8× fewer calls, and ~147× less wall-clock time — and it never exceeds the caller's token budget, because the packer truncates to it by construction. That is the trade being offered.\n\n**Where it loses.** Behavioural queries with no shared vocabulary — *\"where is\nthe retry backoff decided?\"* — score 0.00. Local semantic retrieval was built\nand measured and does not fix it (see the design doc §2.2); the capability is\ntherefore not claimed. If your questions are mostly of that shape, an agentic\nsearch loop is the better tool today.\n\nNumbers are reproducible: `npm run bench:fixture && npm run bench:large`\n\n.\nFull results in [BENCHMARK-LARGE.md](/anishmoncivarghese/sonde/blob/main/BENCHMARK-LARGE.md) and\n[BENCHMARK.md](/anishmoncivarghese/sonde/blob/main/BENCHMARK.md).\n\n```\nnpm install -g @cheppulabs/sonde\ncd your-project\nsonde init\n```\n\n`sonde init`\n\nindexes the repository and registers sonde as an MCP server in\nthis project's `.mcp.json`\n\n, asking before it writes anything (skip the prompt\nwith `sonde init --yes`\n\n). It never touches an `.mcp.json`\n\nit can't safely merge\ninto — an existing `sonde`\n\nentry that differs from what `init`\n\nwould write is\nleft alone and reported, not overwritten.\n\nFor Python repositories, use `sonde init --resolve`\n\n; the default tree-sitter\ntier did not pass the project's placement gate for structural queries.\n\nEquivalent by hand, if you'd rather see every step:\n\n```\nsonde index .\n# then add to .mcp.json:\n# { \"mcpServers\": { \"sonde\": { \"command\": \"sonde\", \"args\": [\"mcp\", \"serve\", \".\"] } } }\n```\n\nNo account or hosted service is required.\n\n`sonde doc`\n\nwrites an [ ARCHITECTURE.md](/anishmoncivarghese/sonde/blob/main/ARCHITECTURE.md) describing the\nrepository's modules, how they depend on each other, and what each one exposes —\ngenerated from the graph, so it reports what the code actually does rather than\nwhat someone remembered.\n\n```\nsonde doc            # write ARCHITECTURE.md\nsonde doc --stdout   # print it instead\nsonde doc --check    # fail if it is out of date (for CI)\nsonde doc --module src/store   # symbol-level detail, never committed\n```\n\nIt is meant to be committed and regenerated, not hand-edited. Regeneration is\nbyte-identical when nothing changed, so it does not churn your diffs; when two\nbranches both regenerate it, resolve the conflict by running `sonde doc`\n\nagain\nrather than merging by hand. It refuses to overwrite an `ARCHITECTURE.md`\n\nit did\nnot generate.\n\nThree things it deliberately does **not** do:\n\n**It does not draw a dependency it cannot evidence.** Module pairs that merely share symbol names are excluded and counted separately. On this repository two adapters share the filenames`symbols.ts`\n\n,`parser.ts`\n\nand`references.ts`\n\n, which manufactured 62 heuristic \"references\" between modules that never import each other — once the second-heaviest arrow in the diagram.**It does not pretend the diagram is complete.** The diagram shows the heaviest dependencies and states how many it omitted; the table below it goes further, and`--module`\n\nhas the rest. A diagram containing every dependency is unreadable and therefore shows nothing.**It does not claim to be current when it is not.** The header names the commit it describes and warns when files have changed since.\n\n**Never returns stale source bytes.** Whenever a response includes source, Sonde re-reads and re-hashes the indexed byte range before returning it (spec §8.1, Guarantee A).**Always reports structural drift**, rather than claiming completeness it cannot verify (spec §8.1, Guarantee B).`sonde status`\n\nshows the same drift and tier distribution carried by tool response envelopes.**Every edge is tier-labelled by how it was found**—`COMPILER`\n\n(resolved exactly by a bundled type checker under`--resolve`\n\n: the TypeScript compiler for TypeScript, pyright for Python),`LEXICAL`\n\n(resolved through an import binding or lexical scope),`HEURISTIC`\n\n(member access or another relationship requiring type inference),`EXTERNAL`\n\n(target outside the indexed repository), or`UNRESOLVED`\n\n(genuinely unplaceable, with a reason).**Never fabricates an edge.** An unresolved reference becomes`EXTERNAL`\n\nor`UNRESOLVED`\n\n— never a guessed target and never a silently dropped reference.\n\nSonde measures its zero-setup tree-sitter path against the TypeScript\ncompiler on a pinned fixture and publishes the result, unflattering numbers\nincluded (spec §12). `COMPILER`\n\nedges use that compiler directly, so comparing\nthem back to the same authority would not be an independent accuracy test.\n\nGenerated: 2026-08-23T18:16:41.557Z TypeScript: 5.9.3 (bundled; repository TypeScript is never loaded)\n\n**What these numbers cover.** The oracle measures the tree-sitter resolution\npath — the zero-setup default, and the only tier whose accuracy is in question.\nCOMPILER-tier edges come from the TypeScript compiler itself, so scoring them\nagainst the same compiler would measure nothing; they are exact by construction\nand excluded from these figures. Run `sonde index --resolve`\n\nto produce them.\n\nThe oracle is filtered to in-repo targets; `node_modules`\n\nand `.d.ts`\n\ndeclarations are excluded. Type-only references, JSX intrinsics, `export =`\n\n,\ndecorators, and declaration merging are known expected divergences (spec §10).\nTier rows compare that tier alone with the complete oracle, making each tier's\nindependent contribution visible; `ALL`\n\nis the combined result.\n\nThese divergences are structural, so reading a precision figure as \"how often Sonde is wrong\" overstates the error rate:\n\n**Ambiguous member calls emit every candidate.** For`x.foo()`\n\nwith two visible`foo`\n\ndeclarations, Sonde emits both as confidence-weighted`HEURISTIC`\n\nedges. At most one matches the compiler, so the other counts as a false positive by construction. The alternative is guessing a single target, which invariant 1 forbids — a wrong resolved-looking edge is worse than two honestly heuristic ones. Precision is therefore capped below 1.000 wherever the fixture contains an ambiguous call.**Constructor calls are ours alone.** Sonde emits`CALLS`\n\nfor`new Foo()`\n\n; the oracle does not model them, so each one is a false positive against ground truth that omits it.**Member-level IMPLEMENTS is ours alone.** Sonde derives an IMPLEMENTS edge from`RegExpRouter.add`\n\nto`Router.add`\n\nonce the class declares it implements the interface. tsc reports heritage clauses at the type level only, so every member-level edge counts as a false positive against ground truth that does not model them. The capability is the reason impact on an interface method works at all, so the precision cost is disclosed rather than removed.\n\nCounts are absolute, not percentages of a large corpus. Fixture edge totals appear below so a single edge's effect on each figure is visible.\n\nFixture config SHA-256: `e02e2d5003f96d1ad22519f04e10d687fe689cf9298e7fcbc588eab525dce1ad`\n\nOracle edges: 9 · Sonde edges: 7 · one oracle edge moves recall by 11.1%\n\n| Edge kind | Tier | Precision | Recall | TP | FP | FN |\n|---|---|---|---|---|---|---|\n| CALLS | ALL | 0.500 | 1.000 | 2 | 2 | 0 |\n| CALLS | LEXICAL | 0.500 | 0.500 | 1 | 1 | 1 |\n| CALLS | HEURISTIC | 0.500 | 0.500 | 1 | 1 | 1 |\n| IMPLEMENTS | ALL | 0.500 | 1.000 | 1 | 1 | 0 |\n| IMPLEMENTS | LEXICAL | 0.500 | 1.000 | 1 | 1 | 0 |\n| IMPLEMENTS | HEURISTIC | 1.000 | 0.000 | 0 | 0 | 1 |\n| INHERITS | ALL | 1.000 | 1.000 | 1 | 0 | 0 |\n| INHERITS | LEXICAL | 1.000 | 1.000 | 1 | 0 | 0 |\n| INHERITS | HEURISTIC | 1.000 | 0.000 | 0 | 0 | 1 |\n| REFERENCES | ALL | 0.571 | 0.800 | 4 | 3 | 1 |\n| REFERENCES | LEXICAL | 0.800 | 0.800 | 4 | 1 | 1 |\n| REFERENCES | HEURISTIC | 0.000 | 0.000 | 0 | 2 | 5 |\n\n**Overall:** precision 0.571, recall 0.889\n\nRegenerate with `npm run bench:oracle`\n\n.\n\n```\nsonde init [path] [--resolve] [--yes]      # index and register project MCP config\nsonde index [path] [--resolve]             # full index; optional compiler pass\nsonde update [path] [--resolve]            # update; optional compiler pass\nsonde status [path]                        # freshness and tier distribution\nsonde search <query> [path]                # find_symbols\nsonde query <pattern> <symbol> [path]      # query_graph\nsonde impact [path] --symbol <name>        # get_impact_radius by symbol\nsonde impact [path] --from-git-diff        # impact from working-tree diff\nsonde doctor [path]                        # parser/database/tsc health\nsonde clean [path]                         # remove the cached index\nsonde mcp serve [path]                     # MCP server over stdio\n```\n\n`impact`\n\nalso accepts repeatable `--symbol`\n\noptions and\n`--token-budget <n>`\n\n. The `init`\n\n, `index`\n\n, `update`\n\n, `status`\n\n, `search`\n\n, `query`\n\n,\n`impact`\n\n, `doctor`\n\n, and `clean`\n\ncommands accept `--json`\n\n.\n\n**Node 22+ is required.**`better-sqlite3`\n\nneeds it; installing on an older Node prints an`EBADENGINE`\n\nwarning but still completes. If`sonde`\n\nthen fails to run, this is why — upgrade Node rather than ignore the warning.**Python needs** Without it, Python indexes at the tree-sitter tier only, which measured`--resolve`\n\n, and its edges are not oracle-verified.**62.81% unresolved** on a real 56-file project and 57.39% on pydantic — far past the 30% ceiling this project requires, so it is not fit for structural queries. With`--resolve`\n\n, a bundled pyright drives a`COMPILER`\n\ntier and the same corpora measure**27.00%** and**17.42%** unresolved. That gate measured*placement*— whether a reference found a target — not whether the target was correct; TypeScript's edges are scored against`tsc`\n\nin`ORACLE.md`\n\nand Python has no equivalent oracle. On the worse corpus the margin is thin: 0.28 points once a known upward bias is reversed. See.`probes/python-placement/FINDINGS.md`\n\n**TypeScript, Python and Swift only; no other language adapter.****Swift resolution is heuristic, not compiler-backed, and one narrowing rule is unvalidated.** References are narrowed by file visibility and explicit local type annotations, not full type inference. On a real 376-file Swift application this reached 74.84% placed / 25.16% unresolved — seefor the full measurement. The third narrowing rule (SwiftPM target boundaries) has never been tested: the validating corpus was an Xcode project, which has no`probes/swift-narrowing/FINDINGS.md`\n\n`Package.swift`\n\nlayout to supply that signal. The curated Swift SDK symbol table is also deliberately conservative — several ambiguous names were dropped rather than guessed, so some legitimate SDK references may still show as`UNRESOLVED`\n\nrather than`EXTERNAL`\n\n.- Compiler resolution for TypeScript (\n`--resolve`\n\n) is opt-in because it is materially slower and uses more transient memory. On the 19,409-line Hono fixture, default indexing took 3.58 s;`--resolve`\n\ntook 13.70 s, added 10,329 exact placements/promotions, and changed`callers_of Hono.route`\n\nfrom zero graph results to eight compiler callers. The Program is discarded after indexing; inline refresh stays compiler-free and explicitly downgrades affected evidence until a full`sonde update --resolve`\n\n. - Compiler resolution uses bundled TypeScript 5.9.3, not the repository's own\ncompiler, so version skew is possible and disclosed in\n`doctor`\n\nand response envelopes. - A file with a parse error still contributes whatever tree-sitter\nrecovered from it — this is deliberate (see the design spec §8). Its\n`parse_state`\n\nis`partial`\n\nwhen real declarations were recovered despite the error, or`failed`\n\nonly when nothing usable came out of it at all. `TESTS`\n\nedges indicate structural relatedness only; they never prove coverage.- Type-only references, JSX intrinsics,\n`export =`\n\n/`import =`\n\n, decorators, and declaration merging are known gaps in the tree-sitter extraction path. **No rename inference.** Renaming a file changes every stable key derived from its path; anything holding an old key (a saved query, an agent's prior turn) will silently stop resolving rather than following the rename.- Semantic/behavioural search is not available. It was built and measured —\ntwo embedding models, four document configurations — and none of them beat\nlexical/structural retrieval on the task class it was meant to help with.\nSee design spec §2.2 for the numbers. It is not wired into\n`find_symbols`\n\n.\n\nSee\n[ docs/superpowers/specs/2026-08-16-sonde-design.md](/anishmoncivarghese/sonde/blob/main/docs/superpowers/specs/2026-08-16-sonde-design.md)\nfor the full design.", "url": "https://wpnews.pro/news/show-hn-sonde-a-local-code-graph-for-ai-agents-that-refuses-to-guess", "canonical_source": "https://github.com/anishmoncivarghese/sonde", "published_at": "2026-08-31 08:21:15+00:00", "updated_at": "2026-08-31 08:52:36.876087+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Sonde", "Cheppu Labs", "MCP", "SQLite"], "alternates": {"html": "https://wpnews.pro/news/show-hn-sonde-a-local-code-graph-for-ai-agents-that-refuses-to-guess", "markdown": "https://wpnews.pro/news/show-hn-sonde-a-local-code-graph-for-ai-agents-that-refuses-to-guess.md", "text": "https://wpnews.pro/news/show-hn-sonde-a-local-code-graph-for-ai-agents-that-refuses-to-guess.txt", "jsonld": "https://wpnews.pro/news/show-hn-sonde-a-local-code-graph-for-ai-agents-that-refuses-to-guess.jsonld"}}