English  ·  简体中文

Waveloom

release CI downloads Go DeepSeek license

--- **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 二进制。

Waveloom Demo

--- ## Quick Start ### macOS / Linux ```sh curl -fsSL https://raw.githubusercontent.com/Menfre01/waveloom/main/install.sh | sh ``` Or via Homebrew: ```sh brew install menfre01/tap/waveloom ``` > Supports macOS / Linux / Windows, AMD64 & ARM64. Installs to `~/.local/bin`, no sudo needed. ### Windows Requires [Git for Windows](https://git-scm.com/downloads/win). Open PowerShell and run: ```powershell powershell -c "irm https://raw.githubusercontent.com/Menfre01/waveloom/main/install.ps1 | iex" ``` > [!TIP] > **For the best experience on Windows, use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).** 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 ```sh waveloom setup waveloom ``` > [!IMPORTANT] > API key connects directly to DeepSeek / Kimi / GLM / 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 / GLM / 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-flash` (DeepSeek-V4.1-Flash, natively multimodal) 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-flash"` in `settings.json` to assign a lighter model for explore subagents. Explore uses the sub model for code search and discovery; evaluate/verification subagents use the primary model for full reasoning. LLM auto-selects between the two based on task complexity. Note: as of 2026-09-14, DeepSeek continues to serve `deepseek-v4-pro` with unchanged billing — a distinct backend from flash. - **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-flash`. Select `proplan` to use the `model` in plan mode and the `sub_model` for regular tasks (`/model proplan`). Requires both configured in `settings.json`; it falls back to a plain model error otherwise. **Q: Does web_search work with deepseek-flash?** Yes — `web_search` runs on the local backend (DuckDuckGo by default, Brave via `BRAVE_API_KEY`) on every provider. Note: DeepSeek used to offer a server-side built-in `web_search` in the Responses API; it has since been retired (the compatibility table now lists built-in `web_search` as *Ignored*), so Waveloom exposes it as a regular function tool for all models. **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 / GLM / 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-flash"` to the `llm` section in `settings.json`. The explore subagent uses this model for code search and discovery tasks. For evaluate/verification subagents, the primary model (`model`) 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`](./docs/usage.en.md) | Interactive mode, shortcuts, Skill system | | [`settings`](./docs/settings.en.md) | API key, model, timeout, compaction, sub_model | | [`prefix-cache`](./docs/prefix-cache.en.md) | DeepSeek caching, four-tier compaction | | [`environment`](./docs/environment.en.md) | Toolchain probing | | [`mcp`](./docs/mcp.en.md) | MCP client, config sources, CLI management | | [`mcp-ide-setup`](./docs/mcp-ide-setup-en.md) | Connect IntelliJ IDEA / VS Code MCP Server | | [`acp`](./docs/acp.en.md) | ACP (Agent Client Protocol) agent mode for Zed, protocol compatibility | | [`faq`](./docs/faq.en.md) | Frequently asked questions | | [`lsp`](./docs/lsp.en.md) | LSP diagnostics, language detection, configuration | --- ## Development Go 1.25+, `make build` / `make test`. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for project structure and contribution guide. Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) (TUI framework), [Glamour](https://github.com/charmbracelet/glamour) (Markdown rendering), and [Lip Gloss](https://github.com/charmbracelet/lipgloss) (terminal styling) — part of the [Charm](https://charm.sh) ecosystem.