synaps 0.12.0

Terminal-native AI agent runtime — parallel orchestration, reactive subagents, MCP, session daemon
Documentation

Install

Linux, macOS and Windows 10/11 (x64).

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/HaseebKhalid1507/SynapsCLI/releases/latest/download/synaps-installer.sh | sh
# or
brew install HaseebKhalid1507/tap/synaps

synaps --version    # check it worked

On Windows:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/HaseebKhalid1507/SynapsCLI/releases/latest/download/synaps-installer.ps1 | iex"

This installs synaps.exe in %USERPROFILE%\.cargo\bin (%CARGO_HOME%\bin if set). On Windows the agent also gets a built-in powershell tool, and the default system prompt tells it to prefer it. Install Git for Windows for the rest: the bash tool uses its Git Bash (or WSL's bash.exe), and ls runs its GNU ls from usr\bin. Without it those tools fail with a message pointing at powershell. grep and find need nothing: they search in-process.

cargo install synaps                        # crates.io, needs Rust 1.88+
yay -S synaps                               # Arch / EndeavourOS

# Debian/Ubuntu: a .deb is attached to every release
# Windows: so is synaps-x86_64-pc-windows-msvc.zip
# https://github.com/HaseebKhalid1507/SynapsCLI/releases/latest

git clone https://github.com/HaseebKhalid1507/SynapsCLI && cd SynapsCLI
cargo build --release && ./target/release/synaps

Quick start

synaps login     # pick a provider: your subscription, an API key, cloud, or local
synaps           # start the TUI

Sign in with what you already pay for, or use no account at all:

synaps login --provider claude      # Claude subscription (also openai-codex, xai-auth, github-copilot)
synaps login --provider kimi        # an API key
ollama serve                        # or a local model: run synaps, then /model local/llama3.2

# Subscription OAuth
synaps login --provider claude
synaps login --provider openai-codex
synaps login --provider xai-auth
synaps login --provider github-copilot
synaps login --provider google-gemini  # requires a Synaps-owned Google Desktop OAuth client registration

# Static API key
synaps login --provider kimi            # Moonshot AI (MOONSHOT_API_KEY / KIMI_API_KEY)

# Cloud identity; credentials stay in the broker
synaps login --provider azure-openai
synaps login --provider aws-bedrock
synaps login --provider google-vertex

Models are provider-qualified: /model <provider>/<model>. Cloud routes (Azure OpenAI, Amazon Bedrock, Google Vertex AI) are text-only for now and say so in model listings; a mode that needs tools fails before any credential is used. Availability depends on each upstream account, region and quota.

Local models: Synaps targets Ollama's default http://localhost:11434/v1. LM Studio, vLLM and llama.cpp work too; point at them with provider.local.url or LOCAL_ENDPOINT. Several accounts per provider: docs/providers/multi-account-broker.md.

What it does

  • Sessions outlive the window. A background daemon owns every session. /sessions lists them, and pinned ones come back after a restart. More
  • Every terminal is you. Attach several clients to one session; any of them can type, steer, or take over.
  • Run a crew. Named subagents work in parallel. Open any one in its own view and steer it mid-flight. More
  • Any model. Claude, Codex, Grok, Copilot, Gemini, Kimi, Meta Muse, Azure, Bedrock, Vertex, any OpenAI-compatible endpoint, or Ollama.
  • Credentials stay in the broker. Agents get short-lived, scoped tokens, never your keys. Several accounts per provider. More
  • Bounded turns, when you want them. Optional caps on rounds, tool calls, time, tokens and cost.
  • Long sessions stay cheap. The prompt cache lasts an hour on a Claude subscription, large tool output waits on disk behind a short preview, re-reads of unchanged files are deduplicated, and workers roll their context over instead of filling the window.
  • Memory that survives. Project memory, /compact checkpoints, sessions that chain across days.
  • Sees what you see. The model reads images, and /attach adds images, PDFs and text to a turn. More
  • Build on it. Extensions in any language, MCP servers, and the engine over JSON-RPC or the daemon socket.

Benchmarks

Memory is total PSS (plus swapped-out pages) across each tool's whole process tree, background servers included, with idle TUI sessions. Measured 2026-10-26 on one machine (24 cores, 30 GB, Linux), median of 3. Synaps shares one daemon across sessions, so each extra session is a thin client.

Memory 1 session 10 sessions per extra session
synaps 0.11.0 (core) 42 MB 79 MB ~4.1 MB
jcode v0.91.0 117 MB 165 MB ~5.3 MB
pi 0.85.1 117 MB 708 MB ~66 MB
claude code 2.1.304 186 MB 894 MB ~79 MB
codex 0.163.0 † 274 MB 525 MB ~28 MB
opencode 2.1.1 387 MB 1197 MB ~90 MB

† codex never drew a frame the harness recognises within its 10 s timeout, so it was sampled at the timeout and may not have finished starting.

Prompt cache, from real use: 97.9% of prompt tokens came from cache across 127,453 requests since v0.8.0, every release between 97.1% and 98.4%. That's 89.6% cheaper than the same tokens at list price without caching. Full report

weekly prompt-cache hit rate

Terminal-Bench 4.1, with Claude Opus 5.5: 39 of 63 tasks (61.9%), one trial per task. The public TB 4.0 Claude Code entry labeled Opus 5.5 would be expected to pass 40.0 of those task names, but some of its traces switch models. Synaps's median task time was 23 minutes versus the board's 55-minute median of per-task means. This is not a controlled ranking: benchmark revisions, effort, host conditions, model lineage, and trial counts differ. Full results · 24 failure case studies · whole-run audit and regression-controlled improvement plan

Method, tool versions, latency numbers, caveats and how to reproduce: BENCHMARKS.md.

Why Synaps

  • Agents are programs, not chat. They happen to use language models. Run them like services.
  • Own your agent. The system prompt is a file on disk, the tool list is opt-out, and nothing phones home.
  • Multi-agent is the default. Single-agent is just n=1.
  • Speed is a feature. A 2-second boot loses the dev who wanted it in a git hook.
  • The terminal is the IDE. Built for people who already live there.

Not for you if:

  • you want an IDE plugin or a desktop app. Synaps is terminal-first.
  • you need a sandbox. Tools run as you; see Security.
  • you want a settled tool. Synaps is young and moves fast; read the upgrade notes before upgrading.

Commands

Command What it does
synaps The TUI, a thin client on the shared daemon (started on first launch)
synaps attach A line client attached to a daemon session
synaps daemon status, sessions, pin, rename, close, stop, reload (swap the binary, sessions intact), reload-extension
synaps send Send a message to a running session from a script
synaps chat The same engine on stdin/stdout, for pipes, scripts and CI
synaps rpc JSON-RPC over stdio, to embed the engine in other software
synaps login · auth · status Sign in, manage several accounts per provider, see usage and reset windows

Configuration

One file, key = value, at ~/.synaps-cli/config:

model = anthropic/claude-opus-5
thinking = high
theme = tokyo-night
identity = You are a senior engineer who writes clean, tested code.
disabled_tools = bash, ls          # remove built-ins at boot (read-only profiles)

Every key, the multi-machine auth broker and more are in the Wiki.

Extensions

Drop a folder in ~/.synaps-cli/plugins/ and it's live on next boot:

~/.synaps-cli/plugins/my-guard/
├── .synaps-plugin/plugin.json    # manifest: hooks, permissions, keybinds
└── main.py | index.js | <any>    # JSON-RPC 2.0 over stdio, any language

Each extension is its own crash-isolated process, with a permissions manifest that gates what it can touch, and hooks from before_tool_call to on_session_end. Restart one without touching your sessions: synaps daemon reload-extension <name>. Protocol and tutorial: docs/extensions/.

Themes

21 built-in themes, including catppuccin, gruvbox, nord, tokyo-night, originals like neon-rain and night-city, and a light one, paper. Switch live with /theme, or try one for a single run with SYNAPS_THEME=<name>.

Security

  • Credentials live in a broker. Agents get short-lived, scoped tokens, so a compromised agent can't leak what it never held. Thin clients strip secrets from your shell's environment before connecting.
  • Extensions are fenced. Each runs as its own process under a permissions manifest, and a tool-call confirm names the extension that asked (details).
  • The daemon is yours alone. Its socket (a named pipe on Windows) is owner-only and refuses other users.
  • Not a sandbox. Tools run as you. Building with --no-default-features compiles out bash and the shell_* tools, but an agent can still start processes indirectly: by editing shell rc files or MCP config, or through extensions. Use a container or VM for untrusted work.

Found a vulnerability? Report it privately: SECURITY.md.

Docs and help

Contributing

Synaps is young and moving fast. Good first contributions: a new provider, an extension, a theme, docs, or any good first issue.

git clone https://github.com/HaseebKhalid1507/SynapsCLI && cd SynapsCLI
cargo build && cargo test

Read CONTRIBUTING.md and ARCHITECTURE.md first. Issues and PRs are welcome, and the maintainer answers fast. Come hang out in the Discord: questions, ideas, show-and-tell, or just to watch the crew run.

License

Apache 2.0. See LICENSE.