Getting Started / 快速开始

Welcome to Synerix — an AI-native coding terminal designed to keep you in flow.

欢迎使用 Synerix —— 一款专为保持心流而设计的 AI 原生编程终端。

What is Synerix? / Synerix 是什么？

Synerix is a high-performance terminal that combines the power of modern AI with the speed of a native CLI. It thinks, writes, reviews, and fixes code — without pulling you out of the command line.

Synerix 是一款高性能终端，将现代 AI 的能力与原生 CLI 的速度相结合。它会思考、编写、审查和修复代码 —— 而不会让你离开命令行。

Quick Install / 快速安装

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/Agions/synerix/main/install.sh | bash

Windows (PowerShell 5.1+)

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://raw.githubusercontent.com/Agions/synerix/main/install.ps1 | iex

From Source / 从源码构建

git clone https://github.com/Agions/synerix.git
cd synerix
cargo build --release
cargo install --path .

First Launch / 首次启动

After installation, configure your LLM provider:

安装后，配置你的 LLM 提供商：

# Create config directory / 创建配置目录
mkdir -p ~/.config/synerix

# Create config file / 创建配置文件
cat > ~/.config/synerix/config.toml << 'EOF'
[llm]
provider = "deepseek"
api_key = "sk-..."
model = "deepseek-v4-flash"
EOF

Then launch:

然后启动：

synerix

Local Development / 本地开发

Prerequisites / 前置要求

• Rust 1.75+ with cargo — install via rustup
• Git
• Terminal with 256-color and Unicode support (iTerm2, Windows Terminal, Alacritty, Kitty, etc.)

Clone and Build / 克隆并构建

git clone https://github.com/Agions/synerix.git
cd synerix

# Build the release binary
cargo build --release

# Run the TUI directly without installing
cargo run --release

Run Tests / 运行测试

# All tests (unit + integration)
cargo test --workspace

# Unit tests only (faster, no network required)
cargo test --lib

# With output for debugging
cargo test -- --nocapture

# Specific crate
cargo test -p synerix

Lint and Format / 代码检查

# Check formatting (CI uses this)
cargo fmt --all -- --check

# Auto-format
cargo fmt --all

# Clippy with all warnings as errors (CI uses this)
cargo clippy --all-targets --workspace -- -D warnings

# Quick type check without building
cargo check --all-targets

Project Structure / 项目结构

synerix/
├── crates/
│   ├── synerix/           # Main binary + TUI application
│   │   ├── src/
│   │   │   ├── app/       # State machine, event loop, input handling
│   │   │   ├── tui/       # Ratatui widgets, theme, layout, renderer
│   │   │   ├── agent/     # Agent loop + orchestration
│   │   │   ├── tools/     # Tool registry + builtins
│   │   │   ├── skills/    # Skills system
│   │   │   ├── mcp/       # MCP protocol client
│   │   │   ├── sandbox/   # Security sandbox + approval flows
│   │   │   ├── llm/       # LLM adapters + streaming
│   │   │   └── session/   # SQLite persistence
│   │   └── Cargo.toml
│   └── synerix-core/      # Shared types + utilities
├── docs/                  # VitePress documentation
├── benches/               # Performance benchmarks
└── Cargo.toml             # Workspace root

Development Workflow / 开发流程

1. Create a branch: git checkout -b feat/your-feature
2. Make changes in crates/synerix/src/
3. Run locally: cargo run --release to test in the TUI
4. Run tests: cargo test --workspace
5. Lint: cargo fmt --all && cargo clippy --all-targets -- -D warnings
6. Commit using Conventional Commits:

   feat: add new slash command
   fix: correct scroll offset calculation
   refactor: extract widget primitives
   docs: update getting started guide

7. 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 sudo apt install build-essential (Linux)
TUI renders incorrectly	Ensure your terminal supports 256 colors and Unicode; set TERM=xterm-256color
Tests hang or timeout	Some tests require network; run cargo test --lib for unit tests only
cargo fmt CI failure	Run cargo fmt --all before committing
Clippy warnings	Fix all warnings; CI uses -D warnings (treats warnings as errors)

Your First Session / 你的第一个会话

❯ Refactor main.rs to reduce nesting
   ✓ Code generated
   ✓ cargo check passes
   ✓ Tests pass
   ✓ Done in 1.8s

❯ /mode vibe
   Switched to Vibe mode — auto-iterate enabled

❯ Add pagination to the API endpoint
   ✓ Generated pagination module
   ✓ Compiled successfully
   ✓ All tests green

Common Commands / 常用命令

Command / 命令	Description / 描述
synerix	Launch the interactive terminal / 启动交互式终端
synerix --help	Show help information / 显示帮助信息
synerix --version	Show version / 显示版本
/mode <name>	Switch coding mode (plan, vibe) / 切换编程模式
/help	List all slash commands / 列出所有斜杠命令
/clear	Clear conversation / 清空对话
/exit	Quit Synerix / 退出 Synerix

Keybindings / 快捷键

Key / 按键	Action / 操作
Tab	Auto-complete / switch mode / 自动补全 / 切换模式
Ctrl+C	Cancel current operation / 取消当前操作
Ctrl+D	Exit / 退出
Ctrl+L	Clear screen / 清屏
↑ / ↓	Navigate history / 浏览历史

Next Steps / 下一步

• Installation — Detailed installation guide / 详细安装指南
• Configuration — Customize Synerix to your workflow / 根据你的工作流定制 Synerix
• Coding Modes — Learn about Plan and Vibe modes / 了解规划模式和沉浸模式
• Troubleshooting — Common issues and solutions / 常见问题与解决方案