Synapse Documentation

Installation

Install options:

# Option A: install the VS Code extension (recommended for daily use)

# Option B: CLI (global install, if published)
npm install -g synapse-cli

# Option C: use the repo-local CLI (this repo)
node .\bin\synapse-unified.js --help

Quick Start

Typical workflow after opening a project:

# If you already have rules in an IDE folder (Cursor/Trae/Windsurf/Cline/Zed)
Command Palette → Synapse: Import Rules from IDE

# If you do not have rules yet
Command Palette → Synapse: Initialize Project

# Then compile Synapse rules into IDE outputs
Command Palette → Synapse: Sync Rules

CLI equivalent:

synapse init
synapse sync --all --conflict prompt

Synapse Rule Format

# Rule: Rule Name
# Description: What this does

Your instructions here

# Constraints:
# @constraint **/*.ts

# Skills:
# @skill code-review

VS Code Extension

Open the sidebar: Synapse → Control Center. Use the Command Palette for power-user workflows.

Command Palette → Synapse: Initialize Project
Command Palette → Synapse: Import Rules from IDE
Command Palette → Synapse: Sync Rules
Command Palette → Synapse: Analyze Tokens
Command Palette → Synapse: Backup
Command Palette → Synapse: Detect Conflicts
Command Palette → Synapse: Optimize Rules (Local)

Once rules exist in .synapse/rules/, you can also:

- Compress Workspace / Compress Current File
- Convert to Skills (Pro) for rarely-needed long content
- Apply Best Practices to add missing safety / token hygiene / response defense rules

Optimize/Detect runs the CLI in the background and streams logs to the Synapse Output panel (no visible terminal).

CLI

Use the CLI for automation and CI:

synapse init
synapse sync --all --conflict prompt      # safe sync with prompts
synapse sync --dry-run --list-changes     # preview changes only
synapse analyze                           # find the biggest rules
synapse optimize                          # local rule optimization (free analysis)
synapse optimize --backup                 # create a local backup before analyzing
synapse optimize --apply                  # apply auto-fixes (Pro)
synapse backup list                       # list local backups
synapse backup restore --backup <name>      # restore a backup
synapse diff                              # compare current rules vs latest backup
synapse rollback --backup <name>            # restore rules only; run sync after
synapse enter-license                     # save Pro key for CLI features
synapse resend-license you@example.com    # email your key again (if enabled)
synapse watch                             # auto-sync on changes

Native Binaries

You can build standalone executables with pkg (no Node.js required for end users).

npm install
npm run build:binary:win

# outputs in dist/

On GitHub, binaries are built by CI when you push a tag like v0.1.0.

Syncing Rules

Synapse keeps one source of truth in .synapse/ and compiles outputs for enabled IDE targets.

.synapse/
  rules/        # master rules
  skills/       # lazy-loaded skills (Pro)

.trae/rules/    # Trae output (.md)
.cursor/rules/  # Cursor output (.mdc)
.windsurf/      # Windsurf output (.windsurfrules)
.clinerules/    # Cline output (.md)

Zed uses a root .rules file (auto-included in Agent context).

.rules

To avoid overwriting existing IDE rules, use:

synapse sync --conflict prompt          # ask before overwrite
synapse sync --rules my-rule,other-rule  # sync selected rules only

IDE Adapters

Adapters are small JSON files that define how Synapse integrates with each IDE.

~/.synapse/adapters/cursor.json
~/.synapse/adapters/trae.json
~/.synapse/adapters/windsurf.json
~/.synapse/adapters/cline.json
~/.synapse/adapters/zed.json

Commands:

synapse adapters list
synapse adapters update cursor
synapse adapters update --all
synapse adapters versions cursor          # Pro
synapse adapters rollback cursor 1.1.0    # Pro

Free tier uses manual adapter downloads (no auto-updates). Pro unlocks one-click updates, background updates during synapse sync, adapter version history, and rollback.

To pin a manual adapter and disable auto-updates, place an override file:

~/.synapse/adapters/overrides/cursor.json

During synapse sync, Synapse checks for adapter updates in the background (non-blocking). Pro users can auto-update; Free users get a tip to run synapse adapters update.

Token Analysis

Analyze token usage and estimated cost per session to find the biggest wins quickly.

synapse analyze --top 10 --threshold 2000

# Optional: estimate $ per session (USD per 1M tokens)
synapse analyze --usd-per-1m 10

Local Optimization

Run a local optimizer to detect token waste, redundancy, missing constraints, and potential conflicts. Everything runs 100% locally (no bandwidth).

synapse optimize

Pro can apply safe auto-fixes and creates a backup under ~/.synapse/backups/:

synapse optimize --backup --apply

To undo, restore a backup:

synapse backup list
synapse backup restore --backup backup_2026-04-22T...

Compression

Synapse can compress verbose workspace rules into shorter text while preserving code blocks. Free includes a conservative built-in dictionary; Pro can sync an expanded dictionary.

Behavior: compression always runs. Pro users get extra Pro-only replacements after running “Sync Dictionary”; until then, Pro behaves like Free (built-in dictionary only).

Downloads: Download page • Free dictionary (JSON)

Compression is Unicode-safe: text is normalized (NFC), smart quotes are normalized (curly → straight), and emoji/multi-byte characters are handled correctly.

Try it on your own rules:

# VS Code → Synapse → Control Center → Rule Improvements
# Scan Compression → Compress Workspace

Measure before/after:

synapse analyze

Tip: start with rule sets that include longer “always-on” instructions for the biggest savings.

Control Center

Synapse exposes a single sidebar UI called Control Center to reduce clicks and keep actions + cost + improvements in one place.

Sections:

- Quick Actions: Sync, Analyze, Optimize, Backup, Detect Conflicts
- Cost Dashboard: totals, top rules, recommendations
- Rule Improvements: Compress Workspace, Convert to Skills (Pro), Apply Best Practices
- License: Pro status, Enter/Resend/Forget key, Diagnostics

Pro License

Free tier includes 5 built-in IDE adapters and manual adapter downloads. Pro unlocks:

- Unlimited targets
- Convert large rules to lazy-loaded skills
- One-click adapter updates + background updates during sync
- Adapter versions + rollback
- Additional Pro-only capabilities

To get a Pro key, complete checkout. After successful payment, Synapse issues a license key and stores it server-side.

To activate Pro in the IDE:

Command Palette → Synapse: Upgrade to Pro
Enter License Key

Pro keys are validated by the server (format + HMAC signature + database status). Revoked keys stop working.

License key persistence:

- Extension stores the key in VS Code SecretStorage (survives reinstall better than globalState)
- CLI stores the key in ~/.synapse/license.key
- Use “Synapse: Forget License Key (This Machine)” to remove local activation

Device policy:

- The server requires an instanceId and binds a license key to one machine
- Reinstall on the same machine continues to work (stable instanceId)
- Using the same key on another machine is rejected

Pro Features

- Unlimited IDE targets (Trae, Cursor, Windsurf, Cline, Zed, ...)
- Optional lazy-loaded skills to reduce prompt size and token cost
- Auto-update IDE adapters (with versions + rollback)
- Server-validated license key (revocable)

How activation works: you complete checkout, receive a license key, then enter it in VS Code. The extension validates it against the server before unlocking Pro.

Pro also unlocks CLI auto-fix in synapse optimize --apply (license validated by the server).

MCP + WebSocket

Run standalone servers to integrate with external tools:

cd standalone
npm install
npm run build
npm start       # MCP server
npm run start:ws

Enterprise

Enterprise is planned and will be rolled out soon.