Whale

Whale

简体中文 · English

Blazingly fast · ~98% prompt cache hit · Zero bloat

Whale — AI coding agent for DeepSeek, in any environment. Long context, tools, and programmable workflows — start in the terminal, scale to desktop and beyond.

---

🚀 Quick Start

Any platform:

npm install -g @usewhale/whale

macOS:

brew install usewhale/tap/whale

Linux:

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

Windows PowerShell:

Requires Windows 10 or Windows Server 2016 or later.

irm https://raw.githubusercontent.com/usewhale/Whale/main/scripts/install.ps1 | iex

Windows CMD:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/usewhale/Whale/main/scripts/install.ps1 | iex"

# Set your DeepSeek API key
whale setup

# Launch the interactive TUI
whale

That's it. Type your question and Whale starts working — reading files, running commands, editing code, searching the web.

> Need a different model provider, proxy, or custom config? See [Configuration](docs/configuration.en.md).

---

✨ At a Glance

| What | Why it matters | |---|---| | 💰 ~98% prompt cache hit | Whale reuses cached context aggressively — most prompts hit cache, slashing costs to pennies per session. DeepSeek pricing × Whale caching = AI-assisted coding at scale. | | 🐋 DeepSeek-native | Built for DeepSeek's long context (1M tokens), tool calling, and cost efficiency — no generic multi-model wrapper | | 🔁 Dynamic Workflows | Write JavaScript scripts that orchestrate multiple agents — fan-out research, multi-perspective review, pipelines. Claude Code compatible. | | 🔌 MCP | Plug in 1,000+ MCP servers for extended tooling — file ops, shell, git, web, and more | | 🧩 Skills + Plugins | Install community skills (code review, git workflows, etc.) or write your own |

---

🔁 Dynamic Workflows

Whale's Dynamic Workflows let you script multi-agent orchestration in JavaScript:

// .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");

Fan-out research · Multi-perspective review · Pipeline processing · Adversarial validation

> ✅ Claude Code compatible — workflow scripts written for Claude Code work as-is in Whale.

> ⚠️ Disabled by default — run /config in the TUI and enable Dynamic workflows, or add [workflows] enabled = true to .whale/config.local.toml.

Learn more: [Workflow Overview](docs/workflows.en.md) · [Custom Workflow Guide](docs/custom-workflows.en.md)

---

🧰 MCP, Skills & Plugins

| Extension | What it does | Get started | |---|---|---| | MCP Servers | Connect to 1,000+ tools (databases, APIs, browser automation) | [docs/mcp.en.md](docs/mcp.en.md) | | Skills | Load domain expertise — code review, git-worktree, and more | [docs/skills.en.md](docs/skills.en.md) | | Subagents | Define focused child-agent roles such as reviewers or researchers | [docs/agents.en.md](docs/agents.en.md) | | Plugins | Extend Whale's runtime with custom logic | [docs/plugins.en.md](docs/plugins.en.md) | | Hooks | Run scripts on lifecycle events | [docs/hooks.en.md](docs/hooks.en.md) |

---

📸 How It Works

Whale currently offers three interfaces — with more environments on the way:

| Interface | When to use | |---|---| | whale (TUI) | Interactive coding sessions — chat, review, iterate with full context | | whale ask "..." (CLI) | One-shot questions, quick code reviews, single commands | | whale --headless | CI/CD, automated PR reviews, scheduled tasks |

---

🎯 Non-goals

• Multi-model shell. Whale is DeepSeek-first — optimized for DeepSeek's caching, tools, and pricing.
• IDE replacement. Whale is not an IDE — it's an agent that meets you wherever you code: terminal, desktop, or CI.

📦 Project Status

Whale is in active development. Best suited for personal projects, experimental repositories, and workflows where changes can be reviewed and rolled back.

> Disclaimer: This project is not affiliated with DeepSeek Inc. It is an independent open-source community project.

---

🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, testing, issues, and PRs.

Current direction and available tasks: [ROADMAP.md](ROADMAP.md).

Security issues: [SECURITY.md](SECURITY.md).

---

Star History

---

🙏 Credits

Whale stands on the shoulders of giants:

• Charmbracelet — Bubble Tea, Lip Gloss, Glamour, and the entire TUI ecosystem
• fastschema/qjs — QuickJS Go bindings for workflow scripting
• spf13/cobra — CLI framework
• alecthomas/chroma — Syntax highlighting
• yuin/goldmark — Markdown parsing
• modelcontextprotocol/go-sdk — MCP protocol support
• tetratelabs/wazero — Pure-Go WebAssembly runtime

And the many open-source libraries we depend on — thank you.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: usewhale
• Source: usewhale/Whale
• License: MIT
• Homepage: https://whale-site.pages.dev

Install and usage instructions live in the source repository linked above.