{ "markdown": "# Synaptic\n\n

\n \"Join\n \"License:\n \"Latest\n

\n\n

\n \"Synaptic\n

\n\nSynaptic is a source-grounded code maintenance platform built around three connected systems:\n**API maintenance**, **repository memory**, and a persistent **knowledge graph**. Together they\nlet an engineer or AI assistant understand what the code does, remember what has happened to\nit, and make bounded repairs without guessing.\n\n1. **API maintenance** keeps external dependencies and SDKs safe to change. Dependency bots\n can tell you a new version exists; Synaptic inventories the APIs your code actually uses,\n detects source-grounded breaking changes, finds the affected call sites, plans a bounded\n repair in an isolated worktree, verifies graph invariants and selected tests, and only\n publishes a draft PR when the evidence is complete.\n2. **Repository memory** preserves the history that usually lives in people, chats, failed\n branches, incident notes, and old PRs. It records previous changes, regressions, decisions,\n procedures, verification results, and external artifacts as source-linked evidence, then\n retrieves that memory through the CLI or MCP server so future work starts with context\n instead of archaeology.\n3. **The knowledge graph** is the structural map underneath everything. Synaptic turns any\n folder, monorepo, or federated set of repositories into a persistent, queryable graph of\n symbols, files, resources, calls, imports, inheritance, SQL usage, dynamic-dispatch hazards,\n and cross-repo edges across 30+ languages with\n [tree-sitter](https://tree-sitter.github.io/).\n\nThe graph answers architectural questions, traces reverse impact (\"what would this change\nbreak?\"), forecasts and speculatively runs changes before you make them, plans safe refactors,\ndiffs architecture across git history, and audits SQL for performance and security. Memory adds\nwhat the graph cannot infer from the current tree alone. API maintenance uses both to turn\nupstream change into evidence-backed repair plans. The engine and terminal workflow ship as a\nsingle static Rust binary (`synaptic`) with no runtime or interpreter. An optional native\n`synaptic-ui` addon provides visual single-repository, workspace federation, and MCP setup plus a\nsearchable Tools view for every Synaptic task on Windows, Linux, and macOS. Synaptic writes\nmachine-readable graphs alongside human-readable reports and 2D/3D/SVG\nvisualizations, and exposes an MCP server so an AI coding assistant can use these systems before\ngrepping or reading files.\n\n## Architecture explorer\n\nTurn an existing `graph.json` into a self-contained, offline architecture map:\n\n```sh\nsynaptic chart\n```\n\nThe overview ranks source-grounded communities and their strongest exact relationships. Search,\nswitch themes, or open any subsystem without rebuilding the graph.\n\n

\n \"Synaptic\n

\n\nInside a subsystem, select a symbol to isolate its real one-hop dependencies. The inspector shows\nincoming and outgoing relations, and each row continues directly to the connected symbol.\n\n

\n \"Synaptic\n

\n\nThe desktop app's **App** screen checks the GitHub Release published by the release workflow,\ndownloads the matching archive, verifies its published checksum, and updates the bundled\nexecutables. **Add to applications** installs it for the current user and makes it searchable from\nWindows Start, macOS Applications, or the Linux application menu without administrator access.\nRemoving the desktop installation does not touch project data, graphs, settings, or a separately\ninstalled CLI.\n\nThe desktop app follows the operating system's light or dark preference on first launch and saves\nthe user's choice after that.\n\nIf someone downloads only `synaptic-ui`, its first-run screen automatically downloads the\nverified command tools from the latest GitHub Release and places them beside the app. No terminal,\nPATH change, or system-wide install is required.\n\nIf you do not want to run the MCP server yourself, **Synaptic Cloud** is a paid hosted MCP\nservice for using Synaptic with your projects: [synapticgraph.com](https://synapticgraph.com/).\nFor commit-triggered graph sync and verified API or dependency draft repairs, follow the\n[GitHub automation guide](https://synapticgraph.com/docs/github-automation).\n\n## Use Synaptic with a project\n\nStart from any repository root. Synaptic writes its index and reports to `synaptic-out/`\nand keeps project-specific configuration under `.synaptic/`.\n\nThe easiest path is to ask your AI coding agent to install and configure Synaptic for\nthe current repository, then have it follow the\n[Installation](https://github.com/ColinVaughn/Synaptic/wiki/Installation),\n[Quickstart](https://github.com/ColinVaughn/Synaptic/wiki/Quickstart), and\n[Assistant Integration](https://github.com/ColinVaughn/Synaptic/wiki/Assistant-Integration)\nguides. If you prefer to do it yourself, the manual path is:\n\n```sh\n# 1. Install the binary from this repository\ncargo install --path bin/synaptic\n\n# Or download a prebuilt binary from GitHub Releases, then confirm it works\nsynaptic --version\n\n# Optional: install and launch the native setup UI\ncargo install --path bin/synaptic-ui\nsynaptic-ui\n\n# 2. Build the first graph for your project\ncd path/to/your/project\nsynaptic extract .\n\n# 3. Ask structural questions without rereading the whole codebase\nsynaptic query \"authentication flow\"\nsynaptic affected parse_config\nsynaptic search --pattern god-class\n\n# 4. Keep the graph current as the project changes\nsynaptic update\nsynaptic watch\nsynaptic hook install\n```\n\nFor a normal project setup, add a `.synapticignore` if there are generated, vendored,\nor sensitive paths you do not want indexed; `extract` also honors `.gitignore` and skips\ncommon secrets like `.env` and key files. Use `synaptic hook install` when you want Git\ncommits, checkouts, and graph merges to keep `synaptic-out/graph.json` fresh automatically.\n\nOnce the graph exists, turn on the higher-level systems as needed:\n\n```sh\n# Repository memory: ingest history, docs, decisions, and outcomes\nsynaptic memory refresh --root .\nsynaptic memory search \"previous auth migration\"\n\n# API maintenance: configure monitored APIs and check real usage\nsynaptic api init\nsynaptic api discover --json\nsynaptic api coverage --json\nsynaptic api scan --offline --json\n\n# AI assistant integration: serve the graph and memory over MCP\nsynaptic serve\nsynaptic install codex --global\n```\n\nThe safest mental model: run `extract` first, use `query` / `affected` / `search` to explore,\nadd hooks or `watch` when the project is active, then enable `memory` and `api` workflows when\nyou want Synaptic to preserve history or maintain external contracts.\n\n---\n\n## Why\n\n- **Structural clarity.** God nodes, surprising cross-module connections, import cycles, and\n community structure are computed for you.\n- **Impact and foresight.** Reverse impact, change forecasting, and speculative test runs\n answer \"what depends on this?\" and \"what would this change break?\" before you touch the code.\n- **Token economy.** Querying a compact graph costs a fraction of feeding raw files to an\n LLM, so an assistant can answer those questions without loading the repo.\n- **Confidence you can audit.** Every inferred relationship is tagged `EXTRACTED`,\n `INFERRED`, or `AMBIGUOUS`.\n- **Scales past one repo.** A workspace can federate many repos with real cross-repo edge\n resolution (export surfaces plus import / tsconfig / module-federation aliases).\n- **Offline by default.** A code-only corpus never makes a network call. The optional\n semantic pass over docs and papers is the only feature that needs an API key.\n\n## Highlights\n\n- **30+ languages** via tree-sitter, each built and tested in isolation in CI, plus\n regex-based extractors for a few formats and script extraction for Vue/Svelte/Astro and\n Razor/Blazor. See [Languages](https://github.com/ColinVaughn/Synaptic/wiki/Languages).\n- **One command to a full graph** plus 2D, 3D, and SVG visualizations, a Markdown report,\n and GraphML / Cypher / DOT / Obsidian / wiki exports. See [Output Formats](https://github.com/ColinVaughn/Synaptic/wiki/Output-Formats).\n- **Graph queries**: relevant-subgraph search, shortest path, node explanation,\n reverse-impact (\"what depends on this\"), find-all-references (`synaptic references` /\n the `find_references` tool: everywhere a symbol is used, including the imports and\n inheritance a caller-only view misses), and per-file symbol outlines. See\n [Querying](https://github.com/ColinVaughn/Synaptic/wiki/Querying).\n- **Dynamic-dispatch awareness**: event buses (Node EventEmitter, DOM CustomEvent, C# events)\n and Electron IPC link a publisher to its subscriber through a channel node, so a handler reached\n only across the bus is not a phantom 0-caller. Reflection and dynamic dispatch that cannot be\n resolved statically (by-name lookups, dispatch tables, `eval`, dynamic import, .NET/Python/JVM\n reflection) are cataloged so a \"0 dependents\" answer is never mistaken for \"safe to change\":\n `synaptic hazards` (and the `dynamic_hazards` MCP tool) list the sites, and `affected` attaches a\n caveat when a symbol is reachable only dynamically.\n- **Time-travel diff**: `synaptic diff [rev2]` (or `--since `) reports how the\n graph changed between two git revisions, added/removed dependencies, removed APIs,\n architectural drift, new cycles, and hotspots, with a Markdown or self-contained HTML report.\n- **Architectural search (SYNQL)**: `synaptic search` runs a small Cypher-inspired query\n language over the graph, matching on structure (kind, visibility, LOC, fan-in/out,\n variable-length paths) with `count(...)` aggregation, `--explain`, saved queries, and a\n library of named patterns (singleton, factory, observer, service-locator, god-class). Not\n text search. `synaptic search --file ` lists every symbol defined in a file, ordered\n by line, with no query needed.\n- **Safe refactor**: `synaptic refactor rename` / `move` / `extract` emit a confidence-scored\n execution plan (`plan.json` + `plan.md`) for an AI agent to apply, then `refactor verify`\n rebuilds and checks the graph held (the definition moved/renamed, no references lost, no new\n cycles). Synaptic never edits source itself.\n- **Change forecasting and speculative execution**: `synaptic predict` forecasts a change's\n blast radius, public APIs at risk, at-risk tests, new cycles, risk score, and a verify\n checklist before you edit (`--edit \":\"` forecasts a described edit before any\n code is written); `synaptic speculate` then applies the change in a throwaway git worktree\n and actually runs the at-risk tests plus a build/type-check, reporting real pass/fail — the\n ground-truth half of prediction; and `synaptic eval replay` replays history to score forecast\n quality against git ground truth (co-edited tests, removed APIs), turning prediction accuracy into\n a CI-gateable metric. See\n [Commands](https://github.com/ColinVaughn/Synaptic/wiki/Commands).\n- **SQL performance & security audit**: `synaptic sql audit` flags row-level-security gaps,\n over-broad grants, likely SQL injection, missing indexes on filter/foreign-key columns,\n `SELECT *`, non-sargable predicates, N+1 patterns, and missing primary keys over the SQL-aware\n graph (extraction now models columns, indexes, RLS policies, and grants, and links application\n queries to the tables they touch). `synaptic sql advise --query \"\"` critiques a candidate\n query before you write it, cross-referenced against the graph's tables/indexes/RLS. See\n [SQL Auditing](https://github.com/ColinVaughn/Synaptic/wiki/SQL-Auditing).\n- **Resource graph** (universal, on by default): data/resource files (data JSON and `.mcmeta`\n under `assets/`, `data/`, and generated dirs) are indexed as graph nodes, and reference-like\n strings inside them bind to the file, resource (by path-derived id like `ns:path`), or code\n symbol they name — so `affected` and `query_graph` span code *and* resources. A generated\n resource that duplicates a hand-authored one at the same logical path gets a `shadows` edge\n (surfaced by `readiness_audit`). Framework-agnostic — a Minecraft `ResourceLocation` is just\n one instance of the logical-id shape. Localization JSON also contributes a bounded set of\n key-only search aliases (never translated prose), so message catalogs are discoverable\n without one graph node per translation. `extract --no-resources` restores the code-only graph.\n- **Port/readiness audit**: `synaptic audit readiness` ranks likely port blockers from graph,\n source, and config signals: framework sentinel returns, placeholders/stubs,\n generated-resource noise, and project metadata. The MCP `readiness_audit` tool exposes the\n same structured report.\n- **MCP server** (stateless protocol 2026-07-28 with legacy compatibility through\n 2025-11-25) exposing 30 core tools, five vulnerability tools, and five\n read-only repository-memory tools over stdio or HTTP:\n subgraph search, source reading, reverse-impact, find-all-references, dynamic-dispatch hazards,\n PR/working-tree blast radius, change forecasting, predictive test selection, edit-impact prediction,\n structural search, time-travel diff, plan-only rename, and SQL audit/advise, plus prompts, completions,\n resource subscriptions, and structured tool output. See\n [MCP Server](https://github.com/ColinVaughn/Synaptic/wiki/MCP-Server).\n- **Source-grounded repository memory**: a temporal overlay for previous\n changes, failed attempts, regressions, decisions, procedures, verification,\n external issue/PR/CI/incident artifacts, semantic community summaries, and\n revision-aware file/symbol lineage. Git hooks capture exact commits and\n refresh knowledge; principal policy, compact/federated stores, checksummed\n team bundles, retrieval benchmarks, and aggregate impact evidence are built\n into the CLI and MCP surface.\n See [Repository Memory](https://github.com/ColinVaughn/Synaptic/wiki/Repository-Memory).\n- **Self-maintaining API workflows**: `synaptic api` inventories SDK versions,\n discovers contracts, records coverage gaps, detects source-grounded breaking\n changes, localizes affected call sites, and prepares bounded repairs in an\n isolated worktree. Verification fails closed on incomplete evidence, and only\n the explicit `publish` stage can create or update an idempotent draft PR. See\n [API maintenance](docs/procedures/api-maintenance.md).\n- **Dependency vulnerability management**: `synaptic vuln` reads every lockfile in\n a repository across 12 package ecosystems, matches resolved versions against an\n OSV corpus, and decides whether each advisory actually applies here rather than\n stopping at a version match. Findings carry an evidence ladder, a dependency\n path, a CVSS-derived priority, graph-backed call sites and entry-point\n exposure, and a remediation plan; applicable findings with a fixed target can\n become bounded, isolated repairs whose patched dependency resolution and\n repository tests must pass before Synaptic can create one deterministic draft\n GitHub PR or GitLab MR. Checksummed export/import keeps repair and provider\n credentials separated, and Synaptic never approves or merges. Accepted risks\n are time-boxed and expire on their own. Five MCP tools let assistants check packages, run a\n graph-backed scan, inspect exposure evidence, and request a bounded repair\n hand-off. Whole-repository scans stay local by default; an agent must opt in\n before the dependency list is sent to OSV. See\n [Vulnerability Management](https://github.com/ColinVaughn/Synaptic/wiki/Vulnerability-Management).\n- **Incremental rebuilds**, file watching, and git hooks keep the graph current. See\n [Incremental Updates](https://github.com/ColinVaughn/Synaptic/wiki/Incremental-Updates).\n- **Graph-aware PR dashboard** with blast radius and merge-order conflict detection. See\n [PR Dashboard](https://github.com/ColinVaughn/Synaptic/wiki/PR-Dashboard).\n\n---\n\n## Token economy\n\nA core payoff of querying a compact graph is **reading a small answer instead of the whole\ncodebase**. `query_graph` defaults to a terse, ranked list of the most relevant symbols (a\nfew hundred tokens); pass `full=true` for the whole subgraph with its edges. The figures\nbelow measure a *full* subgraph response (at a 2,000-token budget) on Synaptic's own source\n(199 Rust files, 56,408 lines, **510,966** `cl100k` tokens) -- one such answer to a\nstructural question is **~1,950 tokens**, versus reading the source files it actually touches:\n\n\n \n \"A\n\n\nAcross six questions spanning different subsystems, querying the graph used **27-38x fewer\ntokens** (about **31x overall**) than reading the files the answer references:\n\n| Question | Query response | Read the files | Fewer tokens |\n|---|--:|--:|--:|\n| http request handling | 1,804 | 48,803 | 27x |\n| session create / reap | 1,974 | 65,578 | 33x |\n| query_graph subgraph | 2,011 | 53,759 | 27x |\n| extraction walker | 1,977 | 70,443 | 36x |\n| PR fetch / rank | 1,926 | 73,231 | 38x |\n| incremental merge | 2,010 | 53,440 | 27x |\n\nA query response stays small no matter how big the repo gets (it is capped by the token\nbudget), so the ratio grows with the codebase. Note the `graph.json` index itself is large\nbecause it encodes every symbol and edge; you never load it into context, you query it and\nget back only the slice above.\n\n**Reproducible.** Tokens are exact `cl100k_base` counts via\n`cargo run -p synaptic-server --example tokcount`. The baseline is the unique source files\nreferenced by the result (whole files, the conservative grep-then-read case; it does not\ncount the dead-end files you would open without the graph). Run `synaptic extract .` on any\nrepo and compare for yourself. This is a context-compression measurement, not an end-to-end\nagent-savings claim; the paired SWE-bench/BEIR methodology is in [BENCHMARKS.md](BENCHMARKS.md#agent-token-efficiency-and-standard-retrieval).\n\n## Advanced-tool performance\n\nThe analysis tools answer in milliseconds because they run over the in-memory graph, not the\nsource. Criterion micro-benchmarks (dev machine; run `cargo bench -p synaptic-synql -p synaptic-refactor`):\n\n| Operation | Workload | Time |\n|---|---|--:|\n| SYNQL property query (`search`) | `WHERE`/`loc`/`fan_out` over a 2,000-node graph | **~0.47 ms** |\n| SYNQL relationship-pattern join (`search`) | one-hop join over a 2,000-node graph | **~0.97 ms** |\n| Safe-refactor rename plan (`refactor rename`) | hot symbol, ~120 call sites across 40 files, incl. the textual scan | **~4.9 ms** |\n\nThe 0.6.3 graph-pipeline audit added dedicated Criterion coverage for construction,\nincremental comparison, and federation (`cargo bench -p synaptic-graph -p\nsynaptic-incremental -p synaptic-workspace`). On the audit fixtures, one-pass\n16 x 500-node federation measured **136.1 -> 6.07 ms**, a 10k-node topology\ncomparison **54.92 -> 9.77 ms**, and a 1,000-site duplicate edge **240.74 ->\n0.56 ms**. These are machine-dependent micro-benchmarks; the committed fixtures\nand growth curves are the reproducible evidence.\n\nTime-travel `diff` is build-bound rather than query-bound: the graph delta itself is\nnear-instant, and the cost is building each revision in a throwaway git worktree. Built\ngraphs are cached per commit SHA under `synaptic-out/history/`, so a repeat diff of the same\ncommits returns immediately and only the working-tree side is rebuilt.\n\n## Accuracy\n\nThe token study above is a smoke test on one repo. The relationships Synaptic extracts are\nvalidated separately, against a **hand-labeled corpus** of mini-repos whose true call edges,\ntest linkages, blast radii (including distractor nodes that must *not* be flagged), and\ncross-language couplings (including look-alikes that must *not* connect) are written out by\nhand in a `ground_truth.toml`. A preflight fails the run if any labeled symbol does not resolve,\nso a dropped node becomes a loud failure rather than a quietly smaller denominator. Every number\nbelow is exact set-comparison against those labels, reproducible with `synaptic eval corpus`:\n\n| Fixture | Family | Call P/R/F1 | Aff-test rec | Blast rec / excl / size | Cross P/R/F1 |\n|---|---|---|---|---|---|\n| systems-rust | systems-rust | 100/50/66 | — | 100% / 100% / 1.0 | — |\n| scripting-python | scripting-python | 100/100/100 | 100% | 100% / 100% / 2.0 | — |\n| web-ts | web-ts | 100/100/100 | — | 100% / 100% / 1.0 | — |\n| oo-java | oo-java | 100/100/100 | — | 100% / 100% / 1.0 | — |\n| systems-go | systems-go | 100/100/100 | — | 100% / 100% / 1.0 | — |\n| deep-python (multi-hop) | scripting-python | 100/100/100 | 100% | 100% / 100% / 3.0 | — |\n| cross-lang-ts-rust | cross-lang | — | — | — | 100/100/100 |\n| cross-lang-grpc | cross-lang | — | — | — | 100/100/100 |\n| cross-lang-queue | cross-lang | 100/100/100 | — | — | 100/100/100 |\n| cross-lang-pyo3 | cross-lang | 100/100/100 | — | — | 100/100/100 |\n| cross-lang-ws | cross-lang | 100/100/100 | — | — | 100/100/100 |\n\nAcross 11 fixtures / 6 language families / 42 labeled symbols (all resolved): pooled call edges\n**precision 100% / recall 94% / F1 97%** over 18 labeled edges; blast-radius **recall 100% with\n0 distractors leaked**; affected-test **recall 100%** over the labeled linkages with the one\nlabeled *unrelated* test correctly **not** selected; cross-language **precision 100% / recall\n100% / F1 100%** over 6 labeled couplings with 6 distractor couplings (look-alike routes, a\nwrong-service gRPC stub, an unregistered PyO3 helper, ...) correctly **not** connected. Reading\nthe numbers honestly:\n\n- **No false call edges were observed** in this 18-edge corpus (precision 100%); that is a\n result on the corpus, not a guarantee at scale.\n- **Recall is 100%** for Python/TypeScript/Java/Go, which resolve cross-file calls. The **50%**\n on Rust is real and expected: Rust call resolution is intra-file, so a module-qualified\n cross-file call is a true miss. Cross-file *reachability* is still preserved through `imports`\n edges, which is why blast-radius recall stays 100%.\n- **Blast radius is scored for noise, not just misses:** each seed labels distractor nodes that\n must stay out, and none leaked (100% exclusion); the average reported impact-set size equals\n the true affected-set size, so the walk is not over-broad.\n- **Affected-test selection is multi-hop:** the `deep-python` fixture changes a leaf three call\n hops below its test and still selects it, while a deliberately unrelated test is excluded\n (so recall is not bought with precision).\n- **Cross-language precision is earned across five boundary kinds:** a TypeScript\n `fetch(\"/session\")` connects to the Rust axum handler that serves it (and a mounted\n `/api/users` client reaches its prefix-composed route); a Python gRPC client reaches its tonic\n server; a Kafka producer reaches its consumer; a Python `import` reaches its PyO3-exported Rust\n function; a JS WebSocket command reaches its C# handler — while every look-alike distractor\n (a `/sessions` path, a wrong-service stub, a wrong topic, an *unregistered* PyO3 helper, an\n unhandled message) is correctly left unconnected.\n\nThe corpus is intentionally small and hand-verified; it validates extraction *correctness* on\nrepresentative shapes, not internet-scale coverage. The [scale](#scale) section measures real\nrepositories. See [BENCHMARKS.md](BENCHMARKS.md) for methodology and the ground-truth format.\n\n### Prediction calibration\n\nThe change-forecast layer attaches a confidence to each predicted co-change. `synaptic eval\ncalibrate` measures whether that confidence is meaningful: it walks recent history, and for each\ncommit uses every changed file as a seed, asks the predictor (trained only on prior commits)\nwhich files should co-change, then scores each prediction's confidence against what actually\nchanged. It reports a **reliability table** (predicted vs. observed hit rate per confidence\nbin), a **Brier score**, the **Brier skill score** against an always-guess-the-base-rate\nbaseline (so the Brier number is interpretable), and **expected calibration error**.\n\nThis is a per-repo property: confidence reflects each repo's commit habits, so run it on yours.\nOn this repo's own (squash-heavy, synthetic) history the skill score is **negative** — co-change\nprediction there is *worse than guessing the base rate*, because squashed commits touch many\nfiles at once and inflate apparent co-change. That is the metric working: it refuses to dress up\na predictor that is miscalibrated on this history. Methodology in [BENCHMARKS.md](BENCHMARKS.md).\n\n## Scale\n\nExtraction throughput across real OSS repositories spanning size tiers and language families,\neach cloned at a pinned SHA (`synaptic eval scale`; network + git, opt-in). Each timing is the\nmedian of 5 reps. The 2026-08-12 run covered **10 repositories, 9 language families, 783,928\nsupported LOC, 71,437 nodes, and 111,851 edges** with no skips. Warm throughput ranged from\n44k to 339k LOC/s; median cold-to-warm speedup ranged from 1.4x to 2.8x. The largest checkout\nmeasured here, Humanizer (476,967 supported LOC), took 7.07s cold and 2.69s warm.\n\nThose are machine-specific development-worktree results, not universal or clean-release\nclaims. \"Cold\" clears Synaptic's AST cache but the checkout and OS file cache were warm;\nincremental timing re-extracts a named unchanged source file and is not patch latency. Full\nmethod, per-repository results, limitations, exact SHAs, and raw samples are in\n[BENCHMARKS.md](BENCHMARKS.md).\n\n## Extraction quality at scale\n\nScale measures how *fast* extraction runs; a graph that anchored every declaration to the wrong\nline would post identical timings. `synaptic eval quality` measures whether the graph is **right**,\nacross **60 pinned repositories covering all 39 shipped languages** (80,061 files, 938,001 nodes),\nusing properties that need no hand labels: anchor exactness, parse and recovery health,\ndeterminism, incremental equivalence, and an independent universal-ctags comparison.\n\nThe 2026-08-15 run: **pooled anchor exactness 735,198 / 735,493 (99.96%)**, with **60/60\nrepositories deterministic and incrementally equivalent** and no skips. 30 of 39 languages are\nexact on every checked declaration.\n\nThe corpus is language-complete by construction — a test fails when a shipped extractor has no\nrepository exercising it — and each repository carries pinned bounds, so a regression exits\nnon-zero naming the repository and metric. The oracle is published as a symmetric difference,\nnever a recall score: ctags is an independent second opinion, not ground truth. Method,\nper-language results, and the defects this benchmark found are in [BENCHMARKS.md](BENCHMARKS.md).\n\n## Install\n\nSynaptic builds with a stable Rust toolchain (pinned to 1.97.1 via\n[rust-toolchain.toml](rust-toolchain.toml)).\n\n```sh\n# From a clone, installs the `synaptic` binary onto your PATH:\ncargo install --path bin/synaptic\n\n# Optional native workspace/MCP setup app (uses `synaptic` from the same directory or PATH):\ncargo install --path bin/synaptic-ui\n\n# ...or build it in-tree:\ncargo build --release -p synaptic -p synaptic-ui\n```\n\nPrebuilt CLI and optional UI binaries for Linux/macOS/Windows are attached to each tagged\n[GitHub Release](../../releases) (see the `release` workflow). Optional integrations are\nbehind feature flags (off by default): `pg` (Postgres introspection), `push` (live\nNeo4j/FalkorDB export), and `office` / `gws` / `media` (spreadsheet / Google-Workspace /\naudio-video ingest), e.g. `cargo install --path bin/synaptic --features pg,push`. See\n[Installation](https://github.com/ColinVaughn/Synaptic/wiki/Installation),\n[Desktop UI](https://github.com/ColinVaughn/Synaptic/wiki/Desktop-UI), and\n[Configuration](https://github.com/ColinVaughn/Synaptic/wiki/Configuration).\n\nOnce installed, update in place with `synaptic self-update` (verifies a SHA-256\nchecksum and prompts before replacing the binary). Opt in to a background\n\"update available\" notice with `synaptic self-update --enable` — off by default,\nruns at most once a day, and never blocks normal commands. `cargo install` /\nsource builds can self-update too, but the swap installs the default-feature\nprebuilt binary.\n\n## Quickstart\n\n```sh\n# 1. Build the graph for the current directory -> synaptic-out/\nsynaptic extract .\n\n# 2. Ask the graph a question (returns a relevant subgraph)\nsynaptic query \"authentication flow\"\n\n# 3. What would changing a symbol break? (reverse impact)\nsynaptic affected parse_config\n\n# 4. Serve the graph to an AI assistant over MCP\nsynaptic serve\n```\n\n`extract` honors `.synapticignore` / `.gitignore` and skips sensitive files (`.env`, keys).\nA code-only corpus runs fully offline; the optional LLM semantic pass over docs and papers\n(`extract --semantic`) needs an API key (e.g. `OPENAI_API_KEY`). See\n[Quickstart](https://github.com/ColinVaughn/Synaptic/wiki/Quickstart).\n\n## Output artifacts (`synaptic-out/`)\n\n| Artifact | What it is |\n|---|---|\n| `graph.json` | Full graph (node-link JSON), query it without re-reading files |\n| `GRAPH_REPORT.md` | God nodes, surprising connections, suggested questions, import cycles |\n| `graph.html` | Interactive 2D explorer (search + community color) |\n| `graph-3d.html` | Interactive 3D force graph (search, relation toggles, federation colors) |\n| `graph.svg` | Static layout (Barnes-Hut, component-packed, asset-shaped) |\n| `chart.html` | On-demand architecture map with community-to-symbol drill-down from `synaptic chart` |\n| `graph.graphml` / `graph.cypher` / `graph.dot` | Import into Gephi / Neo4j / Graphviz |\n| `callflow.html` / `tree.html` | Mermaid call-flow + D3 file tree |\n| `obsidian/`, `wiki/` | Obsidian vault / Markdown wiki (with `--obsidian` / `--wiki`) |\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `extract [path]` | Build the graph and write `synaptic-out/`. Flags: `--directed`, `--obsidian`, `--wiki`, `--semantic` |\n| `export ` | Re-emit a format from an existing `graph.json` (no rebuild) or push live to Neo4j/FalkorDB |\n| `chart` | Create an offline interactive architecture map with source-backed subsystem drill-down. Flags: `--graph`, `--out`, `--repo`, `--max-communities` |\n| `query ` | Return a relevance-ranked subgraph (each node scored). Flags: `--max-nodes`, `--repo`, `--dfs`, `--since ` (boost code changed on the branch), `--seed-changed`, `--json` |\n| `path ` | Shortest path between two nodes |\n| `explain ` | Show a node and its neighbours |\n| `affected ` | Nodes that (transitively) depend on a node; adds a caveat when a \"0 dependents\" symbol is reachable only via dynamic dispatch. Flags: `--depth`, `--relation` |\n| `hazards` | List reflection / dynamic-dispatch sites the graph records, so a \"0 dependents\" answer is not mistaken for \"safe\". Flags: `--repo`, `--kind`, `--limit` |\n| `search [synql]` | Structural search via SYNQL or a named `--pattern`. Flags: `--explain`, `--save`/`--saved`, `--json` |\n| `diff [rev2]` | Time-travel graph diff between two git revisions. Flags: `--since`, `--report`, `--html`, `--scope` |\n| `refactor ` | Plan a safe `rename`/`move`/`extract` for an agent, then `verify` the graph (never edits source) |\n| `predict [paths...]` | Forecast a change before applying it: blast radius, at-risk tests, risk, removed APIs, cycles. Flags: `--base`, `--edit \":\"`, `--gate` |\n| `speculate [paths...]` | Run a change for real in a throwaway worktree: at-risk tests + a build/type-check, reporting pass/fail. Flags: `--patch`, `--test-cmd`, `--check-cmd` |\n| `audit readiness` | Static port/readiness audit: ranks framework sentinel returns, placeholders/stubs, generated-resource noise, and project metadata. Flags: `--profile`, `--severity`, `--repo`, `--json` |\n| `sql ` | `audit` SQL for performance + security over the SQL-aware graph, or `advise --query \"\"` on a candidate query before writing it. Flags: `--severity`, `--explain --db-url` (live EXPLAIN, needs `--features live-explain`) |\n| `eval replay [from]` | Replay history to score forecast quality against git ground truth (CI-gateable). Flag: `--min-test-recall` |\n| `eval quality` | Measure extraction correctness across the pinned real-world corpus, gated against per-repo baselines (network + git, opt-in). Flags: `--language`, `--repo`, `--pin`, `--update-baselines` |\n| `update [paths...]` | Incrementally rebuild after files change (`--full` for a full rebuild) |\n| `watch` | Rebuild automatically as files change (single repo; use `workspace build --watch` for a workspace) |\n| `serve` | Run the MCP server (stdio, or `--http --api-key `) |\n| `prs [number]` | Graph-aware PR dashboard / detail. Flags: `--triage`, `--conflicts`, `--base`, `--repo` |\n| `workspace ` | Multi-repo / monorepo federation (`init`/`add`/`discover`/`build`/`federate`/`coordinate`/`sync`/`status`/`list`). `build --watch` keeps a federated graph live across every member repo |\n| `global ` | The cross-repo global graph store (`~/.synaptic`) |\n| `memory ` | Ingest, record, search, compact, exchange, and evaluate durable source-grounded repository memory |\n| `api ` | Inventory API dependencies, discover contracts, measure coverage, scan changes, assess impact, and safely repair/verify/publish a draft PR |\n| `merge-graphs ` | Compose several `graph.json` files into one namespaced graph |\n| `ingest ` | Ingest an external source (cargo / mcp / scip / pg / url; `office` / `gws` / `media` behind feature flags) |\n| `hook ` | Manage git hooks + the `graph.json` merge driver |\n| `install` / `uninstall [platform]` | Install the Synaptic skill for a host assistant |\n| `cache ` | Maintain the on-disk extraction cache |\n| `self-update` | Update the binary from the latest GitHub release (opt-in). Flags: `--enable`/`--disable` (background notice), `--check`, `--yes` |\n\nThe full reference with every flag is in [Commands](https://github.com/ColinVaughn/Synaptic/wiki/Commands). Run\n`synaptic --help` for the flag list at the terminal.\n\n## Use it from an AI assistant (MCP)\n\n```sh\nsynaptic serve # stdio MCP server\nsynaptic serve --http 127.0.0.1:8765 --api-key \"$SYNAPTIC_API_KEY\" # HTTP server\nsynaptic serve --allow-memory-write # opt-in outcome recording\nsynaptic serve --memory-principal reviewer \\\n --memory-repository-claim owner/repo # scope-filtered memory\nsynaptic serve --graph promoted/graph.json --immutable-graph \\\n --expected-graph-sha256 \"$GRAPH_SHA256\" # authenticate exact loaded bytes\nsynaptic serve --http 127.0.0.1:0 --ready-file /run/synaptic/ready.json # race-free child startup\n```\n\nThe server exposes 30 core tools, five vulnerability tools, and five read-only\nrepository-memory tools:\ngraph navigation (`query_graph`, `get_node`,\n`get_source`, `get_neighbors`, `get_community`, `god_nodes`, `graph_stats`, `shortest_path`),\nimpact analysis (`affected`, `find_callers`, `find_callees`, `find_references`, `dynamic_hazards`,\n`predict_impact`, `affected_tests`, `predict_edit`), federation (`list_repos`, `repo_stats`), change/PR review (`working_changes_impact`,\n`list_prs`, `get_pr_impact`, `triage_prs`), the advanced trio (`structural_search`,\n`time_travel_diff`, plan-only `plan_rename`), port/readiness audit (`readiness_audit`), and SQL auditing (`audit_sql`, `advise_sql`).\nVulnerability work adds `vuln_check_dependency`, `vuln_findings`,\n`vuln_explain`, `vuln_scan`, and `vuln_brief`; a scan writes only with\n`record: true` and sends dependency coordinates to OSV only with `online: true`.\nOn federated graphs, agents select a tag from `list_repos`; scans, findings,\nexplanations, ledgers, and repair briefs are then isolated to that member,\nincluding external checkouts and Git-cached repositories. Artifact-only members\nare explicitly reported as not scannable.\nMemory retrieval adds `search_memory`, `explain_history`,\n`find_similar_change`, `known_pitfalls`, and `explain_decision`;\n`record_change_outcome` is advertised only with `--allow-memory-write`.\nIt also serves MCP prompts, argument completions, resource templates and\nsubscriptions, and a small REST surface (`/api/stats`, `/api/query`, ...) for non-MCP\nclients. Tool output is tuned to stay token-lean (terse defaults, capped lists); add\n`serve --concise` (or set `SYNAPTIC_CONCISE`) to lower the default sizes further.\nFor digest-pinned or read-only deployments, `serve --immutable-graph\n--expected-graph-sha256 ` authenticates the exact byte buffer it parses\nand disables disk hot-reload, source catch-up, and filesystem watching.\n`--http 127.0.0.1:0 --ready-file ` binds before atomically publishing the\nkernel-assigned address, avoiding port reservation races in process supervisors.\n`synaptic install` wires the graph into a host assistant (a `PreToolUse` hook for\nClaude; a native MCP server for Codex, with `synaptic install codex --global` for the Codex\ndesktop app). See [MCP Server](https://github.com/ColinVaughn/Synaptic/wiki/MCP-Server) and\n[Assistant Integration](https://github.com/ColinVaughn/Synaptic/wiki/Assistant-Integration).\n\n## Languages\n\n30+ languages via tree-sitter, each built and tested in isolation in CI: Python,\nJavaScript/TypeScript (+ JSX/TSX, Vue/Svelte/Astro), Go, Rust, Java, C#, Kotlin, Swift, C,\nC++, Objective-C, Ruby, PHP, Scala, Groovy, Lua, Dart, Elixir, Julia, Zig, Bash, PowerShell,\nVerilog, Fortran, CodeQL QL, and regex/delegation extractors for Classic ASP, Salesforce Apex,\nPascal/Delphi, and Razor/Blazor. Plus data and project formats: SQL, JSON, YAML,\nHCL/Terraform, .NET project files (`.csproj`/`.sln`/`.slnx`), and Markdown structure.\nFramework-aware edges for PHP/Laravel and Dart/Flutter. Full breakdown in\n[Languages](https://github.com/ColinVaughn/Synaptic/wiki/Languages).\n\n## Documentation\n\nThe graph-native, vendor-neutral self-maintaining API workflow is documented in\n[API maintenance](docs/procedures/api-maintenance.md).\n\nThe full documentation lives in the [project wiki](https://github.com/ColinVaughn/Synaptic/wiki):\n\n- **Getting started:** [Home](https://github.com/ColinVaughn/Synaptic/wiki/Home) - [Installation](https://github.com/ColinVaughn/Synaptic/wiki/Installation) - [Quickstart](https://github.com/ColinVaughn/Synaptic/wiki/Quickstart)\n- **Concepts:** [Architecture](https://github.com/ColinVaughn/Synaptic/wiki/Architecture) - [Languages](https://github.com/ColinVaughn/Synaptic/wiki/Languages)\n- **Using it:** [Commands](https://github.com/ColinVaughn/Synaptic/wiki/Commands) - [Extraction](https://github.com/ColinVaughn/Synaptic/wiki/Extraction) - [Querying](https://github.com/ColinVaughn/Synaptic/wiki/Querying) - [Analysis and Reports](https://github.com/ColinVaughn/Synaptic/wiki/Analysis-and-Reports) - [Output Formats](https://github.com/ColinVaughn/Synaptic/wiki/Output-Formats) - [Visualizations](https://github.com/ColinVaughn/Synaptic/wiki/Visualizations)\n- **Integrations:** [MCP Server](https://github.com/ColinVaughn/Synaptic/wiki/MCP-Server) - [Assistant Integration](https://github.com/ColinVaughn/Synaptic/wiki/Assistant-Integration) - [Ingestion](https://github.com/ColinVaughn/Synaptic/wiki/Ingestion) - [Semantic Analysis](https://github.com/ColinVaughn/Synaptic/wiki/Semantic-Analysis)\n- **Scaling:** [Workspaces and Federation](https://github.com/ColinVaughn/Synaptic/wiki/Workspaces-and-Federation) - [Incremental Updates](https://github.com/ColinVaughn/Synaptic/wiki/Incremental-Updates) - [PR Dashboard](https://github.com/ColinVaughn/Synaptic/wiki/PR-Dashboard)\n- **Reference:** [Configuration](https://github.com/ColinVaughn/Synaptic/wiki/Configuration) - [Development](https://github.com/ColinVaughn/Synaptic/wiki/Development)\n\n## Development\n\n```sh\ncargo test --workspace --all-features # all tests\ncargo fmt --all --check # formatting (enforced in CI)\ncargo clippy --workspace --all-targets --all-features -- -D warnings\n```\n\nThe codebase is 27 library crates (`crates/*`) plus the `synaptic` binary (`bin/`). CI\nbuilds each language grammar in isolation so a grammar bump that silently drops nodes/edges\nfails on its own. See [Development](https://github.com/ColinVaughn/Synaptic/wiki/Development) and [Architecture](https://github.com/ColinVaughn/Synaptic/wiki/Architecture).\n\n## Star History\n\n\n \n \n \n \"Star\n \n\n\n## Community\n\nQuestions, ideas, or want to show what you built? Join us on\n[Discord](https://discord.gg/ytX7R2PbNz).\n\n## License\n\nGNU Affero General Public License, version 3 or later\n(`AGPL-3.0-or-later`), see [LICENSE](LICENSE) and [NOTICE](NOTICE). If you modify\nSynaptic and let users interact with it over a network, the license requires you\nto offer those users the corresponding source. Historical releases remain\navailable under the licenses under which they were received. The separately\nmaintained private Synaptic Platform site and B2B control plane are proprietary\nand are not covered by this repository's license.\n", "bytes": 42852, "sha": "f61ad88a044d7258562f69e1a334144bf6b8ed2ddd1f1412754381de9a4d348b", "repo_slug": "colinvaughn/synaptic", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_colinvaughn_synaptic_b1474c94/readme" }