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 eight 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.

Map

Every other screen is a list, and a list answers what is stored rather than what it is about. The Map draws the store as a graph: one circle per memory, one larger circle per project, and lines between them. Projects come out as clusters, a correction comes out as a line to the thing it corrected, and a memory nothing else touches comes out looking like one — usually either the most interesting memory on the map or the one that should not be there.

A point is sized by how much is tied to it and coloured by the project it belongs to. Click one to read that memory beside the map, with its scope, source, and date. A hollow point is a superseded memory: out of recall, still in the store, still restorable.

The map is laid out in three dimensions, and the window lets you move around inside it:

A plane is the wrong shape for a graph: a cluster with more neighbours than the plane has room for either overlaps itself or pushes everything else off the map, and both of those are the picture lying about the store. Turning it re-draws, never re-lays-out, so the shape you learned stays the shape it is.

The plot is dark whatever theme you use. A glow is light added to what is behind it, and on a light background there is nothing to add to; the rest of the window stays in your theme.

Three kinds of line, and only one of them is inferred:

A memory and its project

Recorded. Every memory hangs off the project it was stored for, or off global memory.

A memory and the one that replaced it

Recorded, and drawn in red. This is what supersession looks like from above.

Two memories using the same uncommon words

Inferred, and drawn faintest. It uses the same word list recall uses, so a search and a map cannot disagree about which words mean nothing. It is a resemblance, never a claim that two memories say the same thing.

The map is bounded on purpose: it draws the newest 160 memories and says so whenever the store is larger. The layout is the same every time you open it, because a map is worth having when you have learned its shape.

Connections

The Connections screen reports memory count, database size, and how many supported tools are connected. It draws two lists: Connected, the tools wired in right now, above Supported, everything else Synapse can connect on this machine. A tool appears in one or the other, never both, and moves between them as you connect and disconnect it.

Each tool row has one of four 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.

Update available

Connected, and this release would connect it differently — its descriptor changed after the connection was made. Nothing is broken; there is a newer answer to apply. Choose Update.

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.

Keeping a connection current

A connected row carries three controls, in increasing order of what they cost you:

Update

Applies this release's descriptor to a tool that is already connected. The registration is written again rather than skipped, because detection cannot tell a descriptor that moved from one that did not — it only knows an entry is present and points at Synapse. Nothing is removed, your skills stay installed, and the tool is connected throughout. This is what the Update available badge is asking for.

Reset

Disconnects the tool and connects it again. The bigger hammer, and the one that costs something: disconnecting removes the skills Synapse installed for that tool, and a reset puts the connection back rather than the library. Reach for Update first; use Reset when what is on disk has to go before the new answer can land.

Remove

Disconnects and leaves it that way: the MCP registration, the managed instruction block, the Claude Code hooks and status line, and any skill Synapse installed for it. A skill you wrote, your own words in an instruction file, and a status line somebody else configured all stay where they are. The row moves down to Supported.

Synapse knows a descriptor moved because it records which one a connection was made from. A tool connected before this release has no such record, and reads as current rather than out of date — not knowing is not the same as knowing something is stale.

Edit instructions and Edit config open the actual files in the built-in editor. 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.

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.

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.