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	7-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 / SubagentStop, permission_mode field, runtime fail-open	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.
• 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.
• Hook system — PreToolUse / PostToolUse / Notification / Stop / SubagentStop hooks with permission_mode field. Runtime fail-open — hooks never block tool execution. 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.

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. Code verification uses each language's native build tools (go build, npx tsc, cargo build, make, etc.) — no LSP server required.

---

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
faq	Frequently asked questions

---

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.

Recommended Tools

These third-party tools are not required but significantly improve the Waveloom experience:

Tool	Description
ripgrep (rg)	High-performance recursive grep, ~10x faster than grep -r. Waveloom prefers rg over grep for all code searches when available.
RTK (rtk)	Token-optimized CLI proxy — rewrites common commands to compact equivalents, saving 60–90% input tokens. Waveloom loads it via ~/.claude/hooks/rtk-rewrite.sh.

---

Apache License 2.0 © 2026 Waveloom Contributors