Configuration and paths
Find every Synapse-owned path, understand environment overrides, and know how integration and editor writes are protected.Resolved paths
synapse path| Item | Default on macOS |
|---|---|
| Home | ~ |
| Data directory | ~/Library/Application Support/synapse |
| Database | ~/Library/Application Support/synapse/brain.db |
| Shared guidance | ~/Library/Application Support/synapse/SOUL.md |
| Skill library | ~/Library/Application Support/synapse/skills/ |
| Mesh roles and teams | ~/Library/Application Support/synapse/roles/, teams/ |
| Worker logs | ~/Library/Application Support/synapse/workers/ |
| Database backups | ~/Library/Application Support/synapse/backups/ |
| Installed CLI | ~/.local/bin/synapse |
Everything above lives under one folder. A project may also hold .synapse.yaml scope files and a .synapse/roles/ directory, both of which travel with the checkout rather than with you.
Environment variables
| Name | Effect | Typical use |
|---|---|---|
SYNAPSE_DATA | Replaces the application-data directory. | Development, tests, or a deliberately isolated database. |
SYNAPSE_HOME | Replaces the home directory used for tool files and the default CLI path. | Integration testing without touching real user files. |
SYNAPSE_BIN | Replaces the full CLI installation destination. | Install outside ~/.local/bin. |
SYNAPSE_PROJECT_DIR | Provides the fallback project folder for MCP calls that do not carry one, and is what a launched agent is told to treat as home. | A client that launches the server outside the project working directory. Set automatically by synapse launch and relay launch. |
SYNAPSE_PAGE | Chooses which dashboard page opens first: memory, mesh, console, skills, vaults, or settings. Anything else opens Connections. | Opening the app straight to the screen you want. |
CODEX_HOME | Replaces the Codex home directory used for detection and for reading an existing Codex memory store. | A non-default Codex installation, or testing an import without touching real files. |
PI_CODING_AGENT_DIR | pi's own variable for its agent directory, which Synapse reads for the same reason: detection, the instruction pointer, and the skills folder. | A non-default pi installation. |
SYNAPSE_PI_PACKAGE | Replaces the package a connection to pi installs, and the source detection compares against. Defaults to npm:synapse-pi. | Working on the package from a checkout instead of npm. |
SYNAPSE_COMMAND | The Synapse executable a launched pi session should talk to. | Set automatically by synapse launch pi so a session reaches the binary that started it. |
SYNAPSE_SHELL_ACTIVE | Identifies the shell hook currently evaluated in this shell. | Set automatically by the zsh, bash, or fish integration so status can report it. |
SYNAPSE_SHELL_KEYS | Records which managed variables the hook currently has loaded, so leaving a scope unloads exactly those and restores what was there before. | Set automatically by the shell hook. Not intended to be set by hand. |
SYNAPSE_SHELL_COMMAND | The executable the installed shell block re-invokes on each directory change. | Set automatically by the startup-file block so a moved app is still reachable. |
SYNAPSE_DOCUMENT | Launches the desktop app directly into a Markdown, TOML, JSON, or YAML document. | Internal editor entrypoint. |
SYNAPSE_DATA="$HOME/tmp/synapsedemo" synapse data check
SYNAPSE_BIN="$HOME/bin/synapse" synapse installOverrides affect only the process that receives them. Keep the desktop app, CLI, and connected MCP server on the same SYNAPSE_DATA value if they should share one store.
Tool integration files
| Tool | Integration | Instructions | Settings shortcut |
|---|---|---|---|
| Codex | ~/.codex/config.toml | ~/.codex/AGENTS.md | ~/.codex/config.toml |
| Claude Code | ~/.claude.json | ~/.claude/CLAUDE.md | ~/.claude/settings.json |
| pi | ~/.pi/agent/settings.json | ~/.pi/agent/APPEND_SYSTEM.md | ~/.pi/agent/settings.json |
Connection detection parses the actual TOML or JSON entry named synapse. It reports connected only when the stored command resolves to the expected executable and the arguments equal ["mcp"]. A deleted development binary therefore appears stale instead of healthy.
pi is the exception, because its connection is a package rather than a server command: detection reads pi's packages list and reports connected when the Synapse package is there. The extension in that package starts the same synapse mcp server and finds the executable itself, so there is no stored path to go stale.
Each instruction file contains a managed pointer to the central SOUL.md. A normal sync preserves other text in place. The optional consolidation action first moves that text into SOUL.md, then leaves the global files pointer-only so shared guidance has one editable source.
Connecting Claude Code also writes two entries into ~/.claude/settings.json: a SessionStart hook running synapse session, and a statusLine running synapse statusline. JSON has no comment syntax, so Synapse cannot mark its own entries the way it marks a block in a Markdown file. It recognizes them by the command they run instead, and carries everything else through untouched — a status line you configured yourself is reported and left alone, never replaced.
| Entry | Command | What it produces |
|---|---|---|
hooks.SessionStart | synapse session | The connection line in your terminal, and this project's memory in the session's context before the first turn. See Session start. |
statusLine | synapse statusline | One line under the prompt for the rest of the session: model, folder, memory count, and mesh size. |
Both are removed by synapse disconnect claude. Codex exposes neither, so a Codex connection is the MCP entry and the instruction pointer only. pi has no settings entries of this kind either — its notice and status line come from the extension in its package rather than from a hook it has to be configured with.
Safe writes
The built-in document views validate JSON, TOML, and YAML before saving. A write with changed content:
- Resolves a dotfile symlink and writes through it rather than replacing the link.
- Writes the previous bytes to a sibling file ending in
.synapsebackup. - Writes the replacement to a temporary file, syncs it, preserves existing permissions, then renames it atomically.
- Syncs the containing directory.
Tool setup snapshots its integration file, instruction file, and shared guidance file. If registration or the instruction update fails, it restores every prior state. The CLI installer applies the same rollback model to its launcher and receipt.
Settings and shell integration
synapse settings show
synapse settings optimize full
synapse settings optimize balanced
synapse settings optimize lean
# Manual alternative to Settings → Enable shell hook.
eval "$(synapse hook zsh)"
synapse allow
synapse denyThe optimization value lives in SQLite, so the app, CLI, and every connected MCP process read the same setting. Balanced is the default. See Memory and recall for exact limits and transformations.
The Settings screen detects the default shell and can enable, repair, or remove its managed startup-file block. Existing files are backed up and replaced atomically. The hook is an explicit per-shell opt-in: it activates only inside a directory with at least one discovered, approved scope. Leaving the scope, revoking approval, or changing the YAML unloads managed values and restores values that existed before activation. See Choose an environment boundary before enabling ambient mode.