Whale: a DeepSeek-first terminal agent that bets on prompt caching

The problem Whale picks: DeepSeek users with no DeepSeek-native agent

Most terminal coding agents are written against a generic chat-completions interface and then pointed at whichever provider the user has a key for. That works, but it leaves provider-specific behaviour on the table. Whale is explicit about refusing that shape: the README lists "Multi-model shell" under Non-goals and describes the project as "optimized for DeepSeek's caching, tools, and pricing." The intended user is someone who has already chosen DeepSeek as their model provider and wants an agent that treats DeepSeek's long context and prompt caching as the design centre rather than a compatibility target. The repo topics point the same way: coding-agent, deepseek, deepseek-cli, mcp, skills, terminal. If you are shopping for one agent to switch between Anthropic, OpenAI and DeepSeek, Whale says up front that it is not that. The project also carries a disclaimer that it is not affiliated with DeepSeek Inc., so the DeepSeek-specific tuning is community work, not vendor work.

How Whale is put together: a Go TUI, a QuickJS workflow runtime, and MCP

The README's credits section is the most useful architecture document in the repository. Whale is Go, built on Charmbracelet's Bubble Tea, Lip Gloss and Glamour for the terminal interface, spf13/cobra for the command surface, alecthomas/chroma for syntax highlighting and yuin/goldmark for Markdown rendering. Workflow scripting runs on fastschema/qjs, QuickJS bindings for Go, and MCP support comes from modelcontextprotocol/go-sdk. There is also tetratelabs/wazero, a pure-Go WebAssembly runtime, listed among the dependencies, though the README does not state which feature it backs. The data flow the README describes is: you type in the TUI or pass a prompt to the CLI, the agent reads files, runs commands, edits code and searches the web, and optional MCP servers extend the tool list. Dynamic Workflows sit above that, letting a JavaScript file call agent() and parallel() to fan out several agent invocations and then synthesise their output. The README gives this example, a file at .whale/workflows/research.js that runs two parallel agent calls and then a third to combine them. The runtime is a real interpreter embedded in the binary, not a shell-out, which is consistent with the "zero bloat" framing and with a single static Go binary.

Getting it running: four install paths and two config files

Installation is deliberately broad. The npm route is npm install -g @usewhale/whale and works on any platform with Node. macOS users get brew install usewhale/tap/whale. Linux uses a curl pipe from scripts/install.sh on the main branch. Windows has both a PowerShell one-liner, irm https://raw.githubusercontent.com/usewhale/Whale/main/scripts/install.ps1 | iex, and a CMD variant that invokes powershell -NoProfile -ExecutionPolicy Bypass with the same script. The README states Windows 10 or Windows Server 2016 or later for that path. After install, whale setup takes your DeepSeek API key and whale launches the interactive TUI. Beyond the TUI there are two other modes: whale ask "..." for one-shot questions, and whale --headless for CI, automated PR reviews and scheduled tasks. Configuration lives in TOML. The README shows .whale/config.local.toml with a [workflows] section and an enabled key, and notes that you can toggle the same thing from inside the TUI by running /config and enabling Dynamic workflows. That two-file, two-route arrangement (edit TOML or flip a TUI setting) is a small thing but it tells you the project expects people to change behaviour mid-session rather than restart.

Dynamic Workflows are off by default, and that is the tell

The headline extension, Dynamic Workflows, ships disabled. The README states this twice: a warning that it is disabled by default, and the instruction to enable it either through /config in the TUI or by adding [workflows] enabled = true to .whale/config.local.toml. A feature that is documented as Claude Code compatible and that the project puts near the top of its feature table being off on a fresh install is worth reading carefully. It suggests the maintainers consider multi-agent fan-out a power-user mode with real cost and unpredictability, which is the right instinct. A workflow that spawns several agents in parallel multiplies token spend by the number of branches, and the cache-hit economics that make single-agent sessions cheap do not obviously carry over to branches that diverge early. The README does not discuss workflow-level cost accounting at all. If you enable workflows, treat the first runs as a spend experiment, not a productivity feature.

The ~98% cache figure needs your own measurement

The prompt cache claim is the centre of the pitch. The README puts "~98% prompt cache hit" in the badge, in the tagline and in the feature table, and describes the mechanism as reusing cached context aggressively so that "most prompts hit cache." What the README does not provide is the measurement method: no workload description, no session length, no statement of whether the figure is an average across a specific task type or a best case. Cache hit rate is also not a property of the agent alone. It depends on how much of the prompt prefix stays stable between turns, which in turn depends on how the agent orders its context. Whale's claim is that it is designed to keep that prefix stable, and the DeepSeek-first stance is consistent with that. But the number itself is a claim in a README, and the article cannot verify it. The practical way to check is to run a normal session, look at the usage numbers DeepSeek reports, and compare the cached and uncached token counts. If the ratio holds on your workload, the cost argument lands. If your sessions involve frequent large file rewrites that invalidate the prefix, it will not.

Where Whale is the wrong tool

The README's own Project Status section is unusually direct: Whale is "in active development" and "best suited for personal projects, experimental repositories, and workflows where changes can be reviewed and rolled back." That is a meaningful restriction. An agent that reads files, runs commands and edits code with a 1M-token context can touch a lot of a repository before you notice, and the project is telling you it is not yet positioned for codebases where an unreviewed edit is expensive. The release cadence supports the same reading: v0.1.64, v0.1.65 and v0.1.66 landed within roughly a week in August 2026, which is a fast-moving pre-1.0 line. Version numbers in the 0.1.x range mean config keys, workflow APIs and behaviour can change between releases. If your team needs a stable agent interface that will not shift under CI scripts, this is not it yet. The other clear boundary is the non-goal list: no multi-model shell and no IDE replacement. If your workflow is mostly in-editor refactoring with language-server assistance, Whale adds a terminal round trip rather than removing one.

The alternative: a provider-agnostic agent, and what actually differs

The obvious alternative is a provider-agnostic terminal agent such as Aider, which supports many model backends and is built around git-aware edit loops. The difference is not a feature checklist, it is where each project spends its complexity budget. A multi-provider agent has to normalise tool-calling formats, context-window handling and caching semantics across APIs that do not agree, and it cannot assume any one provider's cache behaviour. Whale spends that budget the other way: one provider, deeper assumptions. The README's claim that Whale is "DeepSeek-native" and "no generic multi-model wrapper" is exactly this trade. The cost is that switching providers means switching tools. The benefit, if the cache claim holds, is that the per-session price is lower than a generic agent pointed at the same model, because the generic agent is not arranging its prompt prefix for DeepSeek's cache. Whether that benefit is real is the thing to test, not the thing to assume. A second alternative, staying inside a full IDE with a built-in assistant, wins on refactoring ergonomics and loses on scriptability: Whale's headless mode and JavaScript workflows have no direct equivalent in a GUI assistant.

Maintenance, licence and upgrade cost

Whale is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence and it is the same licence used by most of the Go dependencies listed in the credits. It does not, on its own, settle anything about the DeepSeek API terms, which govern your use of the model regardless of the agent's licence. On maintenance, the practical cost is the pre-1.0 churn: three releases in about a week, and a README that documents config through a local TOML file that users are expected to edit. Pin a version in CI rather than tracking latest, and read the release notes before bumping, because a change to the [workflows] section or to the MCP tool surface can break a headless job silently. The four install channels are a second maintenance surface: npm, Homebrew, the Linux install script and the Windows PowerShell script can lag each other, so the version you get depends on which one you used. For a team, that means deciding on one channel and documenting it. The repository also points to ROADMAP.md and CONTRIBUTING.md for direction, which is where to look before assuming a behaviour is intended rather than a gap.

Editorial conclusion

Adopt Whale if you already pay for DeepSeek, work mostly in a terminal, and want a small Go binary with MCP and scriptable multi-agent workflows rather than a multi-model wrapper. Do not adopt it if your work depends on a non-DeepSeek model, if you need IDE-grade refactoring, or if you are not prepared to review and roll back agent edits on a repository that matters. Before trusting the cost story, verify the cache-hit rate on your own workload: the README states the ~98% figure but does not show how it was measured, so instrument the first sessions and compare DeepSeek billing against a run with caching cold. Then check whether the TUI you get from your install path matches the release you intended, since npm, Homebrew, the shell script and the PowerShell script are four separate channels.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. usewhale/Whale on GitHub