synapses

Overview ¶

daemon.go — "synapses daemon" subcommand Manages the singleton daemon and any external background services. Uses ~/.synapses/pids/ for PID tracking and ~/.synapses/logs/ for output.

Usage:

synapses daemon start            # start all configured sidecars
synapses daemon start --service brain
synapses daemon stop             # stop all
synapses daemon stop --service pulse
synapses daemon restart
synapses daemon status           # show running/stopped state
synapses daemon logs --service brain
synapses daemon install          # register as OS login service (launchd / systemd)
synapses daemon uninstall        # remove OS login service

daemon_admin.go — Phase 0 admin API endpoints for the web console.

These endpoints replace Tauri IPC commands with standard REST so the web console (browser or Tauri) can manage the daemon.

daemon_serve.go — "synapses daemon serve" subcommand.

Runs ONE singleton daemon per machine. Serves multiple projects within a single process. Each project gets its own graph, store, file watcher, and Unix socket (for stdio proxy backward compat).

Architecture (after singleton refactor):

┌─────────────┐   ┌───────────┐
│ Claude Code  │   │  Cursor   │    (stdio MCP — backward compat)
└──────┬───────┘   └─────┬─────┘
       │ stdio             │ stdio
       ▼                   ▼
┌────────────┐    ┌────────────┐
│ mcp proxy  │    │ mcp proxy  │   ← "synapses start --path <repo>"
└──────┬─────┘    └──────┬─────┘
       │ Unix socket       │
       └───────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│       synapses singleton daemon          │  ← ONE per machine
│  HTTP 127.0.0.1:11435                    │
│  GET  /api/admin/health                  │
│  GET  /api/admin/projects                │
│  POST /api/admin/projects                │
│  GET  /api/admin/pulse/summary[?days=N]  │  analytics
│  POST|GET|DELETE /mcp?project=<path>     │  HTTP MCP transport
│  POST /v1/tools/{name}?project=<path>    │  REST tool API (B29)
│  ~/.synapses/daemons/<hash>.sock per-proj │  stdio proxy compat
└─────────────────────────────────────────┘

PID: ~/.synapses/daemon.pid (singleton) Sockets: ~/.synapses/daemons/<sha256(path)[:16]>.sock (one per registered project)

init.go — "synapses init" interactive setup wizard.

This is the single golden-path command for new users. It replaces the old init (stub), onboard (5-step wizard), setup (config writer), and mcp-setup (agent auto-discover) commands with one unified interactive flow:

[1/4] Project Setup  — git init prompt + synapses.json
[2/4] Indexing        — parse codebase, build graph
[3/4] Starting Engine — ensure singleton daemon is running
[4/4] Connect Agents  — multi-select detected AI agents

Non-interactive mode: synapses init --yes --agents claude,cursor

Command synapses is the Synapses MCP server binary. It indexes a code repository into an in-memory graph and serves structured context to AI agents over the Model Context Protocol (stdio transport).

Usage:

synapses start  --path <repo>           Start the MCP server
synapses index  --path <repo>           Index only (no server)
synapses status --path <repo>           Show index statistics

progress.go — per-project indexing progress tracking.

IndexingState is created per project (not a global singleton) and registered in activeIndexes for the duration of a full reindex. The /api/admin/health endpoint calls ActiveSnapshot() to surface live progress to callers.

Cross-process visibility: when `synapses index` runs as a CLI subprocess (separate from the daemon), its progress is written to ~/.synapses/indexing-progress.json. The daemon's ActiveSnapshot() reads that file as a fallback when no in-process indexer is active, making the daemon's health endpoint accurate even for CLI-initiated indexing.

projects.go — persist and reload known project paths across daemon restarts.

Stores a simple JSON array of absolute paths in ~/.synapses/projects.json. On daemon startup, known projects are warmed eagerly in the background so the first MCP request doesn't block on graph indexing.

proxy.go — thin MCP proxy for "synapses start".

Instead of running the full MCP server in-process, this proxy:

1. Ensures the singleton daemon is running (starts it if not).
2. Registers the project with the daemon via HTTP API.
3. Connects to the project's per-project Unix socket.
4. Bridges stdin ↔ socket bidirectionally (zero protocol awareness).
5. Exits when stdin closes (client disconnects) — daemon stays alive.

The proxy is stateless and disposable. Crash it, kill it, spawn 100 of them — the daemon is unaffected.

registry.go — per-project instance registry for the singleton daemon.

The singleton daemon serves multiple projects within one process. Each project gets its own ProjectInstance: graph, store, MCP server, file watcher, brain client, and a per-project Unix socket listener.

selfupdate.go — background self-update check and CLI update command.

The daemon spawns a goroutine that checks GitHub Releases for a newer version every 6 hours. If found, it records the update state (version, changelog URL, asset URL). The binary is NOT downloaded automatically — the user must run `synapses update`.

Update state is persisted at ~/.synapses/update_state.json so the web console, CLI, and MCP can show "update available" banners.

Zero external dependencies — uses only Go stdlib.

uninstall.go — "synapses uninstall" complete removal wizard.

The inverse of "synapses init". Stops the daemon, removes agent configs, cleans indexes, and optionally removes ~/.synapses and the binary itself.

Usage:

synapses uninstall                       Interactive project cleanup
synapses uninstall --path /my/project    Target a specific project
synapses uninstall --yes                 Non-interactive (skip prompts)
synapses uninstall --global              Full system removal (all data + binary)
synapses uninstall --keep-data           Preserve index cache
synapses uninstall --keep-binary         Preserve the synapses binary