usewhale/Whale

Whale — blazingly fast, terminal-first AI coding agent for DeepSeek. ~98% prompt cache hit rate, 1M context, MCP tools, dynamic workflows. - usewhale/Whale

910 stars · 66 forks · Go Topics: go, terminal, skills, mcp, llm, deepseek, coding-agent, deepseek-agent, deepseek-cli, deepseek-coding-agent

README

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

Launch the interactive TUI

Need a different model provider, proxy, or custom config? See Configuration.

✨ 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 · Custom Workflow Guide

🧰 MCP, Skills & Plugins

Extension What it does Get started

MCP Servers Connect to 1,000+ tools (databases, APIs, browser automation) docs/mcp.en.md

Skills Load domain expertise — code review, git-worktree, and more docs/skills.en.md

Subagents Define focused child-agent roles such as reviewers or researchers docs/agents.en.md

Plugins Extend Whale's runtime with custom logic docs/plugins.en.md

Hooks Run scripts on lifecycle events 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 for local development, testing, issues, and PRs. Current direction and available tasks: ROADMAP.md. Security issues: 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