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?

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.
• 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

---

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.