Sheet 02 · Capability schedule

Everything Synaptic does.

One static Rust binary builds the graph, then answers structural and architectural questions over it. Offline by default, with every command also exposed to an AI assistant over MCP.

Part 01

Extraction & the graph

Turn a folder into a knowledge graph: symbols and relationships, clustered into communities.

$ synaptic extract .

Parses 30+ languages with tree-sitter, resolves call, import, and reference edges, and clusters the result into communities so the structurally important pieces surface on their own. A code-only corpus never makes a network call.

Incremental rebuilds, file watching, and git hooks keep the graph current as you work; an on-disk AST cache makes re-runs fast.

FIG. EXTRACTION source tree-sitter parse graph + communities
--directed--obsidian--wiki--semanticupdatewatch
Part 02

Query & structural search

Ask in plain text, or match on structure with SYNQL, a small Cypher-inspired query language.

$ synaptic search --pattern god-class

A text query returns a relevance-ranked subgraph (each node scored, best-first). path finds the shortest route between two symbols; explain shows a node and its neighbours.

SYNQL matches on kind, visibility, LOC, fan-in/out and variable-length paths with count(...) aggregation, --explain, saved queries, and a library of named patterns: singleton, factory, observer, service-locator, god-class. Not text search.

FIG. QUERY ranked slice 1,950 tokens only the slice a query returns a ranked subgraph, not the whole graph
querypathexplainsearch--explain--save
Part 03 · datum

Impact, foresight & speculation

Know what a change touches, then actually run it before you commit to it.

$ synaptic predict --edit "signature:parse_config"

affected reports everything that transitively depends on a symbol. predict forecasts a change's blast radius, public APIs at risk, at-risk tests, new cycles, and a risk score, before you write the edit.

speculate then applies the change in a throwaway git worktree and actually runs the at-risk tests plus a build and type-check, reporting real pass/fail: the ground-truth half of prediction.

FIG. SPECULATE HEAD (main) throwaway worktree apply edit: parse_config at-risk tests: 4 pass 1 fail real pass/fail then discarded
affectedpredictspeculate--edit--gate
Part 04

Dynamic-dispatch awareness

A "0 dependents" answer is never quietly mistaken for "safe to change."

$ synaptic hazards

Event buses (Node EventEmitter, DOM CustomEvent, C# events) and Electron IPC link a publisher to its subscriber through a channel node, so a handler reached only across the bus is not a phantom 0-caller.

Reflection and dispatch that can't be resolved statically (by-name lookups, dispatch tables, eval, dynamic import, .NET/Python/JVM reflection) are cataloged, and affected attaches a caveat when a symbol is reachable only dynamically.

FIG. EVENT BUS emit('evt') channel: evt on('evt') without the channel node, the handler looks like 0 callers
hazards--kinddynamic_hazards (MCP)
Part 05

Safe refactor

Plan a rename, move, or extract. Synaptic never edits your source itself.

$ synaptic refactor rename && synaptic refactor verify

Each refactor emits a confidence-scored execution plan (plan.json + plan.md) with the exact edit sites, for an AI agent to apply.

Afterwards, refactor verify rebuilds and checks the graph held: the definition moved or renamed, no references were lost, and no new cycles were introduced.

FIG. REFACTOR rename plan.json edit sites + confidence agent edits (not Synaptic) verify graph held
renamemoveextractverify
Part 06

Time-travel diff

See how the architecture moved between two points in git history.

$ synaptic diff HEAD~50 HEAD --html

Reports added and removed dependencies, removed public APIs, architectural drift, new cycles, and hotspots between two revisions (or --since <date>), as a Markdown or self-contained HTML report.

Built graphs are cached per commit SHA, so a repeat diff returns immediately and only the working-tree side is rebuilt.

FIG. DIFF HEAD~50 to HEAD + added dependency removed dependency
--since--html--scope
Part 07

SQL performance & security audit

Audit the database layer over a SQL-aware graph that knows your tables, indexes, and policies.

$ synaptic sql audit --severity high

Flags row-level-security gaps, over-broad grants, likely SQL injection, missing indexes on filter and foreign-key columns, SELECT *, non-sargable predicates, N+1 patterns, and missing primary keys.

sql advise --query "<sql>" critiques a candidate query before you write it, cross-referenced against the graph's tables, indexes, and RLS policies.

FIG. SQL AUDIT SELECT * query users ! no index sessions ! RLS gap queries linked to the tables they touch
auditadvise--db-url (live EXPLAIN)
Part 08

Federation & workspaces

From one small folder to a fleet of repos federated into a single graph.

$ synaptic workspace federate

A workspace federates many repositories into one graph with real cross-repo edge resolution (export surfaces plus import, tsconfig paths, and module-federation aliases) so architecture stays visible across repo boundaries.

The cross-repo global store and merge-graphs compose several graphs into one namespaced view.

FIG. FEDERATION repo-a repo-b repo-c cross-repo edges into one graph
initadddiscoverfederatesync
Part 09

MCP server

28 read-only tools, so your assistant queries the graph before it reads files.

$ synaptic serve --http 127.0.0.1:8765

Over stdio or HTTP (protocol 2025-11-25): graph navigation, reverse impact, dynamic-dispatch hazards, PR and working-tree blast radius, change forecasting, predictive test selection, structural search, time-travel diff, plan-only rename, and SQL audit/advise.

Plus MCP prompts, argument completions, resource templates and subscriptions, and a small REST surface. synaptic install wires it into Claude or Codex.

FIG. MCP AI assistant synaptic serve · 28 tools queries structure grep / read files
stdio--httpinstall--allow-exec
Part 10

Outputs & visualizations

Machine-readable graphs alongside human-readable reports and visuals.

$ synaptic export graphml

One run writes graph.json, a Markdown GRAPH_REPORT.md (god nodes, surprising connections, import cycles), an interactive 2D explorer, a 3D force graph, and a static SVG layout.

Re-emit GraphML, Cypher, DOT, an Obsidian vault, or a Markdown wiki from an existing graph, or push live to Neo4j / FalkorDB.

FIG. OUTPUTS one graph graph.json GraphML Cypher DOT Obsidian 2D / 3D viewers
graph.jsongraph-3d.htmlgraphmlcypherobsidian
Synaptic · sheet 02 of 04 · rev 0.3.12 See also

Curious how it earns the answer?