<p align="center">
<img src="assets/banner.png" alt="SynapsCLI" width="100%" />
</p>
<h3 align="center">The agent runtime that boots before your Node binary finishes importing.</h3>
<p align="center">
<a href="https://github.com/HaseebKhalid1507/SynapsCLI/stargazers"><img src="https://img.shields.io/github/stars/HaseebKhalid1507/SynapsCLI?style=flat&color=yellow" alt="Stars"></a>
<a href="https://crates.io/crates/synaps"><img src="https://img.shields.io/crates/d/synaps?color=orange&label=installs" alt="Downloads"></a>
<img src="https://img.shields.io/badge/rust-1.80%2B-orange.svg" alt="Rust">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
</p>
<p align="center">
One Rust binary. Any model. Any provider.<br><br>
<a href="https://github.com/HaseebKhalid1507/SynapsCLI/wiki"><b>๐ Read the Wiki</b></a> ยท <a href="https://github.com/HaseebKhalid1507/SynapsCLI/wiki/Installation"><b>โก Quick Start</b></a> ยท <a href="https://github.com/HaseebKhalid1507/SynapsCLI/wiki/FAQ-and-Troubleshooting"><b>โ FAQ</b></a>
</p>
---
<p align="center">
<img src="assets/demo.gif" alt="SynapsCLI Demo" width="720" />
</p>
---
## Install
```bash
cargo install synaps # crates.io
```
<details>
<summary>More options</summary>
```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)
```bash
# From source
git clone https://github.com/HaseebKhalid1507/SynapsCLI && cd SynapsCLI
cargo build --release && ./target/release/synaps
```
</details>
## 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
| `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.
---
## 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
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.
---
## 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.
---
<details>
<summary><b>Architecture</b></summary>
```
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.
</details>
---
## License
Apache 2.0. See [LICENSE](LICENSE).
---
<p align="center">
<sub>Because every other CLI agent was a 400MB Electron app pretending to be a terminal tool.</sub>
</p>