| 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 the `codewhale`, `codew`, and `codewhale-tui` |
| 14 | commands. The application state and credentials still live in Codewhale's |
| 15 | normal config files, not inside `node_modules`. |
| 16 | |
| 17 | > Previously published as `deepseek-tui`. See |
| 18 | > [docs/REBRAND.md](https://github.com/Hmbown/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 | For project-local usage: |
| 31 | |
| 32 | ```bash |
| 33 | npm install codewhale |
| 34 | npx codewhale --help |
| 35 | ``` |
| 36 | |
| 37 | `postinstall` tries to download platform binaries into `bin/downloads/`. If |
| 38 | GitHub release assets are temporarily unreachable, install continues and the |
| 39 | wrapper retries the download on first run. |
| 40 | |
| 41 | ## First run |
| 42 | |
| 43 | ```bash |
| 44 | codewhale auth set --provider deepseek |
| 45 | codewhale auth status |
| 46 | codewhale doctor |
| 47 | codewhale |
| 48 | ``` |
| 49 | |
| 50 | Every provider is the same one-line shape — `--provider openrouter`, |
| 51 | `--provider huggingface`, `--provider ollama`, or `--provider anthropic` for a |
| 52 | Claude key; the full registry lives in |
| 53 | [docs/PROVIDERS.md](https://github.com/Hmbown/CodeWhale/blob/main/docs/PROVIDERS.md). |
| 54 | |
| 55 | The `codewhale` facade and `codewhale-tui` binary share |
| 56 | `~/.codewhale/config.toml` for auth and default model settings. Legacy |
| 57 | `~/.deepseek/config.toml` installs are still read as a compatibility fallback. |
| 58 | Common TUI commands are available directly through the facade, including |
| 59 | `codewhale doctor`, `codewhale models`, `codewhale sessions`, and |
| 60 | `codewhale resume --last`. |
| 61 | |
| 62 | ## Supported platforms |
| 63 | |
| 64 | Prebuilt binaries for the GitHub release are downloaded automatically: |
| 65 | |
| 66 | - Linux x64 |
| 67 | - Linux arm64 |
| 68 | - macOS x64 / arm64 |
| 69 | - Windows x64 / arm64 |
| 70 | - Android arm64 / Termux (preview; requires matching Android assets in the |
| 71 | selected GitHub Release) |
| 72 | |
| 73 | The source-candidate wrapper recognizes Android arm64 and resolves the |
| 74 | Termux-native `codewhale`, `codew`, and `codewhale-tui` assets. That path works |
| 75 | only for package versions whose matching GitHub Release publishes all three |
| 76 | assets, and remains preview support pending real-device QA. See the support |
| 77 | table in [docs/INSTALL.md](https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md). |
| 78 | |
| 79 | HarmonyOS PC (`openharmony`) is treated as `linux`, so it gets the Linux |
| 80 | binaries matching your CPU architecture (x64 or arm64). Linux riscv64 prebuilts |
| 81 | are temporarily paused while the locked `rquickjs-sys` dependency lacks |
| 82 | `riscv64gc-unknown-linux-gnu` bindings. Other platform/architecture combinations |
| 83 | (FreeBSD, Linux riscv64, …) aren't shipped as prebuilts. Unsupported platforms, |
| 84 | checksum failures, and glibc compatibility problems still fail with a clear |
| 85 | error pointing you at the full |
| 86 | [docs/INSTALL.md](https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md) |
| 87 | guide. |
| 88 | |
| 89 | ## Wrapper configuration |
| 90 | |
| 91 | | Setting | What it does | |
| 92 | | --- | --- | |
| 93 | | `codewhaleBinaryVersion` in `package.json` | Default native binary version. `deepseekBinaryVersion` is still read as a backward-compat fallback. | |
| 94 | | `CODEWHALE_RELEASE_BASE_URL` | Canonical override: use an internal or mirrored release-asset directory when GitHub Releases is unavailable. 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. | |
| 95 | | `CODEWHALE_USE_CNB_MIRROR=1` | Download from the CNB (China-friendly) mirror on Linux x64 and OpenHarmony x64. Other targets fail with a clear unsupported-mirror error; use GitHub or a complete `CODEWHALE_RELEASE_BASE_URL` mirror there. | |
| 96 | | `DEEPSEEK_TUI_VERSION` or `DEEPSEEK_VERSION` | Override the GitHub release version to download. | |
| 97 | | `DEEPSEEK_TUI_GITHUB_REPO` or `DEEPSEEK_GITHUB_REPO` | Override the source repo. Defaults to `Hmbown/CodeWhale`. | |
| 98 | | `DEEPSEEK_TUI_FORCE_DOWNLOAD=1` | Force download even when the cached binary is already present. | |
| 99 | | `DEEPSEEK_TUI_DISABLE_INSTALL=1` | Skip install-time download. | |
| 100 | | `DEEPSEEK_TUI_OPTIONAL_INSTALL=1` | Make install-time retryable download failures warn and exit `0` instead of failing `npm install`. | |
| 101 | | `DEEPSEEK_TUI_SKIP_GLIBC_CHECK=1` | Bypass the Linux glibc preflight check at your own risk (`DEEPSEEK_SKIP_GLIBC_CHECK=1` also works). | |
| 102 | |
| 103 | ### Proxies |
| 104 | |
| 105 | Downloads respect `HTTPS_PROXY` / `HTTP_PROXY` (CONNECT tunneling included) |
| 106 | and `NO_PROXY`, so the wrapper works behind corporate proxies. For fully |
| 107 | offline installs, set `DEEPSEEK_TUI_DISABLE_INSTALL=1` or point |
| 108 | `CODEWHALE_RELEASE_BASE_URL` at a local mirror. |
| 109 | |
| 110 | ## Release integrity |
| 111 | |
| 112 | - `npm publish` runs a release-asset check to ensure the required binaries, |
| 113 | archives, Windows installer, and checksum manifests exist for the target |
| 114 | GitHub release before publishing. |
| 115 | - For the default GitHub Release source, `npm run release:check` also verifies |
| 116 | that those release assets were updated by a successful `release.yml` run for |
| 117 | the tag commit. When `CODEWHALE_RELEASE_BASE_URL` or a legacy mirror override |
| 118 | is set, it checks the mirror asset URLs and checksum manifests instead. |
| 119 | - Install-time downloads are verified against the release checksum manifest before |
| 120 | the wrapper marks them executable. |
| 121 | |
| 122 | ## Links |
| 123 | |
| 124 | - Repository: <https://github.com/Hmbown/CodeWhale> |
| 125 | - Website: <https://codewhale.net/> |
| 126 | - Provider registry: [docs/PROVIDERS.md](https://github.com/Hmbown/CodeWhale/blob/main/docs/PROVIDERS.md) |
| 127 | - Changelog: [CHANGELOG.md](https://github.com/Hmbown/CodeWhale/blob/main/CHANGELOG.md) |
| 128 |