Codewhale is an open-source agent that helps you build software, work with your files, and automate everyday tasks using the models you choose. Start with a task in your terminal, connect a hosted or local model, and bring in a team of agents when you want to share a larger job across different models and roles.
简体中文 · 日本語 · Tiếng Việt · Bahasa Indonesia · 한국어 · Español · Português · Русский · Українська · Français · Deutsch · 繁體中文 · हिन्दी · Türkçe · Italiano · Polski · العربية · Català
macOS / Linux — install the official GitHub release:
curl -fsSL https://codewhale.net/install.sh | sh
"$HOME/.local/bin/codewhale"Windows: download the matching installer or archive from
GitHub Releases.
For an existing direct install, run codewhale update (or codewhale update --check
to inspect it). The updater prints the executable path and keeps newer builds.
The first run helps you connect a provider or stay offline. Codewhale also supports npm and Cargo as secondary packaging routes, plus Docker, Nix, Scoop, Android/Termux, and an optional CNB mirror. Existing package-managed installs receive migration instructions. See installation and PATH help.
Tab completion is one command per shell — codewhale completion bash|zsh|fish|powershell|elvish.
See shell completions.
Talk to Codewhale the same way you would talk to a teammate:
Fix the failing tests and explain what changed.
Or run a task without opening the TUI:
codewhale exec "fix the failing tests and explain what changed"Codewhale can read your repository, edit files, run commands, inspect results, and keep working toward a goal. You decide how much access it has.
Prefer a graphical interface? The community-maintained CodeWhale for VS Code extension wraps the same agent in a VS Code sidebar — chat, threaded conversations, live diffs, and task management over the same Runtime API, so sessions stay in sync with the terminal. Install it from the VS Code Marketplace; source code is on GitHub.
- Choose your models. Connect hosted providers or local models through
Ollama, vLLM, or SGLang. Use
/providerto change providers and/modelto choose a model. - Stay in control. Plan is read-only. Ask, Auto-Review, and Full Access make
approval behavior visible.
/undoreverts the last turn and/restorereturns the workspace to an earlier snapshot. - Keep long work organized. Save sessions, set a durable
/goal, review workflows before they run, and coordinate agents without turning their internal instructions into your transcript. - Extend the agent you already have. Connect MCP servers and skills, configure hooks, and keep agent roles as readable files in your project or personal settings.
Run /help in the TUI for commands and keyboard shortcuts.
Codewhale runs on your machine with the access you grant it. Approval modes and repository rules limit what the agent may do; optional OS sandboxing adds a stronger execution boundary where supported. Unknown model prices stay unknown instead of being reported as free.
Read authorization order for the exact policy stack and configuration for local settings.
- Providers and local models
- Agent teams
- MCP, hooks, and configuration
- Local web client
- All documentation
Bug reports, feature ideas, and pull requests are welcome, whether you have used Codewhale for months or are trying it for the first time. If a provider is missing, a workflow is awkward, or the terminal UI gets in your way, open an issue or send a pull request so we can improve it together. We welcome first contributions, and contributors keep credit for the work that lands.
Join the Discord, or add Hunter on WeChat
(hunterbown) and ask to join the Whale Brothers group.
Codewhale began as deepseek-tui and still preserves that configuration and
session compatibility. It is now provider-neutral and independently maintained;
it is not affiliated with any model provider.
Thanks to every contributor and to the open source communities that helped the project grow. See the contributor record.
MIT. Portions adapted from other open-source projects are recorded in third-party notices.