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