Whale: a DeepSeek-native coding agent for the terminal

What Whale is for, and who it is not for

Whale is a coding agent that runs in a terminal. Its README describes it as "DeepSeek-native", built for that provider's long context window (the project states 1M tokens), its tool calling, and its cost profile. The tagline on the repository page says "in any environment", and the interface table lists three ways in: an interactive TUI launched with `whale`, a one-shot CLI mode via `whale ask "..."`, and a headless mode for CI/CD, automated PR reviews and scheduled tasks.

The intended user is someone who already works in a shell and already has a DeepSeek API key. The README is unusually direct about scope. Under Non-goals it states that Whale is not a "multi-model shell" and is not an IDE replacement. That is a real constraint rather than marketing modesty: if your team standardises on one vendor's models, or you want the agent embedded in an editor, this project is pointed elsewhere.

The project status section says Whale is in active development and is "best suited for personal projects, experimental repositories, and workflows where changes can be reviewed and rolled back." Treat that sentence as the honest boundary of the tool. It is a statement from the maintainers, not a third-party assessment, and it should shape where you point the agent first.

How the DeepSeek caching and context story actually works

The headline claim is a prompt cache hit rate of roughly 98%, repeated in the README badge and the At a Glance table. The mechanism described is context reuse: Whale "reuses cached context aggressively", so most prompts hit the provider's cache and the cost per session drops. DeepSeek's own API is where the caching happens; Whale's contribution is ordering and structuring the conversation so that the stable prefix stays stable.

That design has a consequence worth naming. Anything that shuffles the front of the prompt, such as reordering system instructions or injecting volatile data early, would break the cached prefix and cost you the discount. The README does not document how Whale arranges its prompt segments, so the cache rate is a claim you can only check against your own usage once you are running it.

The dependency list in `go.mod` shows the shape of the thing: Bubble Tea, Lip Gloss and Glamour for the TUI, Cobra for the CLI, the official Model Context Protocol Go SDK, `fastschema/qjs` for QuickJS bindings, and `tetratelabs/wazero` as a pure-Go WebAssembly runtime. This is a single Go binary with an embedded JavaScript engine, not a wrapper around another agent.

Installing Whale and running a first session

The README gives one install path that works anywhere, plus platform-specific ones. The npm route is the broadest:

npm install -g @usewhale/whale

On macOS the project publishes a Homebrew tap, and on Linux there is a shell installer that pipes a script from the repository into `sh`:

brew install usewhale/tap/whale
curl -fsSL https://raw.githubusercontent.com/usewhale/Whale/main/scripts/install.sh | sh

Windows users get a PowerShell installer, which the README notes requires Windows 10 or Windows Server 2016 or later. Once the binary is on your PATH, configuration is a single command that stores your DeepSeek API key:

whale setup

After that, running `whale` with no arguments launches the interactive TUI. The README's description of the first session is that you type a question and the agent starts reading files, running commands, editing code and searching the web. The `whale ask` form is the one-shot equivalent for quick questions or a single code review, and `whale --headless` is the mode aimed at pipelines. If you need a different provider, a proxy, or custom configuration, the README points to `docs/configuration.en.md` rather than describing the options inline.

Dynamic Workflows: JavaScript orchestration, off by default

The most distinctive feature is Dynamic Workflows. You write JavaScript that orchestrates several agents, and the README's example is a fan-out pattern: two agents research a topic in parallel, then a third synthesises their output.

// .whale/workflows/research.js
const results = await parallel([
  () => agent("Search for best practices in Go error handling"),
  () => agent("Find common Go error handling mistakes"),
]);
return agent("Synthesize both findings into a concise guide");

The README claims compatibility with Claude Code workflow scripts, meaning a script written for that tool should run as-is here. The QuickJS dependency in `go.mod` is what executes these scripts inside the Go binary.

Two things stand out. First, the feature is disabled by default. You enable it either by running `/config` in the TUI and turning on Dynamic workflows, or by adding a line to a local config file:

[workflows] enabled = true

Second, the README does not describe resource limits, timeouts, or what happens when a fan-out spawns more agents than intended. A JavaScript engine embedded in your coding agent, running scripts that can call tools and spend API budget, is a surface you should enable deliberately rather than by default.

Extensions, MCP servers and what the docs leave open

Beyond workflows, Whale supports MCP servers, skills, subagents, plugins and hooks, each with its own document under `docs/`. The README points at the MCP page for connecting to what it describes as 1,000+ tools covering databases, APIs and browser automation, and the Go SDK dependency confirms the protocol support is first-party rather than bolted on.

Skills and plugins are installable from a community pool; the repository root contains a `skills-lock.json`, which suggests installed skills are pinned to specific versions. That is a reasonable design for reproducibility, though the README does not explain how updates to a locked skill are surfaced.

Where the documentation is thin is failure behaviour. Nothing in the project's own documentation describes what happens when an MCP server crashes mid-session, when a hook script exits non-zero, or when a subagent loops. For a tool whose stated audience is experimental repositories, the absence of documented rollback semantics is the gap I would want closed first. The README does not document rollback.

How Whale differs from a general-purpose agent CLI

The obvious comparison is a multi-provider agent such as Aider or the various CLI agents that let you swap between Anthropic, OpenAI and local models. The difference is architectural rather than cosmetic. Those tools abstract over providers, which means they cannot assume a specific caching implementation or a specific context ceiling. Whale assumes both: the prompt-cache badge and the 1M-token context figure are DeepSeek-specific properties, and the README explicitly refuses the multi-model role.

That trade is coherent. You give up provider portability and in exchange the agent can be tuned to one API's caching behaviour, which is where the cost argument lives. If DeepSeek's pricing or availability changes, or your organisation mandates a different provider, you are starting over with a different tool.

A second comparison point is the workflow scripting. Agents that only expose a chat loop cannot express fan-out research or adversarial validation as a script. Whale's QuickJS runtime can, and the claimed Claude Code script compatibility lowers the cost of trying it. The catch is that this capability is off until you enable it, so a new user may never encounter the feature the project is most known for.

Licence, maintenance and upgrade cost

Whale is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence with few obligations, but it also means no warranty and no support commitment from the authors. Nothing in the repository suggests a CLA or a dual-licensing arrangement, and the README carries a disclaimer that the project is not affiliated with DeepSeek Inc. and is an independent community effort.

On maintenance: the repository is not archived, and the last push was on 2026-08-11, the same day release v0.1.66 was tagged. Releases v0.1.64 and v0.1.65 landed on 2026-08-05 and 2026-08-06, so the cadence around that period was roughly daily. That is a fast-moving project, which cuts both ways. You get fixes quickly, and you also get a moving target.

Upgrade cost is low if you install through npm or Homebrew, since both handle version resolution for you. It is higher if you use the curl installer, which pulls whatever is current on `main`. The `Makefile` shows the project's own release path uses a version injected at link time via `-X github.com/usewhale/whale/internal/build.Version=$(VERSION)`, so a locally built binary reports whatever version you pass. If you build from source, pin a tag rather than tracking the default branch.

Editorial conclusion

Adopt Whale if you already pay for DeepSeek and want an agent in the terminal rather than an IDE plugin, and start with a repository you can roll back. Do not adopt it if you need a single tool that fronts several model providers, since the README lists multi-model support as an explicit non-goal. Before trusting it on anything you care about, verify two things yourself: that your DeepSeek key and proxy settings survive `whale setup`, and that the workflow runtime stays disabled until you deliberately turn it on.

Frequently asked questions

Official sources

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