Whale
A DeepSeek-first terminal coding agent with long context, tools, and programmable workflows.
- Source repo
- usewhale/Whale
- Stars
- ★ 931
- Last updated
- 23d ago
- License
- MIT
- Primary language
- Go
- FA score
- 51/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificClaude Code (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer using the DeepSeek API who wants a terminal agent to inspect repository files, execute commands, and edit code.
- Not a fit if
- Teams that need provider-agnostic multi-model support or OpenAI/Claude APIs
- Users who want everything on by default, not workflows disabled by default
- Production teams that need stability, not an actively developed project
- Source review
- 51/100 · Major gaps
What does this agent do, and when should you use it?
Whale is a terminal-first AI coding agent built for DeepSeek rather than a general multi-model shell. It offers an interactive whale TUI, one-shot whale ask "..." commands, and whale --headless for CI/CD and automated work. The agent can read files, run commands, edit code, and search the web, with extensions through MCP servers, Skills, Subagents, Plugins, and Hooks. Its JavaScript-based Dynamic Workflows orchestrate multiple agents for fan-out research, review, and pipeline-style processing. The project is under active development and is positioned for personal projects, experimental repositories, and workflows where changes can be reviewed and rolled back.
After a DeepSeek API key is configured, whale starts an interactive TUI where the agent can read files, run commands, edit code, and search the web. whale ask "..." handles one-shot questions, quick code reviews, or single-command work, while whale --headless targets CI/CD, automated PR reviews, and scheduled tasks. MCP Servers can connect tools such as databases, APIs, and browser automation; Skills, Subagents, Plugins, and Hooks add domain behavior and lifecycle scripting. When Dynamic Workflows are enabled, JavaScript files in .whale/workflows/ can use parallel and agent to run multiple tasks and synthesize their results.
- A developer using the DeepSeek API who wants a terminal agent to inspect repository files, execute commands, and edit code.
- An engineer needing a quick, single-turn code review or answer through
whale ask "...". - A team running automated PR reviews, scheduled jobs, or other non-interactive tasks through
whale --headlessin CI/CD. - A developer who needs databases, APIs, or browser automation available to a coding workflow through MCP Servers.
- A user who wants to fan out research or multi-perspective review work in JavaScript and then synthesize the results with another agent.
How do you install or deploy this agent?
On any platform, run npm install -g @usewhale/whale. On macOS, you can instead run brew install usewhale/tap/whale. Then run whale setup to set a DeepSeek API key and start the interactive TUI with whale. For Linux, the documented command is curl -fsSL https://raw.githubusercontent.com/usewhale/Whale/main/scripts/install.sh | sh. For Windows 10, Windows Server 2016, or later, run irm https://raw.githubusercontent.com/usewhale/Whale/main/scripts/install.ps1 | iex in PowerShell.
How do you use this agent?
Run whale after whale setup, then enter a task in the TUI. For a one-shot request, use whale ask "Review this code"; for automation, use whale --headless. Dynamic Workflows are disabled by default: enable Dynamic workflows through /config in the TUI, or add [workflows] enabled = true to .whale/config.local.toml.
What are this agent's strengths and limitations?
- It is explicitly optimized around DeepSeek long context, tool calling, and caching; the README reports an approximately 98% prompt-cache hit rate.
- It exposes interactive TUI, one-shot CLI, and headless automation interfaces for local and CI/CD use.
- Dynamic Workflows provide JavaScript multi-agent orchestration and are documented as compatible with Claude Code workflow scripts.
- MCP Servers, Skills, Subagents, Plugins, and Hooks offer several distinct extension mechanisms.
- Whale is DeepSeek-first rather than a provider-agnostic multi-model tool, and setup requires a DeepSeek API key.
- Dynamic Workflows are disabled by default and require explicit activation through
/configor.whale/config.local.toml. - The project is in active development; its README recommends personal projects, experimental repositories, and workflows with reviewable, reversible changes.
- The supplied documentation does not describe native integrations for ChatGPT, Codex, the OpenAI API, or the Claude API.
How does this agent compare with similar options?
Whale explicitly rejects the role of a general multi-model shell and instead positions itself as DeepSeek-first. It states that Claude Code workflow scripts run unchanged in Whale, but that compatibility is for workflow scripts rather than evidence of a complete Claude Code product integration.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Whale This agent | 51 · Major gaps | CLIFree + model costs | ★ 931 | 23d ago | Go | — |
| Kode CLI | 44 · Major gaps | CLIFree + model costs | ★ 5.2k | 3d ago | TypeScript | OpenAI API · Claude API |
| Reasonix | 66 · Some gaps | CLIFree + model costs | ★ 36k | today | Go | OpenAI API |
| Deep Code CLI | 49 · Major gaps | CLIFree + model costs | ★ 2.2k | 1d ago | TypeScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README mentions user approval and hooks executing shell commands, SECURITY.md indicates credential file location and DEEPSEEK_API_KEY precedence, but lacks detailed least-privilege model, data flow transparency, or external impact assessment. Deductions: missing specific permission model, data flow explanation, and external impact evaluation.
Evidence shows: README and CI config are consistent, dependency list is complete, but failure messages are not documented. Deductions: insufficient failure handling documentation.
Evidence shows: README clearly defines target audience (developers) and use cases (terminal, CI), lists non-goals (multi-model, IDE replacement), but trigger precision (e.g., command trigger conditions) is not detailed. Deductions: insufficient trigger condition documentation.
Evidence shows: README structure is clear, installation instructions are detailed, examples and known limitations are present, MIT license is explicit, but version changelog is missing and maintenance responsibility is unclear. Deductions: missing changelog and maintenance responsibility statement.
Evidence shows: README emphasizes output usability (TUI, CLI, headless), marginal value (caching, DeepSeek-native), cost-benefit (cache reduces costs), but lacks concrete data or comparisons. Deductions: lack of empirical data.
Evidence shows: Claims in README (e.g., 98% cache hit rate) lack sources, CI config exists but not verified, facts and inferences are not clearly separated. Deductions: claims lack traceability, facts and inferences not distinguished.
- Publisher identity is unverified; treat with caution.
- Performance claims in README (e.g., 98% cache hit rate) lack verifiable sources.
- Security boundary documentation (SECURITY.md) mentions hooks can execute shell commands, but lacks specific permission control details.
- Version changelog is missing, and maintenance responsibility is unclear.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
v0.1.66 Summary This release sharpens the TUI and hardens the ACP/MCP runtime: 1. ACP session lifecycle — session/delete so Zed's Trash actually removes whale threads, plus permission options constrained to the ACP schema enum so approvals are never silently dropped. 2. Agent turn reliability — an "execute, don't narrate" system block plus wider premature-end recovery catches announce-then-stop turns across the ACP, terminal CLI, and subagents; abrupt turns recover with interrupt tracing. …View on GitHub ↗ -
Release notes excerpt
v0.1.65 Summary This release hardens the ACP (Agent Client Protocol) runtime and the agent turn loop: 1. ACP reliability overhaul — proper model resolution and API transport selection for whale-acp, automatic session compaction at a safe threshold, a raised tool-iteration cap, session/list support so Zed shows previous sessions, and no more mid-prompt eviction of sessions with in-flight requests. …View on GitHub ↗ -
Release notes excerpt
v0.1.64 Summary This release brings two significant improvements: 1. whale exec session resume & explicit mode control — resume existing sessions, override the execution mode (agent/ask/plan), and get strict, machine-parseable session validation with unified JSON error output. Built for automation workflows (CI, SWE-bench) with zero side effects on failed pre-checks. 2. TUI Alt+P permission cycle shortcut — cycle the permission mode directly from the chat view (ask → auto-review → auto-accept → ask) and always see the current permission state in the footer. …View on GitHub ↗
FAQ
What credentials do I need?
whale setup.Can it run in automation?
whale --headless for CI/CD, automated PR reviews, and scheduled tasks.Are Dynamic Workflows enabled automatically?
/config or set [workflows] enabled = true in .whale/config.local.toml.