English  ·  简体中文

---

A DeepSeek-native terminal code agent engineered for cache economics. Prefix-cache architecture keeps the longest common prefix cache-hot across turns; LLM auto-selects pro for deep reasoning and flash for routine tasks — maximizing cache hits and minimizing token cost. Premium TUI with .claude/skills/ and .claude.json MCP configs drop in — zero-friction onboarding. One Go binary.

DeepSeek 原生终端编码代理，围绕缓存经济学设计。 前缀缓存架构让最长公共前缀跨轮次持续命中；LLM 自动按任务选模型——pro 做深度推理，flash 处理常规任务——最大化缓存命中，最小化 token 成本。专业级 TUI，.claude/skills/ 和 .claude.json MCP 配置开箱兼容，零摩擦迁移。单一 Go 二进制。

---

Quick Start

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Menfre01/waveloom/main/install.sh | sh

Or via Homebrew:

brew install menfre01/tap/waveloom

Supports macOS / Linux / Windows, AMD64 & ARM64. Installs to ~/.local/bin, no sudo needed.

Windows

Requires Git for Windows. Open PowerShell and run:

powershell -c "irm https://raw.githubusercontent.com/Menfre01/waveloom/main/install.ps1 | iex"

Tip

For the best experience on Windows, use WSL2. Install the Linux binary inside WSL2 and enjoy native performance — no Git Bash forwarding layer, smoother terminal rendering, and faster shell commands.

Prefer Git Bash? Waveloom requires bash.exe — cmd and PowerShell are not supported. After installation, open Git Bash and run the commands below. If waveloom is not found, add %USERPROFILE%\.local\bin to your Windows PATH (the installer handles this automatically).

Configure

waveloom setup
waveloom

Important

API key connects directly to DeepSeek / Kimi / OpenAI — your code never passes through a third-party server. Every file write and command execution requires your confirmation.

---

How does it compare?

	Waveloom	Claude Code	Reasonix
Skill/Plugin	Drop-in: .claude/skills/ SKILL.md + .claude/plugins/ installed plugins, 9 frontmatter fields ($ARGUMENTS, paths, !`cmd` injection, etc.)	Native SKILL.md + commands + plugin system	13 frontmatter fields, no variable substitution in skill bodies
Cache design	DeepSeek prefix matching: 4-tier watermark (Snip → Prune → Summarize), compaction bytes never change	Anthropic cache_control: cache_edits API, dynamic system prompt sections	DeepSeek prefix matching: 4-tier (notice → snip → compact → force), session.Replace() bumps rewrite version
Compaction	Monotonic — compactionDecisionSet + triple cursor, each message compacted once	Per-turn independent, no durability guarantee	Prefix bytes preserved across compact, but no per-message decision tracking
Plan mode	Guard restricts writes to plan file only; build tools auto-allowed	Write restricted to plan file only; rich exit UI	planmode.Policy with trust gates for bash/MCP; Marker string injected; no plan file
Sub-agents	Fork (inherits context) / Cold: Evaluate (code review) • Explore (read-only) • Verification (adversarial)	Fork + Cold + In-process + Coordinator	task tool with nested agent, background via job manager
Runtime	Go binary ~20MB, zero deps	Node.js	Go binary + Desktop app, external plugin host
MCP	Full client (config, transport, tool proxy), registered alongside built-in tools	Native MCP support	Native MCP support
Permission	8-step pipeline, 5-layer tool output security (Unicode cleaning → injection scan → boundary markers → risk grading → safe truncation), 4-tier command safety (RiskNone/RiskLow/RiskMedium/RiskHigh)	8-source rule merge + LLM classifier auto-approval	Policy + Approver, 9-stage execute pipeline, shellsafe readOnly detect
Hook	PreToolUse / PostToolUse / Notification / Stop, permission_mode field, fail-open by default (exit code 2 explicitly blocks)	Native hooks: PreToolUse, PostToolUse, etc.	—
TUI polish	Streaming reasoning, rich diff, permission dialogs, @ fuzzy picker, / palette, i18n, theme toggle — premium terminal UX	Native TUI (Ink/React), gold standard	Functional TUI, different UX paradigm

Choose Waveloom if: you want premium terminal UX with multi-provider support (DeepSeek / Kimi / OpenAI), .claude/skills/ + .claude/plugins/ drop-in, without the cache miss cost. Choose Claude Code if: you use Anthropic, need coordinator mode, deep in the Claude ecosystem. Choose Reasonix if: you want a desktop GUI, QQ Bot integration, or a larger community ecosystem.

---

Why TUI

Waveloom is the only DeepSeek-native agent with premium terminal polish. Streaming reasoning with syntax highlighting, rich diff, permission dialogs, @ fuzzy file picker, / command palette, light/dark/color-blind theme toggle, ? shortcut help, zh-CN / en-US i18n. Most DeepSeek agents treat the TUI as an afterthought — raw text streaming, no interaction design. Fire it up and feel the difference.

---

Highlights

• Prefix cache optimized — Fixed System Prompt, append-only message history, four-tier watermark compaction. Maximum common prefix stays cache-hot across turns.
• Multimodal vision — Reference images with @shot.png; deepseek-v4-flash-vision-exp describes screenshots, OCRs text, and analyzes charts.
• Permission safety — Three-tier decisions (allow / deny / ask) with pattern-matching rule engine, backed by a 5-layer tool output security pipeline (Unicode cleaning → injection scan → boundary markers → risk grading → safe truncation). Every write operation requires your confirmation.
• OS-level sandbox — Optional execution isolation via bubblewrap (Linux) / Seatbelt (macOS): read-only root, workspace-only writes, configurable credential masking (filesystem.denyRead / credentials.files; recommended list in the settings docs), env var stripping, configurable env injection (redirect build-tool caches like GOPATH/GOMODCACHE/npm_config_cache into the workspace), and network control (off / on). Auto-activated with --bypass-permissions; configure via "sandbox" in settings.json or --sandbox-network off|on.
• Hook system — PreToolUse / PostToolUse / Notification / Stop hooks with permission_mode field. Fail-open by default — hook crashes never block tool execution; exit code 2 explicitly blocks. Configured via settings.json.
• Session persistence — Close the terminal, come back days later with waveloom --continue. The agent remembers all prior context.
• Checkpoint/Rewind — Rewind to any previous message with full file state restoration. Fork mode preserves original session intact — history never lost.
• Plan Mode — Two-stage workflow: explore & design first, implement after approval. Shift+Tab to enter/exit, Guard-enforced write protection.
• Sub_model configuration — Set "sub_model": "deepseek-v4-flash" in settings.json to assign a lightweight model for explore subagents. Explore uses flash (~2× cheaper) for code search and discovery; evaluate/verification subagents use pro for full reasoning. LLM auto-selects between pro/flash based on task complexity. Saves ~50% on subagent token cost.
• 14 built-in tools — read / write / edit / bash / web_fetch / web_search / ask_user_question / enter_plan_mode / exit_plan_mode / skill / agent / kill_background_task / todo_create / todo_update.
• i18n multilingual — Full zh-CN / en-US bilingual UI. --locale CLI flag, /locale command, auto-detect from LANG.

---

FAQ

Q: How do I switch models? Type /model in interactive mode, or waveloom --model deepseek-v4-flash. Select proplan to use the pro model in plan mode and the flash model for regular tasks (/model proplan). Requires model (plan mode) and sub_model (regular tasks) configured in settings.json; it falls back to a plain model error otherwise.

Q: Does web_search work with deepseek-v4-flash? Yes — with deepseek-v4-flash, Waveloom automatically switches to the DeepSeek Responses API and web_search becomes a server-side built-in search (no DuckDuckGo/Brave dependency). Other models keep the local search backends.

Q: How do I switch LLM providers? Type /provider to open the interactive provider picker (overlay with ↑↓ select / Enter confirm / Esc cancel), or /provider kimi to switch directly. Profiles are configured in settings.json under llm.profiles.

Q: Is my API key safe? Stored locally at ~/.waveloom/. Keys connect directly to DeepSeek / Kimi / OpenAI — no third-party relay.

Q: How do I switch languages? Type /locale to toggle between Chinese and English, or waveloom --locale zh-CN. The setting persists automatically in settings.json.

Q: How do I configure a lightweight model for explore subagents? Add "sub_model": "deepseek-v4-flash" to the llm section in settings.json. The explore subagent uses this model for code search and discovery tasks — ~2× cheaper than the primary model. For evaluate/verification subagents, the primary model (model, e.g. deepseek-v4-pro) is used for full reasoning quality. No runtime switching needed.

Q: What languages are supported? Waveloom works with any text-based project. Post-edit LSP diagnostics automatically verify code correctness for Go, Rust, TypeScript/JavaScript, and C/C++. Other languages use native build tools (go build, npx tsc, cargo build, make, etc.).

---

Docs

Document	Content
usage	Interactive mode, shortcuts, Skill system
settings	API key, model, timeout, compaction, sub_model
prefix-cache	DeepSeek caching, four-tier compaction
environment	Toolchain probing
mcp	MCP client, config sources, CLI management
mcp-ide-setup	Connect IntelliJ IDEA / VS Code MCP Server
acp	ACP (Agent Client Protocol) agent mode for Zed, protocol compatibility
faq	Frequently asked questions
lsp	LSP diagnostics, language detection, configuration

---

Development

Go 1.25+, make build / make test. See CONTRIBUTING.md for project structure and contribution guide.

Built with Bubble Tea (TUI framework), Glamour (Markdown rendering), and Lip Gloss (terminal styling) — part of the Charm ecosystem.