Synapse

The open-source coding agent that lives in your terminal — built on LangChain Deep Agents. Ask it to fix a test, refactor a module, or carry a goal across turns until it is done.

English · 简体中文 · Docs · Changelog

Synapse is a terminal-first coding-agent runtime. Unlike a one-shot "run this and reply" prompt, it is designed for sessions that last more than a few turns: a responsive TUI that keeps the timeline, tool calls, and context usage visible; token-aware handling of tool output; and persistent goals that keep the agent working until the work is actually done.

Install

One command, no clone required:

uv tool install synapse-cli-agent

Then start the TUI from anywhere:

synapse tui -w .

Open a session in any registered project from the global catalog:

synapse --session <project_id>:<thread_id>   # global session reference
synapse --project <ref>                      # project by id prefix, name, or path

Inside the TUI, click the topbar ≡ (or the workspace label) to open the floating project drawer: it lists every registered project, groups their sessions, marks live runtime status, and lets you switch sessions in place or jump to another project (the TUI restarts into that project).

Press Ctrl+Tab for a global recent-sessions switcher: it lists the most recently changed sessions across every registered project (from the user-layer catalog), marks each one's live runtime status — running / queued / idle / cold, etc. — lets you Tab / Shift+Tab through them and Enter to switch. The old session keeps running in the background and is never cancelled. Some terminals never forward Ctrl+Tab to the app; Ctrl+O is a drop-in alternative.

git clone https://github.com/alex8224/synapse-agent.git
cd synapse-agent
uv sync

# Windows venv entry
.\.venv\Scripts\synapse.exe tui -w .

# Or module entry
uv run python -m synapse tui -w .

Use it

Type it like you would ask a colleague:

• "Fix the failing test in tests/test_backends.py"
• "Refactor this module and add type annotations"
• "Review the latest commit and suggest improvements"
• "Keep working on this goal until it is done" (via /goal)

Three ways to talk to it:

Why it is built for long sessions

• Long-running goals — /goal <objective> survives turn boundaries, tracks tokens and elapsed time, and steers the next turn automatically until the goal is completed, paused, blocked, or budget-limited.
• Token-aware tool output — search results, logs, diffs, JSON, and code are classified and compressed before they re-enter the model context; large originals stay recoverable through references.
• Managed long context — automatic summarization and /compact keep sessions inside the model window, with occupancy and savings visible in the TUI.
• Direct Codex OAuth — sign in with the Codex-compatible browser flow or import an existing Codex grant. No API key required; tokens refresh automatically.
• Your model, your choice — OpenAI-compatible providers via models.json profiles (OpenAI, DeepSeek, local gateways, and more), including a persistent WebSocket mode.
• MCP built in — attach MCP servers and their tools appear in the agent automatically.
• Sessions that resume — SQLite checkpoints, a global project catalog across all your projects, and a lightweight paged transcript so even huge sessions reopen fast.
• Memory and skills — AGENTS.md memory plus Agent Skills (skills/**) that load only when relevant.
• Sub-agents — built-in researcher, tester, and reviewer roles for parallel delegation, plus user-defined subagents from .synapse/agents/*.md.
• Approvals when you want them — optional human-in-the-loop (--require-approval) and safety profiles.

Slash commands

Type /help in the TUI for the full reference. The essentials:

ACP v1 adapter

The package also installs the standalone synapse-acp stdio entry point. It uses the locked agent-client-protocol==0.12.0 dependency and keeps stdout reserved for ACP JSON-RPC; diagnostics go to stderr.

# Run from an installed package
synapse-acp

# Run from a source checkout
uv run synapse-acp

For a client such as Zed, configure the ACP agent as a subprocess whose command is synapse-acp (or the absolute path to that executable). The adapter accepts absolute cwd values and session-scoped MCP servers. MCP credentials are used only for the live session and are not written to the ACP catalog or transcript.

The published capability set currently covers text prompts, image prompts, permission/HITL, session load/list/close/delete/resume, session-local mode/config, HTTP/SSE MCP configuration, model selection via providers/list/providers/set, and capability-gated Client filesystem/ terminal tools. Thinking level maps directly to Synapse levels (off, minimal, low, medium, high, max). Audio, embedded-context, authentication/logout, elicitation, NES, and document-sync capabilities are not advertised until their runtime semantics and interoperability tests exist.

Troubleshooting:

• stdout is reserved for ACP JSON-RPC; any log line on stdout breaks the protocol. Logs and startup traces go to stderr.
• cwd and additionalDirectories must be absolute paths; relative paths are rejected with an ACP error.
• Session metadata lives in ~/.synapse/acp-sessions.sqlite; MCP credentials and headers are never persisted there.
• If a client reports "Method not found", verify it negotiates the same ACP protocol version and does not rely on not_target methods (auth, providers, elicitation, NES, document sync).

Pick a model

Synapse works with any OpenAI-compatible endpoint. Configure profiles in ~/.synapse/models.json (or <workspace>/.synapse/models.json):

{
  "default": "deepseek",
  "models": {
    "deepseek": {
      "model": "openai:deepseek-v4-pro",
      "api_key": "sk-...",
      "base_url": "http://127.0.0.1:3000/v1",
      "thinking": "high"
    }
  }
}

For a zero-config Codex experience, use the OAuth profile — see Models.

Documentation

Repository layout

src/synapse/    Agent assembly, commands, runtime, sessions, TUI, integrations
rust/           Optional native compression cores (PyO3)
docs/           User documentation
tests/          Python test suite
scripts/        Install / release helpers

License

Apache License 2.0 — see LICENSE. Third-party dependencies and Rust subcomponents may carry their own licenses; retain the corresponding license and NOTICE files when distributing.