| 1 | # Codewhale |
| 2 | |
| 3 | An open source coding agent for your terminal — bring your own model. |
| 4 | |
| 5 | Codewhale started as a native experience for DeepSeek. It has since grown into a |
| 6 | community-driven project: one coding harness that fits a growing international |
| 7 | community and supports as many models and providers as possible — open models |
| 8 | first, hosted or local, none privileged over the rest. |
| 9 | |
| 10 | Give it a provider, a model, and a task. It reads your code, edits files, runs |
| 11 | commands, and checks its own work, then stops when the job is done or it needs |
| 12 | you. Switch models mid-task with `/model`. Work interactively in the TUI, or run |
| 13 | `codewhale exec` in scripts and CI. It's written in Rust, licensed MIT, and runs |
| 14 | on your machine. |
| 15 | |
| 16 | We're always looking for contributors and ways to improve. If a model or |
| 17 | provider you use is missing, or something breaks, telling us is one of the most |
| 18 | useful things you can do — see [Contributing](#contributing). |
| 19 | |
| 20 | [简体中文](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) · [codewhale.net](https://codewhale.net/) · [Docs](docs) · [Changelog](CHANGELOG.md) · [Discord](https://discord.gg/37gfS3ksug) |
| 21 | |
| 22 | [](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml) |
| 23 | [](https://crates.io/crates/codewhale-cli) |
| 24 | [](https://www.npmjs.com/package/codewhale) |
| 25 | [](https://discord.gg/37gfS3ksug) |
| 26 | |
| 27 |  |
| 28 | |
| 29 | ## Install |
| 30 | |
| 31 | ```bash |
| 32 | npm install -g codewhale |
| 33 | ``` |
| 34 | |
| 35 | Cargo, Docker, Nix, Scoop, prebuilt archives, Android/Termux, and a CNB mirror |
| 36 | for anyone who can't reach GitHub are covered in |
| 37 | [docs/INSTALL.md](docs/INSTALL.md). Coming from `deepseek-tui`? Your config and |
| 38 | sessions carry over — see [docs/REBRAND.md](docs/REBRAND.md). |
| 39 | |
| 40 | ## Use |
| 41 | |
| 42 | ```bash |
| 43 | codewhale auth set --provider deepseek # or export ANTHROPIC_API_KEY, etc. |
| 44 | codewhale # open the TUI |
| 45 | codewhale exec "fix the failing test" # headless |
| 46 | codewhale web # local browser client on 127.0.0.1 |
| 47 | ``` |
| 48 | |
| 49 | In the TUI: `/model` switches provider and model together, `/fleet` runs a team |
| 50 | of workers, `/undo` reverts the last turn, and `/restore <N>` rolls the |
| 51 | workspace back to an earlier snapshot (bare `/restore` lists them). `Tab` |
| 52 | cycles Plan / Act / Operate when the composer is empty — with text in it, `Tab` |
| 53 | completes slash commands and `@` mentions instead. `Shift+Tab` cycles the |
| 54 | Ask / Auto-Review / Full Access permission posture at any time. `!` runs a |
| 55 | shell command through the normal approval path. |
| 56 | |
| 57 | ## What it does |
| 58 | |
| 59 | - **Any model, any provider.** DeepSeek, Claude, GPT, Kimi, GLM, and 30+ |
| 60 | providers, plus your own vLLM, SGLang, or Ollama with no key — all through one |
| 61 | runtime and one toolset. Context limits and prices come from the real route, |
| 62 | and an unknown price shows as unknown rather than $0. |
| 63 | - **Read-only until you allow more.** Plan mode can't change files, and |
| 64 | approvals gate risky commands. When an OS sandbox actually wraps a command, |
| 65 | Codewhale says so: Seatbelt on macOS where available, opt-in bubblewrap on |
| 66 | Linux. A repo's `constitution.json` compiles into write holds that even Full |
| 67 | Access can't skip. |
| 68 | - **Work you can resume.** A fleet records every step to an append-only ledger, |
| 69 | so `fleet resume` picks up where you left off. |
| 70 | |
| 71 | ## Learn more |
| 72 | |
| 73 | - [docs/PROVIDERS.md](docs/PROVIDERS.md) — every provider route: hosted, |
| 74 | gateway, and local |
| 75 | - [docs/FLEET.md](docs/FLEET.md) — fleets, the ledger, and resume |
| 76 | - [docs/WORKFLOW_EXPERIMENTAL_SEARCH.md](docs/WORKFLOW_EXPERIMENTAL_SEARCH.md) — frozen, provider-neutral experimental search within Workflow |
| 77 | - [docs/CONFIGURATION.md](docs/CONFIGURATION.md) — `config.toml`, hooks, and |
| 78 | the constitution |
| 79 | - [docs/AUTHORIZATION_ORDER.md](docs/AUTHORIZATION_ORDER.md) — how modes, |
| 80 | hooks, permission rules, safety floors, repo law, approvals, and sandboxing |
| 81 | compose |
| 82 | - [docs/HOOKS.md](docs/HOOKS.md) — the eleven TUI lifecycle hook events, their |
| 83 | payloads, and which three of them can steer a turn (`codewhale exec` and the |
| 84 | CLI subcommands do not fire hooks) |
| 85 | - [docs/WEB.md](docs/WEB.md) — the loopback-only browser client and its one-time |
| 86 | authentication boundary |
| 87 | |
| 88 | Everything else — modes, keybindings, sandbox details, MCP, the runtime API, |
| 89 | and architecture — lives in [docs](docs) and on |
| 90 | [codewhale.net](https://codewhale.net/). |
| 91 | |
| 92 | ## Contributing |
| 93 | |
| 94 | Issues, PRs, repro steps, logs, and feature requests are all real project work, |
| 95 | and first contributions are welcome. When a PR can't merge as-is, maintainers |
| 96 | harvest what works and keep the author credited — in the commit, the changelog, |
| 97 | and [docs/CONTRIBUTORS.md](docs/CONTRIBUTORS.md). |
| 98 | |
| 99 | - [Open issues](https://github.com/Hmbown/CodeWhale/issues) — good first |
| 100 | contributions live here |
| 101 | - [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup and PR flow |
| 102 | - [docs/CONTRIBUTORS.md](docs/CONTRIBUTORS.md) — everyone who has shaped this |
| 103 | - [Buy me a coffee](https://www.buymeacoffee.com/hmbown) |
| 104 | |
| 105 | Thanks to [DeepSeek](https://github.com/deepseek-ai) for the models and support |
| 106 | that started the project, [DataWhale](https://github.com/datawhalechina) 🐋 for |
| 107 | welcoming us into the Whale Brother family, and |
| 108 | [OpenWarp](https://github.com/zerx-lab/warp) and |
| 109 | [Open Design](https://github.com/nexu-io/open-design) for collaborating on the |
| 110 | terminal-agent experience. |
| 111 | |
| 112 | ## License |
| 113 | |
| 114 | [MIT](LICENSE). An independent community project, not affiliated with any model |
| 115 | provider. |
| 116 | |
| 117 | [](https://www.star-history.com/?repos=Hmbown%2FCodeWhale&type=date) |
| 118 |