Synaptic
Auditable code intelligence for AI agents. Synaptic compiles a repository into a persistent knowledge graph — symbols, files, calls, imports, inheritance, SQL usage, and resources — across 30+ languages via tree-sitter. From that graph it answers what depends on what, forecasts the blast radius of a change before the change is written, selects the tests that actually matter, and verifies refactors in throwaway worktrees. Ships as a single static Rust binary with no runtime dependencies.
Why Build This
An agent that reads source files to understand a codebase is reading the wrong artifact, at the wrong cost, with no way to prove it was right.
Answering "what breaks if I change this?" by reading files means loading the files. On Synaptic's own codebase, a full subgraph response costs roughly 1,950 tokens against 60,900 for the equivalent raw source — 27–38x cheaper, and the graph answer is structured rather than something the model has to re-derive on every call.
Grep-based impact analysis reports "0 dependents" for anything reached through an event bus, reflection, or dynamic dispatch. That is not a missing answer, it is a wrong one, and it is the kind that gets shipped. Synaptic catalogues dynamic-dispatch hazards explicitly and surfaces them as caveats rather than silently omitting the edges.
Most code-understanding tooling cannot tell you how often it is right. Synaptic ships a hand-labeled ground-truth corpus and an eval subcommand, so precision and recall are measured numbers on a fixed corpus rather than a claim in a README.
Repository memory records prior changes, regressions, decisions, and verification results as source-linked evidence. When a change resembles one that went badly before, the history is retrievable instead of lost in a closed pull request from eight months ago.
System Design
A 27-crate Rust workspace across three interlocking systems, distributed as one static binary.
Knowledge Graph
tree-sitter parsers extract symbols, files, calls, imports, inheritance, SQL usage, and resource references into a node-link graph.json. Cross-repo federation resolves edges across monorepo boundaries with alias support. Assets and data files are indexed as first-class nodes with reference binding.
Repository Memory
Records changes, regressions, decisions, procedures, and verification outcomes as source-linked evidence. Queryable by CLI or MCP for similar past changes, known pitfalls, and the reasoning behind a prior decision. Write access is deliberately narrow — a single record_change_outcome tool.
API Maintenance
Inventories SDK versions, detects breaking changes, localizes every affected call site, and prepares bounded repairs inside isolated git worktrees before publishing a draft PR. The repair never touches the working tree until it has been run and verified somewhere disposable.
MCP Server
synaptic serve exposes 40+ tools over Model Context Protocol across graph navigation, impact analysis, structural search, auditing, vulnerability scanning, and memory. Agents query the graph directly instead of paging source into context.
Under the Hood
What the graph makes possible once the structure is resident and queryable.
A query language over the graph. Property filters (WHERE kind="function" AND loc > 500), one-hop and variable-length relationship patterns, aggregation, and named patterns for singleton, factory, observer, service-locator, and god-class shapes. --explain shows why each result matched.
predict forecasts the blast radius of a change before any code is written. speculate goes further and runs the change in a throwaway worktree with its tests, so the forecast can be checked against reality rather than trusted.
Graph deltas between any two git revisions, with caching. Shows how architecture actually moved between releases — which edges appeared, which symbols became load-bearing, where coupling accumulated — instead of a line-level diff that cannot express any of that.
Rename, move, and extract operations planned as confidence-scored execution plans over known call sites. A rename touching ~120 call sites across 40 files plans in roughly 4.9 ms, and the plan enumerates what it will touch before it touches anything.
sql audit flags row-level-security gaps, N+1 access patterns, and missing indexes from SQL usage captured in the graph. audit readiness ranks framework sentinels and stubs as migration blockers for port work.
Scans 12 package ecosystems and grounds each finding in the graph — not just "this dependency is vulnerable" but whether the affected surface is actually reached from your code, with the path as evidence.
synaptic watch and synaptic hook install refresh the graph on file changes and git operations. Warm extraction runs 1.4–2.8x faster than cold, so the graph stays current without a rebuild step anyone has to remember.
Every run writes synaptic-out/: machine-readable graph.json, a GRAPH_REPORT.md of god nodes and cycles, interactive 2D and 3D explorers, a static SVG layout, and GraphML / Cypher / DOT / Obsidian exports. The graph is auditable by a human, not just consumable by an agent.
Measured, Not Asserted
Accuracy from synaptic eval corpus against hand-labeled ground truth: 11 fixtures, 6 language families, 42 symbols. Speed from Criterion benchmarks and a 10-repository scale audit.
Call-Edge Accuracy
100% precision, 94% recall, F1 97%. Cross-language edges score 100/100/100 across five boundary kinds. Precision is the number that matters here — a false edge sends an agent to rewrite code that was never affected.
Blast Radius
100% recall, zero false positives. Affected-test selection also validates at 100% including multi-hop cases. Missing a dependent is the failure mode that ships bugs, so recall is the constraint the design optimizes for.
Query Latency
~0.47 ms for a SYNQL property query on a 2,000-node graph; ~0.97 ms for a relationship-pattern join; ~4.9 ms to plan a safe rename across ~120 call sites in 40 files.
Extraction Throughput
44–339k LOC/s median cold extraction across 10 open-source repositories. The largest tested — Humanizer at 476,967 LOC — extracts cold in 7.07s and warm in 2.69s.
The Command Surface
Install from source or grab a prebuilt binary from GitHub Releases; synaptic self-update handles upgrades.
synaptic extract . builds the initial graph into synaptic-out/. synaptic query "question" returns a relevance-ranked subgraph. synaptic affected symbol_name lists transitive dependents with dynamic-dispatch caveats. synaptic serve starts the MCP server.
search for SYNQL and named patterns, diff for time-travel comparison between revisions, predict for blast-radius forecasting, speculate for verified throwaway execution, refactor for safe rename/move/extract plans.
audit readiness for port and migration blockers, sql audit and sql advise for SQL performance and security, and the vuln family for dependency scanning with source-grounded evidence.
Project config lives in .synaptic/. Indexing honors .synapticignore and .gitignore. The graph is queryable without re-parsing source, so repeat questions cost a lookup rather than a re-extraction.