| 1 | <div align="center"> |
| 2 | |
| 3 | <picture> |
| 4 | <source media="(prefers-color-scheme: dark)" srcset="brand/wordmark-inverted.svg"> |
| 5 | <img src="brand/wordmark.svg" alt="Codewhale" width="320"> |
| 6 | </picture> |
| 7 | |
| 8 | **The open-source coding agent that works with any model.** |
| 9 | |
| 10 | Codewhale reads your project, edits files, runs commands, and checks its own |
| 11 | work — in your terminal, with a hosted or local model you choose. |
| 12 | |
| 13 | [](https://github.com/codewhale-hq/CodeWhale/actions/workflows/ci.yml) |
| 14 | [](https://crates.io/crates/codewhale-cli) |
| 15 | [](https://www.npmjs.com/package/codewhale) |
| 16 | [](LICENSE) |
| 17 | [](https://discord.gg/37gfS3ksug) |
| 18 | |
| 19 | [Website](https://codewhale.net) · [Documentation](docs/README.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) |
| 20 | |
| 21 | [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · [Tiếng Việt](README.vi.md) · [Bahasa Indonesia](README.id.md) · [한국어](README.ko-KR.md) · [Español](README.es-419.md) · [Português](README.pt-BR.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [繁體中文](README.zh-TW.md) · [हिन्दी](README.hi.md) · [Türkçe](README.tr.md) · [Italiano](README.it.md) · [Polski](README.pl.md) · [العربية](README.ar.md) · [Català](README.ca.md) |
| 22 | |
| 23 | <img src="web/public/codewhale-tui-8ba2bbf.png" alt="A Codewhale terminal session" width="760"> |
| 24 | |
| 25 | <sub>Real terminal capture of a fresh install — no staged output.</sub> |
| 26 | |
| 27 | </div> |
| 28 | |
| 29 | ## Install |
| 30 | |
| 31 | macOS and Linux: |
| 32 | |
| 33 | ```bash |
| 34 | curl -fsSL https://codewhale.net/install.sh | sh |
| 35 | ``` |
| 36 | |
| 37 | The installer downloads checksum-verified binaries into `~/.local/bin`. If |
| 38 | `codewhale` then says "command not found", run the one PATH line the installer |
| 39 | prints, or see [Put it on your PATH](docs/INSTALL.md#put-it-on-your-path). |
| 40 | Upgrade any time with `codewhale update`. |
| 41 | |
| 42 | <details> |
| 43 | <summary><b>Windows, npm, Cargo, and other routes</b></summary> |
| 44 | |
| 45 | ```bash |
| 46 | winget install HunterBown.CodeWhale # Windows x64 (or Scoop, or the installer from GitHub Releases) |
| 47 | npm install -g codewhale # wraps the same release binaries |
| 48 | cargo install codewhale-cli --locked # build from crates.io |
| 49 | ``` |
| 50 | |
| 51 | Docker, Nix, Homebrew on Linux, Android/Termux, manual downloads with checksum |
| 52 | verification, and the optional CNB mirror are covered in the |
| 53 | [installation guide](docs/INSTALL.md). Pick one route: several installs on one |
| 54 | machine end up fighting over `PATH`. |
| 55 | |
| 56 | </details> |
| 57 | |
| 58 | ## Quickstart |
| 59 | |
| 60 | 1. **Open your project.** Run `codewhale` in the folder you want to work on. |
| 61 | 2. **Connect a model.** Run `/provider` (or press `F3`) to add a hosted key or |
| 62 | pick a local runtime. If Ollama is already running with a chat model, |
| 63 | Codewhale switches to it on its own. Use `/model` to change models. |
| 64 | 3. **Give it a concrete task.** |
| 65 | |
| 66 | ```text |
| 67 | Fix the failing tests and explain what changed. |
| 68 | ``` |
| 69 | |
| 70 | The same task runs headless from a script or CI job: |
| 71 | |
| 72 | ```bash |
| 73 | codewhale exec "fix the failing tests and explain what changed" |
| 74 | ``` |
| 75 | |
| 76 | Run `/help` for commands and keyboard shortcuts. |
| 77 | |
| 78 | ## Ways to run it |
| 79 | |
| 80 | Every client drives the same local [Codewhale Engine](docs/ARCHITECTURE.md), so |
| 81 | sessions, tools, and permissions behave the same everywhere. |
| 82 | |
| 83 | | Command | What it does | |
| 84 | | --- | --- | |
| 85 | | `codewhale` | The interactive terminal interface | |
| 86 | | `codewhale exec "…"` | One headless turn from a script or CI, streaming JSON | |
| 87 | | `codewhale web` | The bundled [local browser client](docs/WEB.md) on `127.0.0.1` | |
| 88 | | `codewhale review --pr N` | An advisory [pull request review](docs/GITHUB_ACTION.md); posting is opt-in | |
| 89 | | Runtime API | A [local HTTP API](docs/RUNTIME_API.md) for threads, events, and approvals | |
| 90 | |
| 91 | A native desktop app (GPUI) is being built as the signed-in product client; see |
| 92 | the [product page](https://codewhale.net/en/product) for availability. The |
| 93 | community-maintained [VS Code extension](https://marketplace.visualstudio.com/items?itemName=HengQuWorld.brotherwhale-vscode) |
| 94 | connects to the same Engine from a sidebar ([source](https://github.com/HengQuWorld/CodeWhale-VSCode)). |
| 95 | |
| 96 | ## What it does |
| 97 | |
| 98 | - **Any model, no lock-in.** Over 40 built-in provider routes — Anthropic, |
| 99 | DeepSeek, Google, Mistral, Moonshot, OpenAI, OpenRouter, xAI and more — plus |
| 100 | any OpenAI-compatible endpoint and local models through Ollama, vLLM, or |
| 101 | SGLang. [Providers](docs/PROVIDERS.md) |
| 102 | - **You stay in control.** Plan mode explores without changing anything; Work |
| 103 | and Operate make changes. Approval postures decide when a tool call needs your |
| 104 | OK, `/undo` and `/restore` recover workspace changes, and `/receipts` lists |
| 105 | every file, command, and approval in a session. [Modes](docs/MODES.md) · |
| 106 | [Receipts](docs/RECEIPTS.md) |
| 107 | - **Built for long jobs.** Set a durable `/goal`, delegate bounded work to |
| 108 | [sub-agents](docs/SUBAGENTS.md), run supervised [agent teams](docs/FLEET.md) |
| 109 | with a pre-spend check, or script them as checked-in |
| 110 | [workflows](docs/WORKFLOW_AUTHORING.md). |
| 111 | - **Extend what you already use.** Connect [MCP servers](docs/MCP.md), install |
| 112 | [skills](docs/SKILLS.md) and [plugins](docs/PLUGINS.md), run |
| 113 | [hooks](docs/HOOKS.md) on session and tool events, and load existing |
| 114 | [Claude Code plugins](docs/CLAUDE_PLUGIN_COMPAT.md). |
| 115 | - **Computer Use.** An included plugin adds tools for observing and operating |
| 116 | other applications. Review its access and enable it before use. |
| 117 | [Guide](crates/tui/plugins/computer-use/README.md) |
| 118 | |
| 119 | ## Modes and permissions |
| 120 | |
| 121 | | | Choose with | Options | |
| 122 | | --- | --- | --- | |
| 123 | | **Mode** — what the agent is doing | `Tab` or `/mode` | Plan (explore, no changes) · Work (edit and run) · Operate (drive a goal through planned, verified steps) | |
| 124 | | **Posture** — when it asks first | `Shift+Tab` | Ask · Auto-Review · Full Access | |
| 125 | |
| 126 | Full Access still respects hard policy boundaries. The |
| 127 | [modes and permissions guide](docs/MODES.md) explains each option. |
| 128 | |
| 129 | ## Safety |
| 130 | |
| 131 | Codewhale runs on your machine with the access you grant it. Approval postures |
| 132 | and repository rules limit what the agent may do, and commands run inside an OS |
| 133 | sandbox where supported (Seatbelt on macOS; bubblewrap on Linux is opt-in). |
| 134 | `/preview-request` shows the exact redacted request before anything is sent. |
| 135 | Unknown model prices stay unknown instead of being reported as free. |
| 136 | |
| 137 | See [authorization order](docs/AUTHORIZATION_ORDER.md), |
| 138 | [sandboxing](docs/SANDBOX.md), and [telemetry](docs/TELEMETRY.md) — usage |
| 139 | counts are on by default and `codewhale config set telemetry false` turns them |
| 140 | off. |
| 141 | |
| 142 | ## Documentation |
| 143 | |
| 144 | | Start here | Go deeper | |
| 145 | | --- | --- | |
| 146 | | [Installation](docs/INSTALL.md) | [Configuration](docs/CONFIGURATION.md) | |
| 147 | | [Providers and local models](docs/PROVIDERS.md) | [Architecture](docs/ARCHITECTURE.md) | |
| 148 | | [Modes and permissions](docs/MODES.md) | [Runtime API](docs/RUNTIME_API.md) | |
| 149 | | [Keybindings](docs/KEYBINDINGS.md) | [Plugin authoring](docs/PLUGIN_AUTHORING.md) | |
| 150 | | [GitHub PR review](docs/GITHUB_ACTION.md) | [All documentation](docs/README.md) | |
| 151 | |
| 152 | ## Community |
| 153 | |
| 154 | Bug reports, feature ideas, and pull requests are welcome — whether you have |
| 155 | used Codewhale for months or are trying it for the first time. If a provider is |
| 156 | missing or a workflow is awkward, |
| 157 | [open an issue](https://github.com/codewhale-hq/CodeWhale/issues/new/choose) or |
| 158 | [send a pull request](CONTRIBUTING.md). First contributions are welcome, and |
| 159 | contributors keep credit for the work that lands. The |
| 160 | [repository layout](CONTRIBUTING.md#project-structure) is a good place to start. |
| 161 | |
| 162 | Join the [Discord](https://discord.gg/37gfS3ksug), or add Hunter on WeChat |
| 163 | (`hunterbown`) and ask to join the Whale Brothers group. |
| 164 | |
| 165 | ## History and license |
| 166 | |
| 167 | Codewhale began as `deepseek-tui` and still reads that project's configuration |
| 168 | and sessions. It is now provider-neutral and independently maintained, and is |
| 169 | not affiliated with any model provider. Thanks to |
| 170 | [every contributor](docs/CONTRIBUTORS.md) and to the open-source communities |
| 171 | that helped it grow. |
| 172 | |
| 173 | [MIT](LICENSE). Portions adapted from other open-source projects are recorded |
| 174 | in [third-party notices](docs/THIRD_PARTY_NOTICES.md). |
| 175 |