| 1 | # codewhale |
| 2 | |
| 3 | > The terminal coding agent for supported hosted and local models — open models first. |
| 4 | |
| 5 | Codewhale is a Rust TUI and CLI for many model providers — DeepSeek, |
| 6 | OpenRouter, Hugging Face, and local vLLM/SGLang/Ollama are supported routes, |
| 7 | and it speaks natively to Anthropic Claude and OpenAI when that's what you have |
| 8 | — with approval-gated tools, OS sandboxing, side-git snapshots, and `/restore` |
| 9 | rollback. |
| 10 | |
| 11 | This npm package is a small launcher: it downloads the matching native |
| 12 | Codewhale binaries for your platform, verifies them against the release |
| 13 | SHA-256 manifest, and installs `codewhale` plus the `codew` convenience name. |
| 14 | Both names run the same compiled runtime. The application state and credentials |
| 15 | still live in Codewhale's normal config files, not inside `node_modules`. |
| 16 | |
| 17 | > Previously published as `deepseek-tui`. See |
| 18 | > [docs/REBRAND.md](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/REBRAND.md) |
| 19 | > for the migration notes; the legacy `deepseek-tui` npm package is deprecated |
| 20 | > and receives no further releases. |
| 21 | |
| 22 | ## Install |
| 23 | |
| 24 | ```bash |
| 25 | npm install -g codewhale |
| 26 | # or |
| 27 | pnpm add -g codewhale |
| 28 | ``` |
| 29 | |
| 30 | On Windows, the Node launcher stays alive while the native program runs. |
| 31 | Killing Node by process name can also interrupt other Codewhale npm sessions |
| 32 | and prevent normal terminal cleanup. Stop dev servers by their owned PID or |
| 33 | port, or use Codewhale's task cancellation. The Windows native archive or |
| 34 | installer avoids this launcher dependency. See the [Windows npm note](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/INSTALL.md#4-npm). |
| 35 | |
| 36 | For project-local usage: |
| 37 | |
| 38 | ```bash |
| 39 | npm install codewhale |
| 40 | npx codewhale --help |
| 41 | ``` |
| 42 | |
| 43 | `postinstall` tries to download platform binaries into `bin/downloads/`. On |
| 44 | Linux x64 it concurrently probes the GitHub Releases and CNB first-party |
| 45 | checksum manifests for this package version, locks the first source that |
| 46 | validates, and downloads binaries only from that source. If GitHub release |
| 47 | assets are temporarily unreachable, install continues and the wrapper retries |
| 48 | the download on first run. |
| 49 | |
| 50 | ## First run |
| 51 | |
| 52 | ```bash |
| 53 | codewhale auth set --provider deepseek |
| 54 | codewhale auth status |
| 55 | codewhale doctor |
| 56 | codewhale |
| 57 | ``` |
| 58 | |
| 59 | Every provider is the same one-line shape — `--provider openrouter`, |
| 60 | `--provider huggingface`, `--provider ollama`, or `--provider anthropic` for a |
| 61 | Claude key; the full registry lives in |
| 62 | [docs/PROVIDERS.md](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/PROVIDERS.md). |
| 63 | |
| 64 | The single runtime reads `~/.codewhale/config.toml` for auth and default model |
| 65 | settings. Legacy `~/.deepseek/config.toml` installs are still read as a |
| 66 | compatibility fallback. Common commands are available directly, including |
| 67 | `codewhale doctor`, `codewhale models`, `codewhale sessions`, and |
| 68 | `codewhale resume --last`. |
| 69 | |
| 70 | ## Supported platforms |
| 71 | |
| 72 | Prebuilt binaries for the GitHub release are downloaded automatically: |
| 73 | |
| 74 | - Linux x64 |
| 75 | - Linux arm64 |
| 76 | - macOS x64 / arm64 |
| 77 | - Windows x64 / arm64 |
| 78 | - Android arm64 / Termux (preview; requires matching Android assets in the |
| 79 | selected GitHub Release) |
| 80 | |
| 81 | The wrapper recognizes Android arm64 and resolves the |
| 82 | Termux-native `codewhale` and `codew` assets. That path works only for package |
| 83 | versions whose matching GitHub Release publishes both assets, and remains |
| 84 | preview support pending real-device QA. See the support table in |
| 85 | [docs/INSTALL.md](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/INSTALL.md). |
| 86 | |
| 87 | HarmonyOS PC (`openharmony`) is treated as `linux`, so it gets the Linux |
| 88 | binaries matching your CPU architecture (x64 or arm64). Linux riscv64 prebuilts |
| 89 | are temporarily paused while the locked `rquickjs-sys` dependency lacks |
| 90 | `riscv64gc-unknown-linux-gnu` bindings. Other platform/architecture combinations |
| 91 | (FreeBSD, Linux riscv64, …) aren't shipped as prebuilts. Unsupported platforms, |
| 92 | checksum failures, and glibc compatibility problems still fail with a clear |
| 93 | error pointing you at the full |
| 94 | [docs/INSTALL.md](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/INSTALL.md) |
| 95 | guide. |
| 96 | |
| 97 | ## Wrapper configuration |
| 98 | |
| 99 | | Setting | What it does | |
| 100 | | --- | --- | |
| 101 | | `codewhaleBinaryVersion` in `package.json` | Default native binary version. `deepseekBinaryVersion` is still read as a backward-compat fallback. | |
| 102 | | `CODEWHALE_RELEASE_BASE_URL` | Canonical override: use an internal or mirrored release-asset directory and skip the Linux x64 GitHub/CNB race. The directory must contain `codewhale-artifacts-sha256.txt` and the platform binaries. `DEEPSEEK_TUI_RELEASE_BASE_URL` and `DEEPSEEK_RELEASE_BASE_URL` are the implemented legacy fallbacks. | |
| 103 | | `CODEWHALE_USE_CNB_MIRROR=1` | Force the CNB (China-friendly) first-party mirror on Linux x64 and OpenHarmony x64, skipping the automatic race. Other targets fail with a clear unsupported-mirror error; use GitHub or a complete `CODEWHALE_RELEASE_BASE_URL` mirror there. Without this variable, Linux x64 still probes CNB and GitHub together and uses the first valid checksum manifest. | |
| 104 | | `CODEWHALE_VERSION` | Override the release version to download. | |
| 105 | | `CODEWHALE_GITHUB_REPO` | Override the source repo. Defaults to `codewhale-hq/CodeWhale`. | |
| 106 | | `CODEWHALE_FORCE_DOWNLOAD=1` | Force download even when the cached binary is already present. | |
| 107 | | `CODEWHALE_DISABLE_INSTALL=1` | Skip install-time download. | |
| 108 | | `CODEWHALE_OPTIONAL_INSTALL=1` | Make install-time retryable download failures warn and exit `0` instead of failing `npm install`. | |
| 109 | | `CODEWHALE_QUIET_INSTALL=1` | Suppress installer progress messages. | |
| 110 | | `CODEWHALE_DOWNLOAD_TIMEOUT_MS` | Override the total download budget. | |
| 111 | | `CODEWHALE_DOWNLOAD_STALL_MS` | Override the no-progress stall budget. | |
| 112 | | `CODEWHALE_SKIP_GLIBC_CHECK=1` | Bypass the Linux glibc preflight check at your own risk. | |
| 113 | |
| 114 | The corresponding `DEEPSEEK_TUI_*` and `DEEPSEEK_*` names remain accepted as |
| 115 | legacy aliases, after the canonical Codewhale names. |
| 116 | |
| 117 | ### Proxies |
| 118 | |
| 119 | Downloads respect `HTTPS_PROXY` / `HTTP_PROXY` (CONNECT tunneling included) |
| 120 | and `NO_PROXY`, so the wrapper works behind corporate proxies. For fully |
| 121 | offline installs, set `CODEWHALE_DISABLE_INSTALL=1` or point |
| 122 | `CODEWHALE_RELEASE_BASE_URL` at a local mirror. |
| 123 | |
| 124 | ## Release integrity |
| 125 | |
| 126 | - `npm publish` runs a release-asset check to ensure the required binaries, |
| 127 | archives, Windows installer, and checksum manifests exist for the target |
| 128 | GitHub release before publishing. |
| 129 | - For the default GitHub Release source, `npm run release:check` also verifies |
| 130 | that those release assets were updated by a successful `release.yml` run for |
| 131 | the tag commit. When `CODEWHALE_RELEASE_BASE_URL` or a legacy mirror override |
| 132 | is set, it checks the mirror asset URLs and checksum manifests instead. |
| 133 | - Install-time downloads are verified against the release checksum manifest before |
| 134 | the wrapper marks them executable. |
| 135 | |
| 136 | ## Links |
| 137 | |
| 138 | - Repository: <https://github.com/codewhale-hq/CodeWhale> |
| 139 | - Website: <https://codewhale.net/> |
| 140 | - Provider registry: [docs/PROVIDERS.md](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/PROVIDERS.md) |
| 141 | - Changelog: [CHANGELOG.md](https://github.com/codewhale-hq/CodeWhale/blob/main/CHANGELOG.md) |
| 142 |