| 1 | # Codewhale |
| 2 | |
| 3 | Codewhale is an open-source agent that reads your project, edits files, runs |
| 4 | commands, and checks its work using a hosted or local model you choose. Start |
| 5 | with one task in your terminal. For a larger job, give parts of the work to |
| 6 | agents with different models and roles. |
| 7 | |
| 8 | <picture> |
| 9 | <source media="(prefers-color-scheme: dark)" srcset="brand/wordmark-inverted.svg"> |
| 10 | <img src="brand/wordmark.svg" alt="Codewhale" width="360"> |
| 11 | </picture> |
| 12 | |
| 13 | [简体中文](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) |
| 14 | |
| 15 | [](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml) |
| 16 | [](https://crates.io/crates/codewhale-cli) |
| 17 | [](https://www.npmjs.com/package/codewhale) |
| 18 | [](https://discord.gg/37gfS3ksug) |
| 19 | |
| 20 | <picture> |
| 21 | <source media="(prefers-color-scheme: dark)" srcset="web/public/codewhale-tui-d7a9a1c.png"> |
| 22 | <img src="web/public/codewhale-tui-d7a9a1c.png" alt="A Codewhale terminal session" width="720"> |
| 23 | </picture> |
| 24 | |
| 25 | *Terminal preview from a v0.9.12 development build.* |
| 26 | |
| 27 | ## Install |
| 28 | |
| 29 | macOS / Linux — install the official GitHub release: |
| 30 | |
| 31 | ```bash |
| 32 | curl -fsSL https://codewhale.net/install.sh | sh |
| 33 | "$HOME/.local/bin/codewhale" |
| 34 | ``` |
| 35 | |
| 36 | The installer selects the latest published release. The [changelog](CHANGELOG.md) |
| 37 | also describes the next release's unreleased candidate; those changes are not |
| 38 | included in published downloads until the release is available. |
| 39 | |
| 40 | Windows: download the matching installer or archive from |
| 41 | [GitHub Releases](https://github.com/Hmbown/CodeWhale/releases/latest). |
| 42 | For an existing direct install, run `codewhale update` (or `codewhale update --check` |
| 43 | to inspect it). The updater prints the executable path and keeps newer builds. |
| 44 | |
| 45 | |
| 46 | The first run helps you connect a provider or configure Codewhale offline. |
| 47 | Model replies require a connected hosted or local model. Codewhale also |
| 48 | supports npm and Cargo as secondary packaging routes, plus Docker, Nix, Scoop, |
| 49 | Android/Termux, and an optional CNB mirror. Existing package-managed installs |
| 50 | receive migration instructions. See [installation and PATH help](docs/INSTALL.md). |
| 51 | |
| 52 | Tab completion is one command per shell — `codewhale completion bash|zsh|fish|powershell|elvish`. |
| 53 | See [shell completions](docs/INSTALL.md#8-shell-completions). |
| 54 | |
| 55 | ## Use |
| 56 | |
| 57 | Open a terminal in your project folder and run `codewhale`. Choose your provider |
| 58 | with `/provider` and your model with `/model`. Then describe a concrete task: |
| 59 | |
| 60 | ```text |
| 61 | Fix the failing tests and explain what changed. |
| 62 | ``` |
| 63 | |
| 64 | Or run a task without opening the TUI: |
| 65 | |
| 66 | ```bash |
| 67 | codewhale exec "fix the failing tests and explain what changed" |
| 68 | ``` |
| 69 | |
| 70 | Codewhale can read your repository, edit files, run commands, inspect results, |
| 71 | and keep working toward a goal. Use `/mode plan` to explore without file changes |
| 72 | or shell execution, and `/mode work` when you want it to make changes. Press |
| 73 | `Shift+Tab` to choose Ask, Auto-Review, or Full Access; the |
| 74 | [modes and permissions guide](docs/MODES.md) explains what each allows. |
| 75 | |
| 76 | ## Terminal, apps, and Computer Use |
| 77 | |
| 78 | The terminal and graphical clients connect to the Codewhale Runtime, which runs |
| 79 | the agent and its tools: |
| 80 | |
| 81 | - **Terminal:** `codewhale` opens the interactive interface; `codewhale exec` |
| 82 | runs a task from a script or CI job. |
| 83 | - **Local browser:** `codewhale web` opens the bundled |
| 84 | [local web client](docs/WEB.md) for the same runtime. |
| 85 | - **Codewhale desktop app (GPUI):** the native GPUI desktop app is the |
| 86 | product-client direction (decided 2026-09-14; the phase map lives in |
| 87 | `docs/TRANSITION.md` in the private `codehwhale-gpui` repo). The hosted web |
| 88 | app at app.codewhale.net sunsets in phases; the marketing site, sign-in, |
| 89 | billing, legal, and download pages stay on the web permanently. |
| 90 | Availability is listed on the [product page](https://codewhale.net/en/product). |
| 91 | |
| 92 | **Computer Use adds tools for observing and interacting with other applications.** |
| 93 | The plugin is included in the current source. |
| 94 | Review its requested access and enable it before use; OS permissions and |
| 95 | platform requirements still apply. See the included |
| 96 | [Computer Use guide](crates/tui/plugins/computer-use/README.md) and |
| 97 | [plugin setup](docs/PLUGINS.md). |
| 98 | |
| 99 | For VS Code, the community-maintained CodeWhale extension connects to the local |
| 100 | Runtime from a sidebar. Install it from the |
| 101 | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=HengQuWorld.brotherwhale-vscode); |
| 102 | source code is on [GitHub](https://github.com/HengQuWorld/CodeWhale-VSCode). |
| 103 | |
| 104 | ## Why Codewhale |
| 105 | |
| 106 | - **Choose your models.** Connect hosted providers or local models through |
| 107 | Ollama, vLLM, or SGLang. Use `/provider` to change providers and `/model` to |
| 108 | choose a model. |
| 109 | - **Stay in control.** Inspect proposed actions and resulting file changes. |
| 110 | Approval settings govern when review is needed; Full Access still respects |
| 111 | hard policy boundaries. `/undo` and `/restore` help recover workspace changes. |
| 112 | - **Keep long work organized.** Save sessions, set a durable `/goal`, review |
| 113 | workflows before they run, and coordinate agents without turning their |
| 114 | internal instructions into your transcript. |
| 115 | - **Extend the agent you already have.** Connect MCP servers and skills, |
| 116 | configure hooks, and keep agent roles as readable files in your project or |
| 117 | personal settings. |
| 118 | |
| 119 | Run `/help` in the TUI for commands and keyboard shortcuts. |
| 120 | |
| 121 | ## Safety |
| 122 | |
| 123 | Codewhale runs on your machine with the access you grant it. Approval modes and |
| 124 | repository rules limit what the agent may do; optional OS sandboxing adds a |
| 125 | stronger execution boundary where supported. Unknown model prices stay unknown |
| 126 | instead of being reported as free. |
| 127 | |
| 128 | Read [authorization order](docs/AUTHORIZATION_ORDER.md) for the exact policy |
| 129 | stack and [configuration](docs/CONFIGURATION.md) for local settings. |
| 130 | |
| 131 | ## Documentation |
| 132 | |
| 133 | - [Providers and local models](docs/PROVIDERS.md) |
| 134 | - [Agent teams](docs/FLEET.md) |
| 135 | - [MCP](docs/MCP.md), [hooks](docs/HOOKS.md), and [configuration](docs/CONFIGURATION.md) |
| 136 | - [Local web client](docs/WEB.md) |
| 137 | - [All documentation](docs) |
| 138 | - [Repository layout and contribution guide](CONTRIBUTING.md#project-structure) |
| 139 | |
| 140 | ## Join the community |
| 141 | |
| 142 | **Bug reports, feature ideas, and pull requests are welcome**, whether you have |
| 143 | used Codewhale for months or are trying it for the first time. If a provider is |
| 144 | missing, a workflow is awkward, or the terminal UI gets in your way, |
| 145 | [open an issue](https://github.com/Hmbown/CodeWhale/issues/new/choose) or |
| 146 | [send a pull request](CONTRIBUTING.md) so we can improve it together. We welcome |
| 147 | first contributions, and contributors keep credit for the work that lands. |
| 148 | |
| 149 | Join the [Discord](https://discord.gg/37gfS3ksug), or add Hunter on WeChat |
| 150 | (`hunterbown`) and ask to join the Whale Brothers group. |
| 151 | |
| 152 | ## Project history |
| 153 | |
| 154 | Codewhale began as `deepseek-tui` and still preserves that configuration and |
| 155 | session compatibility. It is now provider-neutral and independently maintained; |
| 156 | it is not affiliated with any model provider. |
| 157 | |
| 158 | Thanks to every contributor and to the open source communities that helped the |
| 159 | project grow. See [the contributor record](docs/CONTRIBUTORS.md). |
| 160 | |
| 161 | ## License |
| 162 | |
| 163 | [MIT](LICENSE). Portions adapted from other open-source projects are recorded |
| 164 | in [third-party notices](docs/THIRD_PARTY_NOTICES.md). |
| 165 |