Synaptic documentation

Synaptic Code Intelligence Overview

Source: GitHub Wiki · Published Jun 15, 2026 · Updated Jul 17, 2026Edit this article

Synaptic turns any folder of code into a persistent, queryable knowledge graph, then lets you (or an AI assistant) query that compact graph instead of re-reading the whole codebase. It extracts symbols and relationships across 30+ languages with tree-sitter, clusters them into communities, surfaces the structurally important pieces, and writes machine-readable graphs, human-readable reports, and interactive visualizations.

It is a single static Rust binary (synaptic) with no runtime, plus an MCP server so a coding assistant can consult the graph before grepping or reading files.

60-second tour

synaptic extract .                      # build synaptic-out/ for the current directory
synaptic query "authentication flow"    # get a relevant subgraph back
synaptic explain parse_config           # show a node and its neighbours
synaptic affected parse_config          # what would changing it break?
synaptic search "MATCH (c:class) WHERE c.loc > 500 RETURN c"   # structural query (SYNQL)
synaptic diff HEAD~10 HEAD              # how the graph changed between two revisions
synaptic refactor rename old_name --to new_name   # a safe, confidence-scored rename plan
synaptic serve                          # expose the graph to an assistant over MCP

See Quickstart for a fuller walk-through and Installation to get the binary.

What Synaptic gives you

A canonical graph.json you can query without reading source.
A Markdown report of god nodes, surprising connections, import cycles, and suggested questions (Analysis and Reports).
2D, 3D, and SVG visualizations plus GraphML / Cypher / DOT / Obsidian / wiki exports (Output Formats, Visualizations).
Graph queries: relevant-subgraph search, shortest path, and reverse impact (Querying).
Dynamic-dispatch awareness: event buses and Electron IPC link publishers to subscribers through channel nodes, and reflection / dynamic-dispatch sites are cataloged so a "0 dependents" answer is never mistaken for "safe to change" (synaptic hazards, the dynamic_hazards MCP tool, and an affected caveat) (Querying, Cross-Language Edges).
Structural search with SYNQL, a Cypher-inspired query language matching on kind/visibility/loc/fan-in-out plus named architectural patterns (Commands).
Time-travel diff between two git revisions: added/removed dependencies, removed APIs, architectural drift, new cycles, and change hotspots (Commands).
Safe refactor: confidence-scored rename/move/extract plans for an agent to apply, with a graph-invariant verify afterwards (Commands).
Change forecasting: synaptic predict reports a change's blast radius, public APIs at risk, the tests that exercise it, new cycles, and a verify checklist before you edit; --edit "<kind>:<symbol>" forecasts a described edit before any code is written (Commands).
Speculative execution: synaptic speculate applies a pending change in a throwaway git worktree and actually runs the at-risk tests plus a build/type- check, reporting real pass/fail (the ground-truth half of prediction; CLI-only by default, exposed over MCP only with serve --allow-exec) (Commands).
Forecast evaluation: synaptic eval replay replays history, re-predicts each commit from its parent state, and scores the prediction against git ground truth (co-edited tests, removed APIs) so forecast quality is regression-testable and CI-gateable (Commands).
An MCP server (30 read-only tools) and one-command assistant integration (MCP Server, Assistant Integration).
Multi-repo federation with real cross-repo edge resolution (Workspaces and Federation).

Documentation map

Getting started: Installation - Quickstart - Updating

Concepts: Architecture - Languages - Synaptic vs Other Tools

Using Synaptic: Commands - Extraction - Querying

SQL Auditing - Analysis and Reports - Output Formats - Visualizations

Integrations: MCP Server - Assistant Integration

Building on Synaptic - Ingestion - Semantic Analysis

Scaling: Workspaces and Federation - Incremental Updates - PR Dashboard

Reference: Configuration - Development

Design principles

Offline by default. A code-only corpus makes no network calls. The only network features are opt-in and explicit: the --semantic pass over documents calls an LLM (Semantic Analysis), and self-update (with its optional daily notice) contacts GitHub (Updating).
Auditable. Every edge carries a confidence level (EXTRACTED, INFERRED, AMBIGUOUS).
Deterministic. The same input produces the same graph; ids and community numbers are stable across rebuilds.

Community

Questions, ideas, or want to show what you built? Join us on Discord.

Star History