Codewhale: Open-Source Coding Agent with 30+ AI Provider Support

What Codewhale Is and Who It Serves

Codewhale is an open-source agent harness for developers who want a coding agent without committing to one AI vendor. It reads your project repository, edits files, runs shell commands, and checks its results. The key design constraint is that the agent runtime and the model it calls are always separate: you connect a provider through the /provider command, and every agent operation flows through that single runtime regardless of which model sits behind it.

The target user is a developer who either wants to experiment across providers, prefers a local model for privacy, or works in an environment where specific models are required for cost or compliance reasons. The README lists DeepSeek, Claude, GPT, Kimi, GLM, and more than 30 others as supported providers, plus local runtime options including Ollama, vLLM, and SGLang. A local Ollama instance running a chat model is detected and activated automatically on first launch, without any manual configuration.

Codewhale Runtime Architecture: From CLI to Crates

Codewhale is a Rust workspace with more than twenty crates. The main binary is built from `crates/cli`, which depends on the agent, runtime, tools, hooks, mcp, lane, workflow, and tui crates, among others. The separation matters: the TUI is one client, but it is not the only one.

Three clients connect to the same runtime:

- The terminal client (`codewhale`) opens the interactive TUI. - `codewhale web` opens the bundled local browser client. - A native desktop application built with GPUI is in a separate repository and is described in the README as the direction for the signed-in product client.

The `codewhale exec` subcommand runs a task without opening the TUI at all, which makes it usable from CI pipelines and shell scripts. Fleet mode is documented in `docs/FLEET.md` and allows coordinating multiple agents with different models and roles on larger jobs; agent roles are stored as readable files in the project or personal settings rather than embedded in the agent's system prompt.

Installing Codewhale and Running a First Task

On macOS and Linux, the official installer fetches the latest release:

curl -fsSL https://codewhale.net/install.sh | sh
"$HOME/.local/bin/codewhale"

The first line downloads and runs the install script. The second line runs the binary directly before it is on your PATH. On Windows, download the installer from the GitHub Releases page or use Scoop; the README also mentions npm and Cargo as secondary packaging routes.

The first launch opens to the composer immediately. No setup wizard runs. The launch screen shows "no model connected" until you add a provider. Run `/provider` or press F3 to add a hosted API key or pick a local runtime. Once a model is connected, describe a task in plain text:

Fix the failing tests and explain what changed.

Or skip the TUI entirely and run the task from a script:

codewhale exec "fix the failing tests and explain what changed"

Shell tab completion installs with one command per shell. For bash:

codewhale completion bash

For zsh and fish, replace `bash` with `zsh` or `fish`. The full list of shells is in `docs/INSTALL.md`.

For updates, `codewhale update` fetches the latest release and prints the executable path. `codewhale update --check` inspects without installing.

Permission Modes and Workspace Safety

Codewhale offers three interaction modes toggled with Shift+Tab: Ask, Auto-Review, and Full Access. `/mode plan` disables file changes and shell execution entirely, which makes it safe to explore what the agent intends to do without committing to it. `/mode work` restores the ability to make changes.

Approval settings and repository rules define what the agent may do before any sandboxing applies. Optional OS sandboxing adds a harder execution boundary where the platform supports it. The README notes that Full Access still respects hard policy boundaries, and that unknown model prices are reported as unknown rather than as free.

Two recovery mechanisms are documented: `/undo` reverses the most recent workspace change, and `/restore` is available for broader recovery. The authorization order documentation in `docs/AUTHORIZATION_ORDER.md` describes the exact policy stack. Local settings live in `docs/CONFIGURATION.md`.

Computer Use is a plugin included in the current source. It adds tools for observing and interacting with other applications. The README states that you must review its requested access and enable it explicitly; OS permissions and platform requirements apply. The plugin guide is at `crates/tui/plugins/computer-use/README.md`.

MCP, Hooks, and Skills

Codewhale supports connecting MCP servers for external tool access, configured through `docs/MCP.md`. Hooks are scripts the runtime calls at defined points in the agent lifecycle, documented in `docs/HOOKS.md`. Both are configured in `config.toml` or through CLI flags.

The `/provider` command changes the active provider at runtime, and `/model` selects from the models that provider exposes. The `.env.example` file shows the credential variable names for built-in providers: `DEEPSEEK_API_KEY`, `CODEWHALE_API_KEY`, and others. The file notes that routing, model URL, config, MCP, sandbox, and approval settings are ignored in `.env` and belong in `config.toml`, CLI flags, or the launching shell.

The Docker image in the repository builds a minimal runtime layer that ships the `codewhale` and `codew` command names. API keys must be passed at runtime with `-e DEEPSEEK_API_KEY` or `--env-file .env`, never baked into the image. The Dockerfile uses Rust 1.88, which the workspace manifest also sets as the minimum toolchain version.

Limitation: Community VS Code Extension and Upstream Versioning Gaps

Codewhale has no first-party VS Code extension. The README points to a community-maintained extension (HengQuWorld.brotherwhale-vscode) available on the VS Code Marketplace. Its source code is on GitHub under a separate organization. Because it is not maintained by the Codewhale team, compatibility with a given Runtime version is not guaranteed; you should verify it against the current Runtime before relying on it for editor workflows.

The changelog describes the next release's unreleased candidate alongside published changes. The README warns that those unreleased changes are not included in published downloads until the release is available. This means the install script always fetches a stable release, but the CHANGELOG may show work in progress that does not yet install.

For teams using the fleet mode, agent role files are stored as readable files rather than system prompts. This is a deliberate design, but it means the files are visible in the repository, and any contributor with repository access can read or modify agent roles. The security model assumes that repository access implies trust.

Codewhale versus Claude Code

Claude Code is Anthropic's terminal coding agent and the closest direct comparison. Both run in the terminal and operate on your local repository. The structural difference is model support: Claude Code connects to Anthropic's hosted Claude models; Codewhale connects to any of more than thirty providers including local runtimes. A developer who needs to work without an internet connection can point Codewhale at a local Ollama instance; Claude Code has no equivalent local model path.

Claude Code is a closed-source product maintained by Anthropic. Codewhale is MIT-licensed and open-source. If auditing the agent's source code matters to your team, only Codewhale provides it. The Codewhale fleet mode for multi-agent coordination has no direct Claude Code counterpart in the current Claude Code CLI, though the underlying Claude API supports multi-turn agent patterns separately.

Editorial conclusion

Codewhale suits engineers who want a coding agent that works across providers and avoids committing to a single vendor's model. The model-agnostic runtime is the core differentiator: switching from a hosted DeepSeek key to a local SGLang server requires only a /provider change, not a new install. Teams running sensitive codebases will want to review the authorization order documentation before enabling Full Access, and should enable OS sandboxing where the platform supports it. The VS Code extension is community-maintained rather than first-party, so verify its compatibility with the current Runtime version before relying on it in editor workflows. v0.10.0 was released on 2026-09-22.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes