# SynapsCLI > A terminal-native AI agent runtime built in Rust. Interactive chat, parallel agent orchestration, and autonomous supervision โ€” one binary, 70K lines, 1,074 tests. - **Type:** MCP server - **Install:** `agentstack add mcp-haseebkhalid1507-synapscli` - **Verified:** Pending review - **Seller:** [HaseebKhalid1507](https://agentstack.voostack.com/s/haseebkhalid1507) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [HaseebKhalid1507](https://github.com/HaseebKhalid1507) - **Source:** https://github.com/HaseebKhalid1507/SynapsCLI ## Install ```sh agentstack add mcp-haseebkhalid1507-synapscli ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About The agent runtime that boots before your Node binary finishes importing. One Rust binary. Any model. Any provider. ๐Ÿ“– Read the Wiki ยท โšก Quick Start ยท โ“ FAQ --- --- ## Install ```bash cargo install synaps # crates.io ``` More options ```bash brew install HaseebKhalid1507/tap/synaps # macOS / Linux yay -S synaps # Arch / EndeavourOS ``` ```bash # Debian/Ubuntu curl -LO https://github.com/HaseebKhalid1507/SynapsCLI/releases/latest/download/synaps_amd64.deb sudo dpkg -i synaps_amd64.deb ``` ```bash # Shell installer (any platform) curl -sSL https://github.com/HaseebKhalid1507/SynapsCLI/releases/latest/download/synaps-installer.sh | sh ``` ```bash # From source git clone https://github.com/HaseebKhalid1507/SynapsCLI && cd SynapsCLI cargo build --release && ./target/release/synaps ``` ## Go ```bash synaps login # OAuth with Claude Pro/Max synaps # launch ``` Or skip OAuth โ€” any API key works: ```bash export ANTHROPIC_API_KEY="sk-ant-..." # or GROQ_API_KEY, CEREBRAS_API_KEY, etc. synaps ``` 17 providers. 55+ models. Set a key, pick a model, go. --- ## What It Looks Like ``` โ•ญ โ—ˆ 4 agents โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ โœ“ spike done 12.3s โ”‚ โ”‚ โ น chrollo โš™ read (tool #5) 8.1s โ”‚ โ”‚ โœ“ shady done 9.7s โ”‚ โ”‚ โ น zero thinking... 4.2s โ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ ``` You dispatch agents. They work in parallel. You watch them think. --- ## The Pitch Most CLI agents are single-threaded conversations with a language model. Synaps is a **harness** โ€” a place where multiple named agents live, collaborate, and persist across sessions. Think of it like LEGO: the **brain** is one piece (talks to AI models), the **tools** are blocks (read files, run commands, search), and **plugins** are stickers you snap on โ€” voice, security, memory, whatever you need. Swap the AI behind it at any time. The cool part isn't *which AI you have* โ€” it's *how cleverly you put your agents together*. ```bash # Dispatch a named agent with its own personality and tools subagent(agent: "spike", task: "refactor the auth module") # Or dispatch reactively โ€” don't wait, steer mid-flight subagent_start(agent: "chrollo", task: "audit this codebase for vulnerabilities") subagent_steer(handle_id: "sa_1", message: "focus on the API routes") subagent_collect(handle_id: "sa_1") ``` The big agent dispatches little helper agents โ€” like a chef with sous-chefs. You can poke them mid-task, redirect them, or let them run. And there's a **watcher** that supervises the fleet so they don't crash or burn through your budget. ``` ๐Ÿค– Main Agent โ”‚ "you chop, you stir, you watch the oven" โ”Œโ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ” ๐Ÿค– ๐Ÿค– ๐Ÿค– ๐Ÿค– spike shady chrollo zero ``` Agents aren't anonymous forks. They're crew members with names, system prompts, specializations, and memory. You build a team, not a chatbot. *New to AI agents? Read the [ELI5](ELI5.md). Want the full tour? Check the **[Wiki](https://github.com/HaseebKhalid1507/SynapsCLI/wiki)**.* --- ## Features **โšก Fast.** ~81K lines of Rust across a 3-crate workspace. Sub-100ms cold start. Single binary, no runtime dependencies. **๐ŸŒ Any model.** Claude, GPT-4, Gemini, Llama, Qwen, Mistral, DeepSeek โ€” 17 providers including free tiers (Groq, Cerebras, NVIDIA NIM). Swap mid-session with `/model`. **๐ŸŽญ Named agents.** `spike`, `chrollo`, `shady`, `zero` โ€” each with a soul. Dispatch by name, watch them work in the live panel. **๐Ÿ”„ Reactive orchestration.** Dispatch โ†’ poll โ†’ steer โ†’ collect. Five tools that turn fire-and-forget into collaborative multi-agent workflows. **๐Ÿ“ก Event bus.** Push events into a running session from any script, cron, or service. The agent reacts in real time. **๐Ÿ”Œ Extensions.** JSON-RPC 2.0 over stdio. Hook into `before_tool_call`, `after_tool_call`, `before_message`, `on_message_complete`, `on_compaction`, `on_session_start`, `on_session_end`. Build guardrails, inject context, modify tool calls. **๐Ÿง  Context that lasts.** 90%+ prompt cache hit rate. `/compact` replaces history with a structured checkpoint. Chain sessions across days. **๐Ÿค– Autonomous mode.** `synaps watcher` supervises long-running agents with heartbeats, crash recovery, cost limits, and session handoff. **๐ŸŽจ 17 themes.** From `neon-rain` to `tokyo-night`. Hot-swap with `/theme`. --- ## Modes | Command | What it does | |---------|-------------| | `synaps` | Interactive TUI โ€” streaming, markdown, syntax highlighting, subagent panel | | `synaps chat` | Headless โ€” same engine, stdin/stdout. For scripts, pipes, CI | | `synaps server` | WebSocket API with token auth, origin validation, streaming | | `synaps rpc` | Line-JSON IPC โ€” one process per thread, for bridges (Slack, Discord) | | `synaps watcher` | Supervisor daemon for autonomous agent fleets | --- ## Tools 18 built-in, zero config: | | | | |---|---|---| | `bash` | `read` / `write` / `edit` | `grep` / `find` / `ls` | | `subagent` / `subagent_resume` | `subagent_start` / `_status` / `_steer` / `_collect` | `shell_start` / `_send` / `_end` | | `connect_mcp_server` | `load_skill` | | Plus anything from MCP servers. `connect_mcp_server` and they're live. Need a locked-down agent? Disable any built-in by name in your config: `disabled_tools = bash, ls` removes them from the registry at boot, so the model never sees them (handy for read-only or no-shell profiles). --- ## Configuration ``` ~/.synaps-cli/config ``` ```ini model = claude-sonnet-4-6 thinking = high theme = neon-rain context_window = 200k identity = You are a senior engineer who writes clean, tested code. cache_ttl = hybrid # prompt-cache TTL: 5m (default) | 1h | hybrid max_fps = 60 # TUI redraw cap during streaming: 60 (default) | 144 | 240 | โ€ฆ disabled_tools = bash, ls # built-in tools to remove from the registry at boot provider.groq = gsk_... provider.cerebras = csk-... keybind.F5 = /compact ``` That's it. No YAML. No TOML. No JSON. Key = value. Done. ### Bridge mirror (optional) When the bridge daemon (synaps-skills) is running locally, the watcher can mirror per-agent heartbeats over its UDS `ControlSocket` (`heartbeat_emit` op). Off by default. Enable with: ```ini bridge.heartbeat_mirror = true # bridge.uds_path = /custom/path/control.sock # default: ~/.synaps-cli/bridge/control.sock # bridge.heartbeat_timeout_ms = 250 # connect+write+read budget ``` Mirroring is best-effort โ€” the watcher never blocks or fails an agent if the bridge UDS is missing. See [`docs/smoke/watcher-bridge.md`](docs/smoke/watcher-bridge.md) for the verification playbook. ### Shared credentials via a broker (`auth.*`) By default each machine reads and refreshes its own `~/.synaps-cli/auth.json` (`auth.remote_endpoint` unset). To share ONE OAuth credential across many machines without copying it to each disk, run a broker on one trusted host and point the others at it. Anthropic **and** OpenAI/codex tokens both route through the broker. ```ini # on a CLIENT machine โ€” fetch short-lived access tokens from the broker auth.remote_endpoint = https://broker-host:8181 auth.machine_token = # env overrides (win over config): SYNAPS_AUTH_ENDPOINT / SYNAPS_MACHINE_TOKEN ``` ```bash # on the BROKER host โ€” holds the credential, refreshes centrally, serves tokens synaps auth-broker --bind 0.0.0.0:8181 --machine-token-file /etc/synaps/broker.token # GET /healthz -> { status } (non-200 if cred missing) # GET /token?provider=X -> { access_token, expires, ttl_ms } (Bearer machine token) ``` A Remote client **never stores the credential**: it holds only short-lived access tokens in memory, never a refresh token, and never writes `auth.json`. The broker is the single refresher (Anthropic rotates the refresh token on every refresh, so exactly one party may refresh). **Token config (note the three env vars):** | Role | config key | env var | |---|---|---| | client โ†’ broker URL | `auth.remote_endpoint` | `SYNAPS_AUTH_ENDPOINT` | | client โ†’ its identity to the broker | `auth.machine_token` | `SYNAPS_MACHINE_TOKEN` | | broker โ†’ secret it requires of clients | `--machine-token` / `--machine-token-file` | `SYNAPS_BROKER_TOKEN` | Prefer `--machine-token-file` over `--machine-token` so the secret isn't exposed in `argv`/`ps`. **Security model โ€” read before exposing it:** - The broker constant-time-compares the machine token, allowlists providers, rate-limits in-flight requests, and refuses to start unauthenticated on a non-loopback bind (override with `--insecure-no-auth`, don't). - **TLS is terminated externally** โ€” the broker speaks plain HTTP to stay a lean single static binary. Run it **behind WireGuard** (private overlay) **or front it with a TLS-terminating reverse proxy / load balancer / service mesh.** A bare non-loopback HTTP bind ships your machine token and access tokens in cleartext โ€” a DNS-spoof/MITM then harvests them. Example with Caddy: ``` # Caddyfile โ€” terminates TLS, proxies to the loopback broker broker.internal { reverse_proxy 127.0.0.1:8181 } ``` Then run `synaps auth-broker --bind 127.0.0.1:8181 ...` and point clients at `https://broker.internal`. (systemd unit: `deploy/synaps-auth-broker.service`.) > **โš  Terms of Service.** This is for sharing ONE account's credential across > **your own** machines (a personal homelab / your own fleet). Sharing a Claude > Pro/Max or ChatGPT **subscription seat** across multiple distinct users โ€” or > fanning one seat out across a large machine fleet โ€” likely violates Anthropic's > / OpenAI's Terms and risks **account suspension**. At real scale use **org/ > enterprise API keys**, not subscription-seat OAuth. Check the current ToS > before deploying beyond your own boxes. --- ## Extensions & Plugins Plugins are like stickers you snap onto your agent โ€” want code guardrails? Stick on a security plugin. Want memory? Stick on a memory plugin. Drop a folder in `~/.synaps-cli/plugins/` and it's live on next boot. Extensions hook into the agent loop via 7 lifecycle events. They can block tool calls, inject context, modify inputs, or just observe. Permission-gated. Sandboxed processes. ``` ~/.synaps-cli/plugins/my-guard/ โ”œโ”€โ”€ .synaps-plugin/ โ”‚ โ””โ”€โ”€ plugin.json # manifest: hooks, permissions, keybinds โ””โ”€โ”€ index.js # JSON-RPC 2.0 over stdio ``` And anything in the world can poke your agent โ€” monitoring systems, cron jobs, CI pipelines. `synaps send "the website is down" --source uptime-kuma` and your agent wakes up and handles it. See [docs/extensions/](docs/extensions/) for the protocol spec, or the **[Wiki](https://github.com/HaseebKhalid1507/SynapsCLI/wiki)** for the full documentation โ€” 36 pages covering everything from installation to multi-agent orchestration. --- ## Philosophy Synaps has opinions: - **Agents are not chat.** They're autonomous programs that happen to use language models. Treat them like services, not conversations. - **Speed is a feature.** If your agent runtime takes 2 seconds to boot, you've already lost the developer who wanted to use it in a git hook. - **Multi-agent is the default.** Single-agent is a special case of multi-agent with n=1. The architecture should reflect that. - **The terminal is the IDE.** If you need Electron to be productive, your tools are wrong. --- Architecture ``` src/ โ”œโ”€โ”€ main.rs # CLI dispatch โ”œโ”€โ”€ engine/ # shared boot, commands, stream, session โ”œโ”€โ”€ runtime/ # LLM API + provider router (Anthropic native + OpenAI-compat) โ”œโ”€โ”€ tui/ # terminal UI, themes, settings, plugin modals โ”œโ”€โ”€ tools/ # 18 built-in tools โ”œโ”€โ”€ extensions/ # JSON-RPC extension system โ”œโ”€โ”€ events/ # event bus + priority queue โ”œโ”€โ”€ mcp/ # Model Context Protocol client โ”œโ”€โ”€ watcher/ # autonomous agent supervisor โ”œโ”€โ”€ skills/ # markdown-driven behavioral guidelines โ”œโ”€โ”€ memory/ # local plugin memory store โ””โ”€โ”€ sidecar/ # long-running plugin companion processes ``` Two API paths: Anthropic (native) and OpenAI-compatible (17 providers). Both emit the same `StreamEvent` โ€” the TUI and tool loop are provider-blind. --- ## License Apache 2.0. See [LICENSE](LICENSE). --- Because every other CLI agent was a 400MB Electron app pretending to be a terminal tool. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [HaseebKhalid1507](https://github.com/HaseebKhalid1507) - **Source:** [HaseebKhalid1507/SynapsCLI](https://github.com/HaseebKhalid1507/SynapsCLI) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: flagged โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-haseebkhalid1507-synapscli - Seller: https://agentstack.voostack.com/s/haseebkhalid1507 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.