Desktop app reference

Navigation and shared state

The desktop app is a local control surface over the same SQLite database, vault, scope files, and tool configuration used by the CLI and MCP server. A column down the left moves between seven screens, grouped by what they answer: what Synapse is wired into, what is running, and what it is holding for you.

Success and error notices appear inside the active screen. The app does not require an account and does not send this state to a hosted service.

Connections

The Connections screen reports memory count, database size, and how many supported tools are connected. Each tool row has one of three states:

Not installed

The command was not found on PATH. Set up is disabled until the tool is installed.

Detected

The tool executable is available but its exact synapse MCP entry is absent or stale. Choose Set up.

Connected

The stored executable and ["mcp"] arguments match the expected Synapse server.

Set up registers the MCP server, creates SOUL.md when needed, and adds a marked pointer to that shared file in the tool's global instructions. For Claude Code it also installs the startup notice described below. Existing settings and text outside the managed block remain in place; changed files receive .synapsebackup siblings. If setup fails, Synapse restores the affected files.

A connected Claude Code row also reports whether it announces Synapse at startup, with an Add or Remove control beside it. Adding it writes two hooks into that tool's own settings: a SessionStart hook, so the connection is stated beside its welcome message before the model has written anything, and a PreCompact hook that asks a long session to write down what it settled before its context is compacted away. It also claims the status line when nothing else has. A status line you configured yourself is never replaced — the row says your status line kept instead. Removing takes back only what Synapse wrote. Either way the change applies to the next session that tool starts, and it never requires disconnecting and reconnecting.

Edit instructions and Edit config open the actual files in the built-in editor. Synapse does not currently provide a separate Disconnect button; remove the named synapse entry and managed instruction block through those files when you intentionally want to disconnect a tool. See Tool integration files for their exact paths.

Memory

The import panel previews Claude and Codex separately. Import safe stores recognized project memory, skips anything credential-shaped, leaves source files untouched, and records a reversible batch. Review source opens the provider folder. Undo requires confirmation and preserves imported records that were edited or linked from another source.

An empty search shows recent memory; a query searches the stored body and shows up to 100 results. Select an entry to inspect its ID, local creation time, full Markdown body, source, and visibility. Global makes it available everywhere; Project requires a project root. Save changes replaces the selected body, source, and scope in place.

Delete changes to Confirm delete before removing one entry. Wipe memories separately changes to Confirm wipe before deleting the entire memory table. A wipe does not affect vault labels, stored values, scope approvals, or settings.

Recall optimization changes responses, not what this screen stores or displays. Read Memory and recall for search behavior, response budgets, and CLI equivalents.

Console

The Mesh screen next door reports; the Console lets you answer. Three columns — a transcript of everything said on the mesh, what the mesh is currently doing, and who is on it — with a box to type in underneath.

Opening it registers you on the roster under your login name, and closing the app takes you off again. That row is what lets a headless worker ask you something: it runs with its permission prompts bypassed, so without a person to address it has had to guess.

Addressing is the same as synapse mux, because it is the same code: @name reaches one agent, #channel a channel, ! everyone, and a bare line goes to whichever agent you picked in the roster. Nothing is interposed — you are a row like any other, and every worker stays directly addressable rather than reachable only through a lead.

The reactor

The dial in the middle column is driven by the mesh: a ring for each message that lands, a band for each agent, and a level that is the share of them working. A still reactor means a quiet mesh rather than a broken window. It can be turned off in Settings, which removes it — the numbers beside it say the same things.

Dictation

A build made with --features voice puts a microphone beside the composer. Push to talk: start, say something, stop, and what you said appears as text you read before sending. Speech is transcribed on your Mac by macOS's own recogniser — no vendor, no key, and nothing billed per minute — and Synapse refuses to transcribe at all rather than fall back to sending your voice to Apple.

Mesh

The Mesh screen is off until you turn it on, here or in Settings. While it is off the screen explains the trade: the coordination tools are loaded by every connected tool, and that costs context in each session.

Once on, it lists the agents that have joined with their role, project, and last reported work state; the background workers running under a Synapse session; and the recent messages between them. Nothing on this screen changes what agents do — it reports. Refresh re-reads the database, which is also what opening the screen does.

See Agent mesh for roles, teams, and the command line.

Skills

The Skills screen lists your library, and beside each skill a badge per connected tool saying whether that tool has it, has an older copy, or has one Synapse did not write. Install on a skill copies it wherever it is missing or behind; Install all does the lot.

Skills a tool already has that the library does not know about appear under Already in your tools with an Adopt button, which copies one into the library and starts managing it. A skill Synapse did not install is never overwritten or deleted from this screen — it is reported instead, and the result line says how many were left alone.

See Skills for the format, the exact folders, and what each state means.

Vaults and scopes

Create a vault, select it, then provide a label, environment name, and value under Add a secret. Save to the vault writes the value straight into the value store while brain.db keeps only its label, environment name, account reference, and scope state. The app never shows a saved value again.

• Project only requires an approved YAML mapping; Global makes that environment name available without a project mapping.
• Copy puts one value on the clipboard. It is the only way a stored value comes back out, and it never passes through the window.
• Replace reads the current Secret value field and overwrites the stored value without changing its reference.
• Forget requires Confirm, then removes the stored value and its metadata.
• Delete vault is available only when the selected vault is empty and requires a second confirmation.

A badge beside the counts names the store this machine keeps values in — Encrypted vault.db or macOS Keychain — and the button next to it moves every value into the other one. That takes two clicks: the first asks, the second migrates. See Where values live for what the two stores protect.

Under Project and folder scopes, choose a directory, create or edit its .synapse.yaml, inspect the reported state, then choose Approve only after reviewing the exact file. Any later edit invalidates that digest and requires another review. Secret values never enter YAML. See Vaults and scopes for resolution order and both process boundaries.

Settings

Shared guidance

Open shared guidance edits SOUL.md. Sync pointers refreshes both global files without removing unmanaged content. Consolidate guidance requires confirmation, moves existing global text into the shared file, and leaves backups before making both global files pointer-only.

Recall optimization

Full, Balanced, and Lean change the shared MCP response limit and character budget. Original memory remains untouched. Balanced is the default; exact limits are documented in Response budgets.

Agent mesh

Off and On switch the coordination tools for every connected tool. Off keeps the tool list at its smallest, which is why it is the default. Tools already running keep the tool list they started with, so the change applies the next time each one starts. The same switch is on the Mesh screen.

Self-improvement

Off and On decide whether connected sessions get teach and revise. Off is the default, for the same reason the mesh is: two more tool definitions cost context in every session that loads them. A skill an agent writes waits on the Skills screen and reaches no tool until you approve it, so leaving this on never changes how a session behaves without you having read what changed it.

Background workers

The most agents one supervisor may run at once. Every worker is a separate session on the account you already pay for, so this is a spending limit as much as a performance one. Whatever you choose is clamped to a ceiling in code, so a mistyped number cannot buy an unbounded fleet, and synapse settings workers <count> takes any value up to it. A supervisor already running picks a change up on its next spawn.

Console reactor

Whether the Console draws the dial in its middle column. Off removes it rather than dimming it; nothing is lost, because the numbers beside it say the same things. A build made without the reactor feature has none to draw, and the panel says so instead of offering a switch that would do nothing.

Dictation

What the microphone can do here, which is four different situations with four different next steps: not in this build, unavailable on this Mac, not yet permitted, allowed, or refused. Only the third has a button — the rest are explanations, because a toggle cannot tell you that macOS has not asked you yet.

Appearance

System follows the current macOS appearance as it changes. Light and Dark pin the app to that mode. The preference is stored locally.

Command line

The status is Installed, Not installed, or Conflict. Install CLI places the managed launcher at the displayed path. Synapse refuses to overwrite an unrelated executable; resolve a Conflict deliberately before trying again.

Shell environments

Command scoped always remains available through synapse run -- <command>. Automatic directory loading is an explicit opt-in for the detected default zsh, bash, or fish shell. Only that detected shell is changed.

Open a new terminal after enabling, repairing, or removing the hook. Existing terminals retain the integration they already loaded. Ambient values are readable by every child of an activated shell; use the command-scoped mode for a sensitive one-off process.

Editors, local data, and recovery

The built-in editor handles SOUL.md, supported tool instructions, TOML or JSON configuration, and YAML scope files. Structured formats must validate before saving. Changed files are backed up and replaced atomically while existing permissions and symlinks are preserved.

If an editor contains unsaved changes, Close and application quit are blocked until you choose Save or Discard. Saving a scope refreshes its state but does not approve it; review the result and choose Approve separately.

Open data folder on the Connections screen reveals the directory containing the local database. It does not create a backup and editing database files by hand is unsupported. Use Data lifecycle for integrity checks, validated exports, exclusive restore, and recovery behavior.