---
## What is Synerix? / Synerix 是什么？
**Synerix** is a high-performance, AI-native coding terminal built in Rust that brings intelligent code assistance directly into your CLI workflow. It combines the power of modern LLMs with a security-first sandbox, multiple coding modes, and a plugin ecosystem — all in a beautiful, responsive TUI.
**Synerix** 是一款用 Rust 构建的高性能 AI 原生编程终端，将智能代码辅助直接带入你的 CLI 工作流。它将现代 LLM 的能力与安全优先的沙箱、多种编程模式和插件生态系统相结合 —— 全部集成在一个美观、响应迅速的 TUI 中。
Instead of juggling editors, browsers, and terminals, Synerix keeps you in flow: **type → generate → compile → test → fix**, all in one place.
无需在编辑器、浏览器和终端之间来回切换，Synerix 让你保持心流：**打字 → 生成 → 编译 → 测试 → 修复**，所有操作都在一个地方完成。
### Two Coding Modes / 两种编程模式
| Mode / 模式 | Badge / 图标 | Description / 描述 |
|------|-------|-------------|
| **Plan** / 规划 | `📋` | Analyze first, propose a plan, then execute step-by-step with approval. / 先分析，提出方案，再逐步骤审批执行。 |
| **Vibe** / 沉浸 | `🎵` | Immersive AI coding — describe, generate, compile, test, and fix in a fully automated loop. / 沉浸式 AI 编程 —— 描述、生成、编译、测试和修复，全自动化循环。 |
---
## Why Synerix? / 为什么选择 Synerix？
| The Problem / 问题 | Synerix's Answer / Synerix 的答案 |
|-------------|------------------|
| Switch between 6 tools constantly / 在 6 个工具之间不断切换 | **One terminal** — type, generate, review, run, fix / **一个终端** —— 打字、生成、审查、运行、修复 |
| Manual approval for every operation / 每个操作都需手动批准 | **Smart sandbox** — auto-approves safe ops, previews risks / **智能沙箱** —— 自动批准安全操作，预览风险 |
| Paste code back and forth / 来回粘贴代码 | **Auto-iteration** — `described → generated → compiled → tested → fixed` / **自动迭代** —— `描述 → 生成 → 编译 → 测试 → 修复` |
| Context switching kills flow / 上下文切换打断心流 | **Persistent sessions** — SQLite-backed conversation history / **持久化会话** —— SQLite 支持的对话历史 |
| Bloated IDE with slow startup / 臃肿 IDE 启动缓慢 | **2.8 MB binary, <50ms startup** — native Rust performance / **2.8 MB 二进制文件，<50ms 启动** —— 原生 Rust 性能 |
---
## Quick Start / 快速开始
```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Agions/synerix/main/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/Agions/synerix/main/install.ps1 | iex
```
> **From source / 从源码构建:** see [Local Development](#local-development--本地开发) below.
[Read the full guide → / 阅读完整指南 →](https://github.com/Agions/synerix/blob/main/docs/guide/getting-started.md)
---
## Local Development / 本地开发
### Prerequisites / 前置要求
- **Rust** 1.75+ ([rustup](https://rustup.rs/))
- **Git**
- **Terminal**: modern terminal with 256-color support (iTerm2, Windows Terminal, Alacritty, etc.)
### Clone and Build / 克隆并构建
```bash
git clone https://github.com/Agions/synerix.git
cd synerix
# Build the release binary
cargo build --release
# Run the TUI directly (no install needed)
cargo run --release
```
### Run Tests / 运行测试
```bash
# All tests
cargo test --workspace
# With output
cargo test -- --nocapture
# Specific crate
cargo test -p synerix
```
### Lint and Format / 代码检查
```bash
# Format check
cargo fmt -- --check
# Auto-format
cargo fmt --all
# Clippy
cargo clippy --all-targets --all-features -- -D warnings
# Type check only
cargo check --all-targets
```
### Project Structure / 项目结构
```
synerix/
├── crates/
│ ├── synerix/ # Main binary + TUI
│ │ ├── src/
│ │ │ ├── app/ # State machine, event loop, input handling, dispatch
│ │ │ ├── agent/ # Agent loop + orchestration + multi-agent
│ │ │ ├── tui/ # Ratatui: components, primitives, theme, layout, router, renderer
│ │ │ ├── command/ # Command registry + palette
│ │ │ ├── config/ # Keymap profiles (vim/emacs/default) + settings
│ │ │ ├── tools/ # Tool registry + builtins
│ │ │ ├── skills/ # Skills system
│ │ │ ├── mcp/ # MCP protocol client
│ │ │ ├── sandbox/ # Security sandbox + risk classifier
│ │ │ ├── llm/ # LLM adapters + streaming
│ │ │ ├── session/ # SQLite persistence
│ │ │ ├── slash/ # Slash command handling
│ │ │ ├── workflow/ # DAG workflow engine
│ │ │ ├── plugins/ # Plugin system
│ │ │ └── project/ # Project detection
│ │ └── tests/ # Integration & e2e tests
│ └── synerix-core/ # Shared types + utilities (AgentEvent, CodingMode, ...)
├── docs/ # VitePress documentation
├── benches/ # Performance benchmarks
└── Cargo.toml # Workspace root
```
### Development Workflow / 开发流程
1. **Make changes** in `crates/synerix/src/`
2. **Run locally**: `cargo run --release` to test in the TUI
3. **Run tests**: `cargo test --workspace`
4. **Lint**: `cargo fmt --all && cargo clippy --all-targets -- -D warnings`
5. **Commit**: use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `refactor:`, etc.)
6. **Push and open PR** on GitHub
### Common Issues / 常见问题
| Issue / 问题 | Solution / 解决方案 |
|---|---|
| `cargo: command not found` | Install Rust via `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
| `error: linker 'cc' not found` | Install Xcode command line tools: `xcode-select --install` (macOS) or `build-essential` (Linux) |
| TUI renders incorrectly | Ensure your terminal supports 256 colors and Unicode |
| Tests hang / timeout | Some integration tests require network; run `cargo test --lib` for unit tests only |
| `cargo fmt` conflicts | Run `cargo fmt --all` before committing to avoid CI failures |
---
## Capabilities / 核心能力
| Feature / 特性 | Details / 详情 |
|---------|---------|
| ⚡ **Blazing Performance** / 极速性能 | Rust binary, 2.8 MB, <50ms startup, 860+ tests (cargo test --workspace) / Rust 二进制文件，2.8 MB，<50ms 启动，860+ 测试（cargo test --workspace 实测） |
| 🛡 **Security Sandbox** / 安全沙箱 | Atomic writes, risk classifier, MCP isolation, approval flows / 原子写入、风险分类器、MCP 隔离、审批流程 |
| 🧩 **Plugin System** / 插件系统 | Commands, skills, MCP servers, custom agents / 命令、技能、MCP 服务器、自定义代理 |
| 🎨 **Tokyo Night TUI** | Rounded borders, syntax-highlighted diffs, hot-swappable dark/light themes / 圆角边框、语法高亮差异、可热切换的 dark/light 主题 |
| 🔑 **Keymaps** / 按键映射 | Vim, Emacs, and Default layouts / Vim、Emacs 和默认布局 |
| 💡 **Smart Defaults** / 智能默认 | DeepSeek powered out of the box, auto-detects project context / 开箱即用 DeepSeek，自动检测项目上下文 |
| 🔄 **Session Persistence** / 会话持久化 | SQLite-backed conversations, resume anywhere / SQLite 支持的对话， anywhere 恢复 |
| 🎯 **Goal-Driven Loops** / 目标驱动循环 | `/goal` auto-iteration until conditions are met / `/goal` 自动迭代直到条件满足 |
---
## Architecture / 架构
```
synerix/
├── crates/
│ ├── synerix/ # Main binary + TUI
│ │ └── src/
│ │ ├── main.rs # Startup + binary entry / 启动 + 二进制入口
│ │ ├── app/ # State machine + event dispatch / 状态机 + 事件分发
│ │ │ ├── state/ # App state (controllers, focus) / 应用状态
│ │ │ ├── event_loop.rs # Main event loop (tokio::select!)
│ │ │ ├── actions.rs # Action dispatch / 动作分发
│ │ │ ├── input_handler.rs # Mode-specific input / 模式特定输入
│ │ │ └── dispatch/ # Command & agent dispatch / 命令与代理分发
│ │ ├── tui/ # TUI rendering (ratatui) / TUI 渲染
│ │ │ ├── components/ # Composable components (Component trait)
│ │ │ ├── primitives/ # Atomic primitives (panel/divider/shadow/focus ring)
│ │ │ ├── theme/ # Theme manager + presets (runtime hot-swap)
│ │ │ ├── layout/ # Layout tree + hit testing / 布局树 + 命中测试
│ │ │ ├── screen/ # Screen composition (ChatScreen, ...)
│ │ │ ├── router.rs # Event routing (key/mouse/tick → intent)
│ │ │ ├── viewmodel.rs # UiModel projection from App
│ │ │ └── renderer.rs # Frame orchestration / 帧编排
│ │ ├── agent/ # Agent loop + multi-agent swarm
│ │ ├── command/ # Command registry + palette
│ │ ├── config/ # Keymap profiles (vim/emacs/default) + settings
│ │ ├── tools/ # Tool registry + builtins
│ │ ├── skills/ # Skills system
│ │ ├── mcp/ # MCP protocol client
│ │ ├── sandbox/ # Security sandbox + risk classifier
│ │ ├── workflow/ # DAG workflow engine
│ │ ├── llm/ # LLM adapters + streaming
│ │ ├── session/ # SQLite persistence
│ │ ├── slash/ # Slash command handling
│ │ ├── plugins/ # Plugin system
│ │ └── project/ # Project detection
│ └── synerix-core/ # Shared types + utilities (AgentEvent, CodingMode, ...)
├── crates/synerix/tests/ # 860+ integration & e2e tests
├── docs/ # VitePress documentation
└── Cargo.toml # Workspace root
```
---
## Community / 社区
| | |
|---|---|
| 📖 **Docs** / **文档** | [github.com/Agions/synerix/tree/main/docs](https://github.com/Agions/synerix/tree/main/docs) |
| 🐛 **Issues** / **问题反馈** | [github.com/Agions/synerix/issues](https://github.com/Agions/synerix/issues) |
| 🥭 **Gitee Mirror** / **Gitee 镜像** | [gitee.com/Agions/synerix](https://gitee.com/Agions/synerix) |
---
## License / 许可证
MIT — free for personal and commercial use. / MIT —— 免费用于个人和商业用途。
