{
  "markdown": "# Sonde\n\n[![ci](https://github.com/anishmoncivarghese/sonde/actions/workflows/ci.yml/badge.svg)](https://github.com/anishmoncivarghese/sonde/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/%40cheppulabs%2Fsonde.svg)](https://www.npmjs.com/package/@cheppulabs/sonde)\n[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\nA 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`, `query_graph`, and `get_impact_radius` — 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\n## What the benchmark actually shows\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** | 1.00 |\n| Tool calls | **1.0** | 8.0 |\n| Context tokens | **1,262** | 3,621 |\n| Latency | **263 ms** | 38,602 ms |\n| Runs that blew the token budget | **0 of 6** | 3 of 6 |\n\nSonde matches the baseline's answers on every structural task while using\n~3× less context, 8× fewer calls, and ~147× less wall-clock time — and it never\nexceeds the caller's token budget, because the packer truncates to it by\nconstruction. 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`.\nFull results in [BENCHMARK-LARGE.md](BENCHMARK-LARGE.md) and\n[BENCHMARK.md](BENCHMARK.md).\n\n## Install and run\n\n```sh\nnpm install -g @cheppulabs/sonde\ncd your-project\nsonde init\n```\n\n`sonde init` indexes the repository and registers sonde as an MCP server in\nthis project's `.mcp.json`, asking before it writes anything (skip the prompt\nwith `sonde init --yes`). It never touches an `.mcp.json` it can't safely merge\ninto — an existing `sonde` entry that differs from what `init` would write is\nleft alone and reported, not overwritten.\n\nFor Python repositories, use `sonde init --resolve`; 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```sh\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## Architecture documentation\n\n`sonde doc` writes an [`ARCHITECTURE.md`](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```sh\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` again\nrather than merging by hand. It refuses to overwrite an `ARCHITECTURE.md` it 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\n  share symbol names are excluded and counted separately. On this repository two\n  adapters share the filenames `symbols.ts`, `parser.ts` and `references.ts`,\n  which manufactured 62 heuristic \"references\" between modules that never import\n  each other — once the second-heaviest arrow in the diagram.\n- **It does not pretend the diagram is complete.** The diagram shows the\n  heaviest dependencies and states how many it omitted; the table below it goes\n  further, and `--module` has the rest. A diagram containing every dependency is\n  unreadable and therefore shows nothing.\n- **It does not claim to be current when it is not.** The header names the\n  commit it describes and warns when files have changed since.\n\n## What it guarantees\n\n- **Never returns stale source bytes.** Whenever a response includes source,\n  Sonde re-reads and re-hashes the indexed byte range before returning it\n  (spec §8.1, Guarantee A).\n- **Always reports structural drift**, rather than claiming completeness it\n  cannot verify (spec §8.1, Guarantee B). `sonde status` shows the same\n  drift and tier distribution carried by tool response envelopes.\n- **Every edge is tier-labelled by how it was found** — `COMPILER` (resolved\n  exactly by a bundled type checker under `--resolve`: the TypeScript compiler\n  for TypeScript, pyright for Python), `LEXICAL`\n  (resolved through an import binding or lexical scope), `HEURISTIC` (member\n  access or another relationship requiring type inference), `EXTERNAL` (target\n  outside the indexed repository), or `UNRESOLVED` (genuinely unplaceable,\n  with a reason).\n- **Never fabricates an edge.** An unresolved reference becomes `EXTERNAL` or\n  `UNRESOLVED` — never a guessed target and never a silently dropped reference.\n\n## Accuracy\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` edges use that compiler directly, so comparing\nthem back to the same authority would not be an independent accuracy test.\n\n<!-- ORACLE_REPORT_START -->\n# Sonde edge accuracy vs the TypeScript compiler\n\nGenerated: 2026-08-23T18:16:41.557Z\nTypeScript: 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` to produce them.\n\nThe oracle is filtered to in-repo targets; `node_modules` and `.d.ts`\ndeclarations are excluded. Type-only references, JSX intrinsics, `export =`,\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` is the combined result.\n\n## Why precision below 1.000 is expected here\n\nThese divergences are structural, so reading a precision figure as\n\"how often Sonde is wrong\" overstates the error rate:\n\n1. **Ambiguous member calls emit every candidate.** For `x.foo()` with two\n   visible `foo` declarations, Sonde emits both as confidence-weighted\n   `HEURISTIC` edges. At most one matches the compiler, so the other counts\n   as a false positive by construction. The alternative is guessing a single\n   target, which invariant 1 forbids — a wrong resolved-looking edge is worse\n   than two honestly heuristic ones. Precision is therefore capped below\n   1.000 wherever the fixture contains an ambiguous call.\n2. **Constructor calls are ours alone.** Sonde emits `CALLS` for\n   `new Foo()`; the oracle does not model them, so each one is a false\n   positive against ground truth that omits it.\n3. **Member-level IMPLEMENTS is ours alone.** Sonde derives an\n   IMPLEMENTS edge from `RegExpRouter.add` to `Router.add` once the class\n   declares it implements the interface. tsc reports heritage clauses at the\n   type level only, so every member-level edge counts as a false positive\n   against ground truth that does not model them. The capability is the\n   reason impact on an interface method works at all, so the precision cost\n   is disclosed rather than removed.\n\nCounts are absolute, not percentages of a large corpus. Fixture edge totals\nappear below so a single edge's effect on each figure is visible.\n\n## tests/fixtures/repos/small\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<!-- ORACLE_REPORT_END -->\n\nRegenerate with `npm run bench:oracle`.\n\n## CLI\n\n```text\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` also accepts repeatable `--symbol` options and\n`--token-budget <n>`. The `init`, `index`, `update`, `status`, `search`, `query`,\n`impact`, `doctor`, and `clean` commands accept `--json`.\n\n## Known limitations\n\n- **Node 22+ is required.** `better-sqlite3` needs it; installing on an older\n  Node prints an `EBADENGINE` warning but still completes. If `sonde` then\n  fails to run, this is why — upgrade Node rather than ignore the warning.\n- **Python needs `--resolve`, and its edges are not oracle-verified.** Without\n  it, Python indexes at the tree-sitter tier only, which measured **62.81%\n  unresolved** on a real 56-file project and 57.39% on pydantic — far past the\n  30% ceiling this project requires, so it is not fit for structural queries.\n  With `--resolve`, a bundled pyright drives a `COMPILER` tier and the same\n  corpora measure **27.00%** and **17.42%** unresolved. That gate measured\n  *placement* — whether a reference found a target — not whether the target was\n  correct; TypeScript's edges are scored against `tsc` in `ORACLE.md` and\n  Python has no equivalent oracle. On the worse corpus the margin is thin: 0.28\n  points once a known upward bias is reversed. See\n  [`probes/python-placement/FINDINGS.md`](probes/python-placement/FINDINGS.md).\n- **TypeScript, Python and Swift only; no other language adapter.**\n- **Swift resolution is heuristic, not compiler-backed, and one narrowing\n  rule is unvalidated.** References are narrowed by file visibility and\n  explicit local type annotations, not full type inference. On a real\n  376-file Swift application this reached 74.84% placed / 25.16% unresolved\n  — see [`probes/swift-narrowing/FINDINGS.md`](probes/swift-narrowing/FINDINGS.md)\n  for the full measurement. The third narrowing rule (SwiftPM target\n  boundaries) has never been tested: the validating corpus was an Xcode\n  project, which has no `Package.swift` layout to supply that signal. The\n  curated Swift SDK symbol table is also deliberately conservative — several\n  ambiguous names were dropped rather than guessed, so some legitimate SDK\n  references may still show as `UNRESOLVED` rather than `EXTERNAL`.\n- Compiler resolution for TypeScript (`--resolve`) is opt-in because it is\n  materially slower and uses more transient memory. On the 19,409-line Hono\n  fixture, default indexing took 3.58 s; `--resolve` took 13.70 s, added\n  10,329 exact placements/promotions, and changed `callers_of Hono.route`\n  from zero graph results to eight compiler callers. The Program is discarded\n  after indexing; inline refresh stays compiler-free and explicitly\n  downgrades affected evidence until a full `sonde update --resolve`.\n- Compiler resolution uses bundled TypeScript 5.9.3, not the repository's own\n  compiler, so version skew is possible and disclosed in `doctor` and response\n  envelopes.\n- A file with a parse error still contributes whatever tree-sitter\n  recovered from it — this is deliberate (see the design spec §8). Its\n  `parse_state` is `partial` when real declarations were recovered despite\n  the error, or `failed` only when nothing usable came out of it at all.\n- `TESTS` edges indicate structural relatedness only; they never prove coverage.\n- Type-only references, JSX intrinsics, `export =`/`import =`, decorators, and\n  declaration merging are known gaps in the tree-sitter extraction path.\n- **No rename inference.** Renaming a file changes every stable key derived\n  from its path; anything holding an old key (a saved query, an agent's prior\n  turn) will silently stop resolving rather than following the rename.\n- Semantic/behavioural search is not available. It was built and measured —\n  two embedding models, four document configurations — and none of them beat\n  lexical/structural retrieval on the task class it was meant to help with.\n  See design spec §2.2 for the numbers. It is not wired into `find_symbols`.\n\nSee\n[`docs/superpowers/specs/2026-08-16-sonde-design.md`](docs/superpowers/specs/2026-08-16-sonde-design.md)\nfor the full design.\n",
  "bytes": 14273,
  "sha": "e3ecfb2219e02ae539e57d9f739b8acffcddd7268bdb7a2f00100aa5a8c1711a",
  "repo_slug": "anishmoncivarghese/sonde",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_anishmoncivarghese_sonde_6d57d8de/readme"
}