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.
• 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:

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.