whale

README

Whale

简体中文 · English

A terminal-native coding agent built for DeepSeek.
Persistent sessions, long context, tools, and programmable workflows —
all in your terminal, no IDE required.

---

✨ At a Glance

What	Why it matters
🐋 DeepSeek-native	Built for DeepSeek's long context (1M tokens), tool calling, and cost efficiency — no generic multi-model wrapper
💬 Persistent sessions	Come back days later, context is still there. Search, branch, resume.
🎛️ TUI + CLI + Headless	Interactive TUI, one-shot CLI commands, or headless automation — pick your mode
⚙️ Tools & MCP	Read/edit files, run commands, search web — and plug in 1,000+ MCP servers
🧩 Skills + Plugins	Install community skills (code review, git workflows, etc.) or write your own
🔁 Dynamic Workflows	Write JavaScript scripts that orchestrate multiple agents — fan-out research, multi-perspective review, pipelines. Claude Code compatible.
💰 Cost-efficient	DeepSeek's aggressive pricing paired with prompt caching makes AI-assisted coding affordable at scale

---

🚀 Quick Start

Platform	Install
macOS	brew install usewhale/tap/whale
Linux	`curl -fsSL https://raw.githubusercontent.com/usewhale/DeepSeek-Code-Whale/main/scripts/install.sh
Windows	`powershell -c "irm https://raw.githubusercontent.com/usewhale/DeepSeek-Code-Whale/main/scripts/install.ps1

# 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.

---

🔁 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.

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
Plugins	Extend Whale's runtime with custom logic	docs/plugins.en.md

---

📸 How It Works

Whale runs in three modes:

Mode	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 works in your terminal alongside your shell, git, and test commands.

📦 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