# Sonde

> A local code-context engine for AI coding agents that indexes TypeScript, Python, or Swift repositories into a symbol-level graph in SQLite and exposes MCP tools for structural code queries.

Sonde is an open-source, local code-context engine built for AI coding agents, published under the Apache 2.0 license by Anish Varghese. It indexes TypeScript, Python, or Swift repositories into a symbol-level graph stored in SQLite, then exposes that graph through three MCP (Model Context Protocol) tools so an agent can answer structural questions in a single call rather than a multi-step search loop. No account or hosted service is required — everything runs locally.

## What It Is

Sonde sits between an AI coding agent and a codebase, providing fast, budget-aware structural answers to questions like *who calls this function*, *what breaks if I change it*, and *which tests relate to it*. It is installed as a CLI tool via npm, indexes the repository on demand, and registers itself as an MCP server in the project's `.mcp.json`. The three MCP tools it exposes are `find_symbols`, `query_graph`, and `get_impact_radius`.

## How the Cost-vs-Recall Trade Works

The README is explicit about what Sonde does and does not claim. On a real 19,409-line TypeScript repository, the project's own benchmark shows Sonde matching an agentic search loop's recall (1.00) on structural tasks while using approximately 3× less context (1,262 vs 3,621 tokens), 8× fewer tool calls (1.0 vs 8.0), and roughly 147× less wall-clock time (263 ms vs 38,602 ms). The benchmark also reports that 3 of 6 agentic search runs exceeded the token budget, while Sonde exceeded it 0 times.

The README explicitly notes where Sonde loses: behavioural queries with no shared vocabulary — such as *"where is the retry backoff decided?"* — score 0.00. Semantic/embedding-based retrieval was built and measured but did not beat lexical/structural retrieval on that task class, so it is not wired into `find_symbols`.

## Architecture and Accuracy Model

Sonde uses a tiered resolution model, labelling every edge by how it was found:
- **COMPILER** — resolved exactly by a bundled type checker (TypeScript 5.9.3 or pyright), opt-in via `--resolve`
- **LEXICAL** — resolved through an import binding or lexical scope
- **HEURISTIC** — member access or relationships requiring type inference
- **EXTERNAL** — target outside the indexed repository
- **UNRESOLVED** — genuinely unplaceable, with a reason

The project publishes its oracle accuracy report in the README. On the small fixture, overall precision is 0.571 and recall is 0.889 for the tree-sitter (zero-setup) path. Known precision gaps — ambiguous member calls emitting every candidate, constructor calls, and member-level IMPLEMENTS edges — are disclosed rather than hidden.

The `sonde doc` command generates an `ARCHITECTURE.md` from the graph, describing modules, dependencies, and exports. It is designed to be committed and regenerated; regeneration is byte-identical when nothing changed, and it refuses to overwrite a file it did not generate.

## Language Support and Known Limitations

- **TypeScript**: Full support; `--resolve` enables the bundled TypeScript 5.9.3 compiler for exact placements.
- **Python**: Requires `--resolve` (bundled pyright); without it, the tree-sitter tier measured 62.81% unresolved on a real project, well past the project's 30% ceiling.
- **Swift**: Heuristic resolution only; no compiler-backed tier. On a 376-file Swift application, 74.84% of references were placed and 25.16% were unresolved.
- Node 22+ is required (`better-sqlite3` dependency).
- No rename inference: renaming a file invalidates all stable keys derived from its path.
- No semantic/behavioural search.

## Update: v0.4.4

The latest release, v0.4.4 (published 2026-08-31), is titled "explain empty graphs, point at sonde doc," indicating the project is in active development with recent usability improvements. The repository was created in August 2026 and has seen continuous pushes through the end of that month.

## Features
- Symbol-level graph indexing in SQLite
- Three MCP tools: find_symbols, query_graph, get_impact_radius
- TypeScript, Python, and Swift support
- Compiler-backed resolution via --resolve flag (TypeScript 5.9.3, pyright)
- Token-budget-aware context packing
- Impact radius analysis from symbol or git diff
- Architecture documentation generation (sonde doc)
- Structural drift reporting and freshness tracking
- Tiered edge labelling: COMPILER, LEXICAL, HEURISTIC, EXTERNAL, UNRESOLVED
- Stale-source prevention via re-read and re-hash before returning source bytes
- CI integration via sonde doc --check
- No account or hosted service required

## Integrations
MCP (Model Context Protocol), TypeScript compiler (tsc), pyright, tree-sitter, SQLite, npm

## Platforms
CLI, API

## Pricing
Open Source

## Version
v0.4.4

## Links
- Website: https://github.com/anishmoncivarghese/sonde
- Repository: https://github.com/anishmoncivarghese/sonde
- EveryDev.ai: https://www.everydev.ai/tools/sonde