Local-first AST code context for AI agents — without uploading source code to external services.
- Use Python >=3.12.
- Install Synapse as a managed CLI tool:
uv tool install locker-room-tools-synapse-mcp. - Connect it globally to your agent:
synapse install codex - Restart the agent once.
Replace codex with claude-code or opencode. No repository files are created. On the first
code-navigation request, the global instruction calls synapse_ensure_workspace, which
initializes the local index and daemon automatically.
See Installation and lifecycle for upgrades, custom scopes, troubleshooting, and uninstall instructions. See MCP tools for tool contracts and recommended agent flows.
Create a virtual environment and install the repository with development dependencies:
uv venv && uv pip install -e ".[dev]". Then run synapse grammars install once.
Grammar installation is an explicit network operation. Indexing, watching, querying, and MCP serving only use the local grammar cache and never download parsers implicitly.
Synapse exposes 17 deterministic MCP tools for initialization, symbol lookup, definitions, references, structural context, dependency navigation, project maps, indexing, and daemon health. The complete parameter and response reference is in docs/tools.md.
Synapse reads configuration from three layers, unioned together:
| Layer | Location | Written by |
|---|---|---|
| built-in defaults | packaged with Synapse | not editable |
| global user config | ~/.config/synapse/config.json |
synapse config ignored-dirs ... --scope global |
| project config | <workspace>/.synapse/config.json |
agents over MCP, or synapse config ignored-dirs ... |
ignored_directories accepts a bare name matched at any depth (node_modules), a
root-anchored name (/build), or a workspace-relative path (src/generated). Globs,
absolute paths, and .. segments are rejected.
Agents configure Synapse through synapse_get_config, synapse_add_ignored_directories, and
synapse_remove_ignored_directories, which always write the project layer. .synapse/config.json
is meant to be committed so the whole team indexes the same tree.
A change needs no reindex: the next watch sweep purges newly-ignored files and picks up restored ones.
Synapse requires a healthy dependency-free polling daemon before query tools can read an
index. synapse_ensure_workspace starts or repairs it lazily, and the MCP entry point restores
it for initialized workspaces after a reboot. Logs are written under the workspace data
directory at logs/watch.log, and status is written to watch.json in the same data directory.
Use synapse watch status --workspace . --json to inspect running, backend, pending, PID,
timestamps, errors, and staleness_seconds. Stop a detached daemon with
synapse watch stop --workspace .. For a bounded smoke check that performs one reconciliation
sweep and exits, run synapse watch start --workspace . --foreground --once.
The shipped backend is currently polling-only. Its interval defaults to the user config
watch.poll_interval_s; native OS event watching is intentionally deferred behind the core
WatchBackend protocol.
synapse install <claude-code|codex|opencode> [--dry-run] [--offline] [--no-skill]synapse init --path <path> [--dry-run] [--offline]synapse status --path <path> [--json]synapse uninstall <client> --globalsynapse setup <client> --path <path>for advanced project-scoped integrationsynapse mcp install <client> --workspace <path> [--scope project|user] [--print]synapse uninstall <client> --path <path> [--scope project|user]synapse doctor --path <path> [--agent <client>] [--scope project|user]
Project setup, mcp install, manual indexing, serve, and foreground watch mode remain
available for advanced integration and diagnostics.
Read docs/architecture.md before changing the project structure.