| 1 | # Rebrand: DeepSeek TUI → Codewhale |
| 2 | |
| 3 | > 阅读简体中文版：[zh_hans/REBRAND.md](zh_hans/REBRAND.md)。 |
| 4 | |
| 5 | Starting with **v0.8.41**, this project ships under a new name: `codewhale`. |
| 6 | |
| 7 | This document explains what changed, what didn't, and how to migrate. None of the |
| 8 | DeepSeek provider integration changed — only the local CLI / TUI brand. |
| 9 | |
| 10 | ## TL;DR |
| 11 | |
| 12 | ```bash |
| 13 | # 1. Uninstall the old wrapper or binaries. |
| 14 | npm uninstall -g deepseek-tui # or: |
| 15 | cargo uninstall deepseek-tui-cli 2>/dev/null || true |
| 16 | cargo uninstall deepseek-tui 2>/dev/null || true |
| 17 | # Homebrew: |
| 18 | # brew upgrade codewhale |
| 19 | |
| 20 | # 2. Install under the new name. |
| 21 | npm install -g codewhale # or: |
| 22 | cargo install codewhale-cli --locked |
| 23 | # Homebrew: |
| 24 | # brew tap Hmbown/deepseek-tui |
| 25 | # brew install codewhale |
| 26 | |
| 27 | # 3. Run with the new command. |
| 28 | codewhale doctor |
| 29 | codewhale |
| 30 | ``` |
| 31 | |
| 32 | Your existing `~/.deepseek/config.toml`, `~/.deepseek/sessions/`, |
| 33 | `~/.deepseek/skills/`, `~/.deepseek/tasks/`, and `~/.deepseek/mcp.json` are |
| 34 | not deleted. New Codewhale installs prefer `~/.codewhale/`, and legacy |
| 35 | `~/.deepseek/` state remains a read fallback while you migrate. Existing |
| 36 | `DEEPSEEK_*` environment variables continue to work. |
| 37 | |
| 38 | ## What got renamed |
| 39 | |
| 40 | | Surface | Before | After | |
| 41 | |---|---|---| |
| 42 | | Installed commands | `deepseek` / `deepseek-tui` | `codewhale` / `codew` | |
| 43 | | npm wrapper package | `deepseek-tui` | `codewhale` | |
| 44 | | Crates.io crates | `deepseek-tui-cli` / `deepseek-tui` / `deepseek-*` | `codewhale-cli` / `codewhale-tui` / `codewhale-*` | |
| 45 | | Release assets | `deepseek-<platform>` / `deepseek-tui-<platform>` | `codewhale-<platform>` / `codew-<platform>`; `codewhale-tui-<platform>` remains a compatibility-only filename | |
| 46 | | Checksum manifest | `deepseek-artifacts-sha256.txt` | `codewhale-artifacts-sha256.txt` | |
| 47 | |
| 48 | ## What changed for local state |
| 49 | |
| 50 | New installs write product-owned state under `~/.codewhale/`. Existing |
| 51 | `~/.deepseek/` config, sessions, skills, tasks, MCP config, memory, and notes |
| 52 | remain readable as legacy fallbacks while you migrate. Codewhale never deletes |
| 53 | the legacy directory automatically. |
| 54 | |
| 55 | ## What did NOT change |
| 56 | |
| 57 | Anything that targets the DeepSeek provider API stays exactly as it was: |
| 58 | |
| 59 | - **Environment variables**: `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`, |
| 60 | `DEEPSEEK_MODEL`, `DEEPSEEK_PROVIDER`, `DEEPSEEK_PROFILE`, |
| 61 | `DEEPSEEK_LOG_LEVEL`, plus the existing `DEEPSEEK_TUI_*` runtime knobs |
| 62 | (`DEEPSEEK_TUI_BIN`, `DEEPSEEK_TUI_RELEASE_BASE_URL`, etc.). They're kept |
| 63 | for backward compatibility; renaming them would break every shell rc on |
| 64 | the planet. |
| 65 | - **`DEEPSEEK_YOLO`**: now deprecated, but still read as an alias of |
| 66 | `CODEWHALE_YOLO` through 0.9.x so existing scripts keep working (when both |
| 67 | are set, `CODEWHALE_YOLO` wins). It is removed in 0.10 (#5443); use |
| 68 | `CODEWHALE_YOLO` in new scripts. |
| 69 | - **Model IDs**: `deepseek-v4-pro`, `deepseek-v4-flash`, and the legacy |
| 70 | aliases `deepseek-chat` and `deepseek-reasoner`. |
| 71 | - **Hosts**: `api.deepseek.com` (global). The legacy typo host |
| 72 | `api.deepseeki.com` is not an official DeepSeek endpoint; it is only |
| 73 | still accepted in URL heuristics for existing configs and is not |
| 74 | offered as a fallback (#1079). |
| 75 | - **GitHub repository URL**: `https://github.com/codewhale-hq/CodeWhale`. |
| 76 | The old `Hmbown/DeepSeek-TUI` URL redirects there during the transition. |
| 77 | - **Homebrew tap and formula**: the formula is `codewhale`. The tap GitHub |
| 78 | repo is still `Hmbown/homebrew-deepseek-tui` until it is renamed; |
| 79 | `brew tap Hmbown/deepseek-tui && brew install codewhale` is the current |
| 80 | path. The legacy `deepseek-tui` formula remains a deprecated alias for |
| 81 | one overlap release. |
| 82 | - **Docker image**: `ghcr.io/codewhale-hq/codewhale`. |
| 83 | |
| 84 | ## Deprecation shims (removed in v0.9.0) |
| 85 | |
| 86 | To keep existing shell aliases, scripts, and CI working through the rename, |
| 87 | v0.8.41 and later v0.8.x releases shipped **deprecation shims**: |
| 88 | |
| 89 | - A `deepseek` binary that prints a one-line warning to stderr and forwards |
| 90 | argv to `codewhale`. |
| 91 | - A `deepseek-tui` binary that does the same for `codewhale-tui`. |
| 92 | - The legacy `deepseek-tui` npm package is deprecated and no longer receives |
| 93 | new releases. Install the `codewhale` npm package instead. |
| 94 | |
| 95 | These binary shims are removed in **v0.9.0**. DeepSeek provider support, model |
| 96 | IDs, `DEEPSEEK_*` environment variables, and legacy `~/.deepseek/` state |
| 97 | fallbacks remain supported. |
| 98 | |
| 99 | ## Migrating in practice |
| 100 | |
| 101 | ### npm |
| 102 | |
| 103 | ```bash |
| 104 | npm uninstall -g deepseek-tui |
| 105 | npm install -g codewhale |
| 106 | ``` |
| 107 | |
| 108 | ### Cargo |
| 109 | |
| 110 | ```bash |
| 111 | cargo uninstall deepseek-tui-cli 2>/dev/null || true |
| 112 | cargo uninstall deepseek-tui 2>/dev/null || true |
| 113 | cargo install codewhale-cli --locked |
| 114 | ``` |
| 115 | |
| 116 | Or in a checkout: |
| 117 | |
| 118 | ```bash |
| 119 | cargo install --path crates/cli --locked --force |
| 120 | ``` |
| 121 | |
| 122 | Cargo installs the canonical `codewhale` command. Release/npm/Homebrew |
| 123 | installers also provide the byte-identical `codew` short name; Cargo users can |
| 124 | add an optional `codew` symlink beside `codewhale`. |
| 125 | |
| 126 | ### Legacy `deepseek update` |
| 127 | |
| 128 | Current v0.8.x compatibility binaries recognize when they are running under a |
| 129 | legacy `deepseek` or `deepseek-tui` filename. In that case, `deepseek update` |
| 130 | or `deepseek-tui update` downloads the canonical Codewhale release assets and |
| 131 | installs them beside the legacy binary as `codewhale` and `codewhale-tui` when |
| 132 | the install directory is writable. That describes the historical v0.8 |
| 133 | compatibility updater, not the current install surface; after upgrading, use |
| 134 | `codewhale` or `codew`. |
| 135 | |
| 136 | If that update path cannot write to the install directory, use the npm, Cargo, |
| 137 | Homebrew, or manual reinstall commands above. The legacy npm package |
| 138 | `deepseek-tui` remains deprecated and is not republished; npm users should move |
| 139 | to `npm install -g codewhale`. |
| 140 | |
| 141 | ### Homebrew |
| 142 | |
| 143 | **Historical migration state as of v0.9.13 (published 2026-09-14):** The |
| 144 | formula is `codewhale`. New installs: |
| 145 | |
| 146 | ```bash |
| 147 | brew tap Hmbown/deepseek-tui |
| 148 | brew install codewhale |
| 149 | brew upgrade codewhale |
| 150 | ``` |
| 151 | |
| 152 | The tap GitHub repo is still `Hmbown/homebrew-deepseek-tui` until it is |
| 153 | renamed to `Hmbown/homebrew-codewhale` (then `brew tap codewhale-hq/codewhale` |
| 154 | works; the old tap name keeps working through GitHub's redirect). The |
| 155 | legacy `deepseek-tui` formula remains a deprecated alias for this overlap |
| 156 | release so existing `brew upgrade deepseek-tui` crontabs keep working. |
| 157 | |
| 158 | **Remaining rollout:** |
| 159 | |
| 160 | 1. Rename the tap repo to `Hmbown/homebrew-codewhale` when adding |
| 161 | `HOMEBREW_TAP_PAT`, then tell Codewhalebot. |
| 162 | 2. After one more minor release, remove the `deepseek-tui` alias. |
| 163 | |
| 164 | ### Manual / GitHub Releases |
| 165 | |
| 166 | `v0.8.41` through `v0.8.x` Releases attached the canonical `codewhale-*` / |
| 167 | `codewhale-tui-*` assets (plus `codew-*` from v0.8.66 onward) and |
| 168 | compatibility-only `deepseek-*` / `deepseek-tui-*` shim assets. Starting in |
| 169 | v0.9.0, Releases attach the current `codewhale-*` / `codew-*` assets, the |
| 170 | `codewhale-artifacts-sha256.txt` checksum manifest, and byte-identical |
| 171 | `codewhale-tui-*` compatibility filenames required by legacy update clients. |
| 172 | Those compatibility filenames are not a third installed command. Install or |
| 173 | update through `codewhale` before moving to v0.9.0. |
| 174 | |
| 175 | ### Sessions, skills, and manual workspaces |
| 176 | |
| 177 | Renaming the binary does not require starting over: |
| 178 | |
| 179 | - **Config**: on first launch, Codewhale copies `~/.deepseek/config.toml` to |
| 180 | `~/.codewhale/config.toml` if the Codewhale file does not already exist. |
| 181 | It never overwrites a newer Codewhale config. You can inspect the active path |
| 182 | with `codewhale doctor`. |
| 183 | - **Sessions and tasks**: managed state is read from `~/.codewhale/...` when |
| 184 | present, with `~/.deepseek/...` used as the legacy fallback when only the old |
| 185 | directory exists. Existing saved sessions still appear in `codewhale sessions` |
| 186 | and the TUI resume picker. |
| 187 | - **Skills**: Codewhale discovers workspace skills first, then global skills, |
| 188 | including both `~/.codewhale/skills` and legacy `~/.deepseek/skills`. Existing |
| 189 | skill directories with `SKILL.md` do not need to be rewritten. |
| 190 | - **MCP config**: the default path is `~/.codewhale/mcp.json`. If that file is |
| 191 | absent, Codewhale still reads legacy `~/.deepseek/mcp.json`. To use a custom |
| 192 | MCP config file, set `mcp_config_path` in `config.toml` or |
| 193 | `DEEPSEEK_MCP_CONFIG`. |
| 194 | - **Manual binary installs**: keep the two current command files together on |
| 195 | your `PATH`: `codewhale` and `codew`. On Windows, the |
| 196 | recommended user-local location is `%LOCALAPPDATA%\Programs\CodeWhale\bin`. |
| 197 | On Unix-like systems, any user-writable `PATH` directory is fine as long as |
| 198 | both commands are present. Do not install a compatibility-only |
| 199 | `codewhale-tui-*` release filename as a third command. |
| 200 | - **Specified work directories**: running `codewhale` from a project directory, |
| 201 | or launching it with a specific workspace path, does not move project files. |
| 202 | Codewhale reads `<workspace>/.codewhale/config.toml` first and falls back to |
| 203 | legacy `<workspace>/.deepseek/config.toml` when the new path is absent. |
| 204 | |
| 205 | If both `~/.codewhale/...` and `~/.deepseek/...` copies exist, the Codewhale |
| 206 | path wins. Keep the legacy directory until you have confirmed `codewhale |
| 207 | doctor`, `codewhale sessions`, and your expected skills all show the same state. |
| 208 | |
| 209 | ### If sessions appear missing after an upgrade |
| 210 | |
| 211 | Run `codewhale doctor` before copying or deleting anything. Doctor compares |
| 212 | top-level session JSON **filenames and filesystem metadata only** between |
| 213 | `~/.deepseek/sessions/` and `~/.codewhale/sessions/`. It does not read chat |
| 214 | contents, traverse `checkpoints/`, or modify either directory. The JSON form |
| 215 | exposes the same result at `legacy_state.session_recovery`. |
| 216 | |
| 217 | If doctor lists recoverable filenames: |
| 218 | |
| 219 | 1. Back up both session directories (if present) and close other Codewhale |
| 220 | processes. |
| 221 | 2. Run `codewhale sessions`. This invokes the existing additive migration, |
| 222 | which creates only missing destination files, never overwrites a file that |
| 223 | already exists under `~/.codewhale/sessions/`, skips checkpoint internals, |
| 224 | and leaves every legacy original in place. |
| 225 | 3. Rerun `codewhale doctor`, then confirm the sessions appear with `codewhale |
| 226 | sessions`. If any filenames remain listed, keep both backups and report the |
| 227 | listed source/destination filenames without sharing chat contents. |
| 228 | |
| 229 | An explicit `CODEWHALE_HOME` intentionally isolates that home and disables the |
| 230 | ambient `~/.deepseek` fallback. Doctor will not inspect the ambient legacy home |
| 231 | in that mode. To diagnose the default home without changing the isolated one, |
| 232 | use a separate shell with `CODEWHALE_HOME` unset and rerun `codewhale doctor`. |
| 233 | |
| 234 | ## Why the name change |
| 235 | |
| 236 | Codewhale is a shorter, terminal-friendlier handle for the same terminal |
| 237 | coding agent and the longer-term product direction: an agentic terminal for |
| 238 | open source and open-weight coding models, with DeepSeek — the provider the |
| 239 | project started with — remaining first-class alongside every other provider. The project name, |
| 240 | command names, package names, release assets, Docker image, and CNB mirror move |
| 241 | to Codewhale; the official DeepSeek provider, model IDs, env vars, and |
| 242 | `~/.deepseek/` config surface remain first-class. |
| 243 | |
| 244 | ## Reporting issues with the rename |
| 245 | |
| 246 | If your install broke during the migration, please open an issue at |
| 247 | <https://github.com/codewhale-hq/CodeWhale/issues> and include: |
| 248 | |
| 249 | - The output of `codewhale --version` (or `deepseek --version` if you're |
| 250 | still on the shim). |
| 251 | - Which install path you used (npm, cargo, brew, manual). |
| 252 | - The exact command you ran and the full error output. |
| 253 | |
| 254 | We'll prioritize migration regressions. |
| 255 |