Skip to content

docs(rebrand): clarify state migration paths #2549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
cyq1017 wants to merge 2 commits into from
+44 −5
Closed

docs(rebrand): clarify state migration paths #2549

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c8b440d
docs(rebrand): clarify state migration paths
cyq1017 Jun 1, 2026
b1f478c
docs(rebrand): address migration review notes
cyq1017 Jun 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 44 additions & 5 deletions docs/REBRAND.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,10 @@ codewhale doctor
codewhale
```

Your `~/.deepseek/config.toml`, `~/.deepseek/sessions/`, `~/.deepseek/skills/`,
`~/.deepseek/tasks/`, and `~/.deepseek/mcp.json` are untouched. Existing
Your existing `~/.deepseek/config.toml`, `~/.deepseek/sessions/`,
`~/.deepseek/skills/`, `~/.deepseek/tasks/`, and `~/.deepseek/mcp.json` are
not deleted. New CodeWhale installs prefer `~/.codewhale/`, and legacy
`~/.deepseek/` state remains a read fallback while you migrate. Existing
`DEEPSEEK_*` environment variables continue to work.

## What got renamed
Expand All @@ -38,6 +40,13 @@ Your `~/.deepseek/config.toml`, `~/.deepseek/sessions/`, `~/.deepseek/skills/`,
| Release assets | `deepseek-<platform>` / `deepseek-tui-<platform>` | `codewhale-<platform>` / `codewhale-tui-<platform>` |
| Checksum manifest | `deepseek-artifacts-sha256.txt` | `codewhale-artifacts-sha256.txt` |

## What changed for local state

New installs write product-owned state under `~/.codewhale/`. Existing
`~/.deepseek/` config, sessions, skills, tasks, MCP config, memory, and notes
remain readable as legacy fallbacks while you migrate. CodeWhale never deletes
the legacy directory automatically.

## What did NOT change

Anything that targets the DeepSeek provider API stays exactly as it was:
Expand All @@ -52,9 +61,6 @@ Anything that targets the DeepSeek provider API stays exactly as it was:
aliases `deepseek-chat` and `deepseek-reasoner`.
- **Hosts**: `api.deepseek.com` (global) and `api.deepseeki.com` (China
fallback).
- **Config directory**: `~/.deepseek/`. Renaming this would invalidate
every existing install's saved API key, sessions, skills, MCP config,
and audit log.
- **GitHub repository URL**: `https://github.com/Hmbown/CodeWhale`.
The old `Hmbown/DeepSeek-TUI` URL redirects there during the transition.
- **Homebrew tap and formula** (`Hmbown/homebrew-deepseek-tui`): still
Expand Down Expand Up @@ -117,6 +123,39 @@ A second checksum manifest, `deepseek-artifacts-sha256.txt`, is attached as
an alias of `codewhale-artifacts-sha256.txt` so v0.8.40's hardcoded lookup
still verifies.

### Sessions, skills, and manual workspaces

Renaming the binary does not require starting over:

- **Config**: on first launch, CodeWhale copies `~/.deepseek/config.toml` to
`~/.codewhale/config.toml` if the CodeWhale file does not already exist.
It never overwrites a newer CodeWhale config. You can inspect the active path
with `codewhale doctor`.
- **Sessions and tasks**: managed state is read from `~/.codewhale/...` when
present, with `~/.deepseek/...` used as the legacy fallback when only the old
directory exists. Existing saved sessions still appear in `codewhale sessions`
and the TUI resume picker.
- **Skills**: CodeWhale discovers workspace skills first, then global skills,
including both `~/.codewhale/skills` and legacy `~/.deepseek/skills`. Existing
skill directories with `SKILL.md` do not need to be rewritten.
- **MCP config**: the default path is `~/.codewhale/mcp.json`. If that file is
absent, CodeWhale still reads legacy `~/.deepseek/mcp.json`. To use a custom
MCP config file, set `mcp_config_path` in `config.toml` or
`DEEPSEEK_MCP_CONFIG`.
- **Manual binary installs**: keep the dispatcher and TUI binaries as siblings
on your `PATH`: `codewhale` plus `codewhale-tui`. On Windows, the recommended
user-local location is `%LOCALAPPDATA%\Programs\CodeWhale\bin`. On Unix-like
systems, any user-writable `PATH` directory is fine as long as both binaries
are present.
- **Specified work directories**: running `codewhale` from a project directory,
or launching it with a specific workspace path, does not move project files.
CodeWhale reads `<workspace>/.codewhale/config.toml` first and falls back to
legacy `<workspace>/.deepseek/config.toml` when the new path is absent.

If both `~/.codewhale/...` and `~/.deepseek/...` copies exist, the CodeWhale
path wins. Keep the legacy directory until you have confirmed `codewhale
doctor`, `codewhale sessions`, and your expected skills all show the same state.
Comment on lines +126 to +157
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 MCP config migration path not covered in the new section

The TL;DR (line 27) and the "Legacy state compatibility" bullet both mention ~/.deepseek/mcp.json as a fallback, but the new "Sessions, skills, and manual workspaces" section — which otherwise carefully enumerates config, sessions, tasks, skills, binaries, and workspace configs — omits MCP config entirely. Users who rely on custom MCP servers will notice the gap. Adding a short bullet for MCP (similar in style to the Skills bullet) would make the section complete.

Fix in Codex Fix in Claude Code Fix in Cursor


## Why the name change

CodeWhale is a shorter, terminal-friendlier handle for the same terminal
Expand Down
Loading