Codewhale, formerly DeepSeek TUI, is a free and open-source terminal coding agent and agent harness for hosted and local models.
It reads repositories, edits files, runs commands, checks its work, and records the result from a TUI, a headless command, a loopback web client, or the local Runtime API.
The project changed its name from DeepSeek TUI to Codewhale in the v0.8.x release line. The current command iscodewhale, withcodewas a shorter alias. The legacy DeepSeek TUI npm path is deprecated. Use the Codewhale name for new installs, scripts, and documentation.
Its main distinction as a Claude Code alternative is model choice. DeepSeek remains the bundled default, while the same MIT-licensed harness can run Claude, GPT, Kimi, GLM, other hosted routes, or models served through Ollama, vLLM, and SGLang.
Codewhale has no license fee and requires no Codewhale account. Hosted inference uses the billing and credentials of the provider you select.
A local Ollama, vLLM, or SGLang route can run without an API key when you supply the model and hardware.
For the DeepSeek provider, see the latest DeepSeek API pricing before starting long agent sessions.
Features
- Runs as a terminal coding agent through the TUI or
codewhale exec. - Reads and edits files, runs shell commands, works with git, searches the web, applies patches, and connects to MCP servers.
- Separates Plan, Act, and Operate modes from Ask, Auto-Review, and Full Access permission postures.
- Uses a local provider-aware heuristic for
--model autounless you explicitly configure a routing provider and model. - Runs DeepSeek, Claude, GPT, Kimi, GLM, OpenAI-compatible services, and local Ollama, vLLM, or SGLang routes through one harness.
- Streams supported reasoning output and records route, token, cache, and cost information when the provider returns it.
- Saves sessions, resumes or forks earlier work, records turn receipts, and creates rollback checkpoints outside your repository’s own
.gitdirectory. - Uses Fleet for durable multi-agent work and Workflow for ordered phases, gates, and background runs.
- Applies a bundled Constitution, optional user rules, and repository rules through a defined authority order.
- Loads reusable skills from Codewhale and compatible agent directories.
- Works as an MCP client and server for trusted external actions and data.
- Exposes a loopback-only web client, authenticated Runtime API, ACP adapter, and headless execution surface.
- Surfaces LSP diagnostics after edits for supported language servers.
Use Cases
- Inspect an unfamiliar repository in Plan mode before allowing file or shell changes.
- Implement and verify code changes in Act mode with approval gates.
- Coordinate independent or long-running work through Fleet workers in Operate mode.
- Run repeatable background phases from saved Workflow files.
- Resume repository work with saved sessions, receipts, and file checkpoints.
- Use hosted model APIs or keep inference local through Ollama, vLLM, or SGLang.
- Open the local web client or connect an editor through ACP and the Runtime API.
Codewhale vs Claude Code
Both products inspect repositories, edit files, run commands, and manage multi-step coding work. Codewhale is an independent MIT-licensed harness that accepts hosted and local model routes. Claude Code is Anthropic’s coding agent and centers its product experience on Claude models and Anthropic account paths.
| Codewhale | Claude Code | |
|---|---|---|
| Product type | Open-source terminal coding agent and agent harness | Anthropic agentic coding product across terminal, IDE, desktop, and browser |
| Model route | Hosted or local model | Claude models only |
| Access | MIT-licensed | Claude subscription, Anthropic Console, or supported cloud provider access |
| Controls | Plan, Act, Operate, permission postures, Constitution, Fleet, and Workflow | Claude Code permissions, hooks, subagents, skills, plugins, and Anthropic product integrations |
How to Use It
Installation
The npm wrapper is the shortest cross-platform install and requires Node.js 18 or newer. The official shell installer is available for macOS and Linux. Cargo installations need both packages because the dispatcher and TUI are separate binaries.
# npm
npm install -g codewhale
# macOS or Linux installer
curl -fsSL https://codewhale.net/install.sh | sh
# Cargo: requires Rust 1.88 or newer
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked
# Homebrew: legacy tap name
brew tap Hmbown/deepseek-tui
brew install deepseek-tui
# Check for a newer release
codewhale updateRelease archives are published for Linux x64, Linux ARM64, Android ARM64 for Termux, macOS x64, macOS ARM64, Windows x64, and Windows ARM64. The Windows downloads include installer and portable options. Verify manual downloads with the release checksum manifest.
The current Windows installer is unsigned and can trigger Microsoft SmartScreen. The portable archive runs from an extracted directory, while install.bat copies the archive build to your user binary directory.Migrating from DeepSeek TUI
Install Codewhale if you previously used DeepSeek TUI. New instructions and scripts should use the codewhale command and npm package. The legacy npm package receives no new releases, although the old commands and ~/.deepseek/ state remain available as compatibility paths.
| Before | Now | Migration Note |
|---|---|---|
| DeepSeek TUI | Codewhale | The project and repository now use the Codewhale name. |
deepseek | codewhale or codew | Use the Codewhale command in new scripts. The old command remains a compatibility shim. |
deepseek-tui npm package | codewhale npm package | Use the new npm wrapper for fresh installs and upgrades. The old npm package is deprecated. |
~/.deepseek/ | ~/.codewhale/ | New installs write Codewhale-owned state to the new root; legacy state remains readable as a fallback. |
.deepseek/config.toml | .codewhale/config.toml | The Codewhale project overlay takes precedence when both files exist. |
Run the doctor command after an upgrade. It reports the active state root and can identify a legacy state directory that still needs review.
codewhale doctorAuthentication
You can open Codewhale and explore in Plan mode without an API key. Model replies require a configured route. Use a hosted provider credential or connect a keyless local runtime such as Ollama, vLLM, or SGLang.
codewhale auth set --provider deepseek
codewhale auth status
# Environment variable alternative
export DEEPSEEK_API_KEY="YOUR_KEY"
codewhale auth clear --provider deepseek
codewhale doctor
codewhale doctor --jsonA key saved through the authentication command takes precedence over the environment variable. Codewhale stores current state under ~/.codewhale/ and reads legacy ~/.deepseek/ state during migration. The doctor command is offline by default. Add an explicit probe flag when you want it to contact a provider, local endpoint, MCP server, or update service.
Starting a Session
First launch opens a short Constitution setup before the full interface. New sessions use Act unless you select a different default. Start in the repository you want Codewhale to inspect, then use /provider and /model to confirm the active route.
codewhale # open the interactive TUI
codew # short dispatcher alias
codewhale exec "fix this test failure" # run a headless task
codewhale --model deepseek-v4-flash # select a fixed model
codewhale --model auto # use automatic routing
codewhale --continue # resume recent workspace work
codewhale web # open the loopback web clientAuto Routing
--model auto uses a local provider-aware heuristic by default and does not send a separate routing request. You can explicitly configure an [auto.router] provider and model when you want classifier-based routing. If that classifier fails, Codewhale returns to the local heuristic.
Select a fixed model for repeatable comparisons, a strict provider boundary, or a task where a separate classifier request is unwanted.
Modes and Permissions
Press Tab while the composer is idle to cycle modes. Press Shift+Tab to cycle Ask, Auto-Review, and Full Access. Plan always stays read-only. Full Access belongs only in a trusted, recoverable workspace.
| Mode | Behavior | Use |
|---|---|---|
| Plan | Read-only repository investigation | Explore and prepare a change |
| Act | Normal coding through the active permission posture | Edit, test, and review work |
| Operate | Direct work with an emphasis on Fleet coordination | Parallel or long-running tasks |
Reasoning Effort
Reasoning settings belong to the selected model route and remain separate from mode and permission posture. Use the model controls to inspect or change the available reasoning level. A provider that does not expose a requested level keeps its own capability boundary.
Session Management
codewhale sessions # list saved sessions
codewhale --continue # resume the latest workspace session
codewhale --resume <SESSION_ID> # resume a selected session
codewhale fork <SESSION_ID> # begin a branch from saved workPress Ctrl+R to open the session picker and press r to rename the selected session. Codewhale stores normal saves in its managed session area and does not add session_*.json files to your repository. Runtime clients can also save completed threads through the managed session API. Explicit exports to a chosen path still work.
The rollback system stores checkpoints in Codewhale-managed state and does not write into your project’s own .git directory. Inspect available restore snapshots with /restore list before choosing a target.
The /restore command and revert_turn roll back workspace file changes from a selected turn. GUI and runtime clients can use undo, patch undo, retry, and snapshot restore endpoints when those clients expose the corresponding controls. This keeps rollback state under the Codewhale state root.
Goals, Receipts, Fleet, and Workflow
Use /goal to create or inspect the current objective. Codewhale keeps task state visible without changing the active mode or permission posture.
Fleet stores durable worker roles and execution state for independent tasks. Workflow defines ordered phases and gates, and saved *.workflow.js files can appear as slash commands. Completed work leaves receipts that record the route, actions, and verification evidence available for that run.
Available Commands
| Command | Purpose |
|---|---|
codewhale | Launch the interactive TUI. |
codew | Launch Codewhale through the short alias. |
codewhale "prompt" | Run a one-shot prompt. |
codewhale exec "prompt" | Run a non-interactive task for scripts or CI. |
codewhale --model auto | Auto-select the model and supported reasoning behavior. |
codewhale web | Open the loopback-only browser client. |
codewhale auth set --provider deepseek | Save a DeepSeek API key. |
codewhale auth status | Show the active credential source. |
codewhale auth clear --provider deepseek | Remove a saved DeepSeek key. |
codewhale doctor | Inspect configuration and recovery state offline by default. |
codewhale doctor --json | Output machine-readable diagnostics. |
codewhale setup --status | Display read-only setup status. |
codewhale setup --tools --plugins | Scaffold tool and plugin directories. |
codewhale mcp list | List configured MCP servers. |
codewhale mcp validate | Validate MCP configuration and connectivity. |
codewhale mcp | Expose Codewhale as an MCP server. |
codewhale update | Check for and apply binary updates. |
Keyboard Shortcuts
| Key | Action |
|---|---|
Tab | Complete entries or cycle Plan, Act, and Operate while idle. |
Shift+Tab | Cycle Ask, Auto-Review, and Full Access. |
F1 | Open help. |
Esc | Dismiss the active overlay. |
Ctrl+R | Open the saved session picker. |
Alt+R | Search prompt history. |
Ctrl+S | Send a queued follow-up immediately. |
@path | Attach file or directory context. |
Provider Configuration
# Official DeepSeek API
codewhale auth set --provider deepseek
codewhale --provider deepseek --model deepseek-v4-flash
# NVIDIA NIM
codewhale auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"
codewhale --provider nvidia-nim
# Native Anthropic route
codewhale auth set --provider anthropic --api-key "YOUR_ANTHROPIC_API_KEY"
codewhale --provider anthropic --model claude-sonnet-4-6
# Experimental OpenAI Codex OAuth route
OPENAI_CODEX_AUTH_FILE="$HOME/.codex/auth.json" codewhale --provider openai-codex --model gpt-5.5
# AtlasCloud
codewhale auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY"
codewhale --provider atlascloud
# Wanjie Ark
codewhale auth set --provider wanjie-ark --api-key "YOUR_WANJIE_API_KEY"
codewhale --provider wanjie-ark --model deepseek-reasoner
# OpenRouter
codewhale auth set --provider openrouter --api-key "YOUR_OPENROUTER_API_KEY"
codewhale --provider openrouter --model deepseek/deepseek-v4-pro
# Novita
codewhale auth set --provider novita --api-key "YOUR_NOVITA_API_KEY"
codewhale --provider novita --model deepseek/deepseek-v4-pro
# Fireworks
codewhale auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"
codewhale --provider fireworks --model deepseek-v4-pro
# Together AI
codewhale auth set --provider together --api-key "YOUR_TOGETHER_API_KEY"
codewhale --provider together --model deepseek-ai/DeepSeek-V4-Flash
# Hugging Face Inference Providers
codewhale auth set --provider huggingface --api-key "YOUR_HF_TOKEN"
codewhale --provider huggingface --model deepseek-ai/DeepSeek-V4-Flash
# Generic OpenAI-compatible endpoint
codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"
OPENAI_BASE_URL="YOUR_OPENAI_COMPATIBLE_BASE_URL" codewhale --provider openai --model glm-5
# Local or self-run endpoints
SGLANG_BASE_URL="http://localhost:30000/v1" codewhale --provider sglang --model deepseek-v4-flash
VLLM_BASE_URL="http://localhost:8000/v1" codewhale --provider vllm --model deepseek-v4-flash
ollama pull codewhale-coder:1.3b
codewhale --provider ollama --model codewhale-coder:1.3bKey Environment Variables
| Variable | Purpose |
|---|---|
CODEWHALE_HOME | Override the current Codewhale state root. |
CODEWHALE_CONFIG_PATH | Override the current Codewhale configuration path. |
DEEPSEEK_API_KEY | Supply the API key for the official DeepSeek provider. |
DEEPSEEK_BASE_URL | Override the DeepSeek API base URL. |
DEEPSEEK_MODEL | Set the default DeepSeek model. |
DEEPSEEK_PROVIDER | Select the active provider route. Recent builds keep DeepSeek compatibility while adding broader provider registry support. |
DEEPSEEK_PROFILE | Select a saved provider profile. |
ANTHROPIC_API_KEY | Supply credentials for the native Anthropic Messages API route. |
OPENAI_CODEX_AUTH_FILE / CODEX_HOME | Point the experimental OpenAI Codex provider to an existing Codex OAuth login. |
OPENAI_BASE_URL / OPENAI_MODEL | Set a generic OpenAI-compatible endpoint and model. |
TOGETHER_API_KEY / TOGETHER_BASE_URL / TOGETHER_MODEL | Configure the Together AI provider route. |
HUGGINGFACE_API_KEY / HF_TOKEN | Configure the Hugging Face provider route. |
MIMO_MODE / XIAOMI_MIMO_MODE | Select Xiaomi MiMo Token Plan or pay-as-you-go routing where supported. |
ATLASCLOUD_API_KEY / WANJIE_ARK_API_KEY | Supply credentials for additional hosted provider paths. |
OPENROUTER_API_KEY / NOVITA_API_KEY / FIREWORKS_API_KEY | Supply credentials for the respective hosted providers. |
CODEWHALE_SEARCH_BASE_URL | Point web search to a DuckDuckGo-compatible private endpoint. |
SGLANG_BASE_URL | Set a self-run SGLang endpoint. |
VLLM_BASE_URL | Set a self-run vLLM endpoint. |
OLLAMA_BASE_URL | Set an Ollama endpoint. |
NO_ANIMATIONS=1 | Force accessibility mode at startup. |
SSL_CERT_FILE | Provide a custom CA bundle for a corporate proxy. |
Config File
New installations store product-owned state under ~/.codewhale/. A project-level overlay at <workspace>/.codewhale/config.toml can override non-sensitive settings. Existing ~/.deepseek/ and <workspace>/.deepseek/config.toml paths remain readable as compatibility fallbacks, and the Codewhale project overlay takes precedence when both exist.
The project overlay cannot loosen user-owned safety policy or store sensitive provider values. Codewhale also reads optional rules from .codewhale/rules/ and compatible .claude/rules/ directories. The user Constitution and repository Constitution add persistent guidance through a defined authority order; approval, sandbox, network, and trust controls still set the hard safety boundary.
Skills
Each skill is a directory with a SKILL.md file. Codewhale scans its workspace and user skill roots and can read compatible agent skill directories. Use /skills to open the manager and /skills inspect to review an installed skill before using it.
MCP Integration
Configure MCP server connections in ~/.codewhale/mcp.json. Existing ~/.deepseek/mcp.json configurations remain readable during migration. Codewhale can consume tools from connected servers and expose its own runtime through codewhale mcp. List and validate each connection before a coding task:
codewhale mcp list
codewhale mcp validateOnly connect MCP servers you trust. A connected server can expose operations that affect files, accounts, or external services, subject to the active permission mode.
Web, Runtime API, and ACP
codewhale web opens a loopback-only browser client over the authenticated Runtime API. It can display transcripts, start or steer turns, handle approvals, and recover pending questions after a tab reload. Runtime tokens stay out of URLs and browser storage.
codewhale web
codewhale serve --http
codewhale serve --acpThe web client does not expose every TUI or Fleet control. ACP remains available for compatible editors such as Zed, while the Runtime API serves local applications and automation that need thread, event, and approval control.
Pros
- Free, MIT-licensed source code.
- Hosted and local models.
- Independent modes and permission postures.
- Resumable sessions with rollback checkpoints.
- Fleet workers for parallel tasks.
- TUI, headless, web, and API surfaces.
- Windows, macOS, Linux, and Android builds.
- MCP, skills, and Workflow extensions.
Cons
- Hosted models require separate provider billing.
- Windows command sandboxing is unavailable.
- The Windows installer is unsigned.
Alternatives & Related Resources
- The Ultimate Claude Code Resource List: Agents, Skills, Plugins & More
- 7 Best CLI AI Coding Agents (Open Source)
- 10 Best Agent Skills for Claude Code & AI Workflows
- Most Popular Agent Skills on GitHub for Coding Agents
FAQs
Q: What is the difference between codewhale and codewhale-tui?
A: codewhale is the dispatcher command, while codewhale-tui is the interactive runtime it launches. npm and release installers include both binaries. Cargo users install both packages separately.
Q: Does Codewhale send project code to a Codewhale service?
A: Codewhale has no mandatory hosted relay. A hosted model provider receives the context sent for its requests. A local Ollama, vLLM, or SGLang route keeps model inference on the endpoint you control.
Q: Where should I download Codewhale?
A: Use codewhale.net for official documentation and the project’s GitHub Releases page for versioned binaries and checksums.
Q: How should I protect a repository?
A: Begin unfamiliar work in Plan, keep Ask or Auto-Review active for changes, and commit important work before large edits. Full Access belongs only in a trusted workspace with a tested recovery route.
Changelog
August 1, 2026: Updated installation and compatibility details, including Android and Windows ARM64 builds and the current Plan, Act, and Operate modes.
