dgf1988/codewhale
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(brand): rename to codewhale across READMEs and docs

Browse Source 
Sweep brand mentions of `DeepSeek TUI` / `deepseek-tui` / bare
`deepseek` (the dispatcher binary) across all user-facing docs to
the new `codewhale` brand. The DeepSeek **provider** integration is
left untouched throughout: env vars (`DEEPSEEK_*`), model IDs
(`deepseek-v4-pro`, `deepseek-v4-flash`, `deepseek-chat`,
`deepseek-reasoner`), the `api.deepseek.com` host, the
`~/.deepseek/` config dir, and the `--provider deepseek` argument
value all keep the legacy spelling.

Anti-scope items deliberately left as the legacy `deepseek-tui`:

- Homebrew tap and formula (`Hmbown/homebrew-deepseek-tui`,
  `brew install deepseek-tui`, `scoop install deepseek-tui`). The
  tap rename ships separately.
- Docker image (`ghcr.io/hmbown/deepseek-tui`). Image-tag rename
  ships separately.
- CNB mirror namespace (`cnb.cool/deepseek-tui.com/DeepSeek-TUI`).
  Third-party hosted path.
- Security contact email (`security@deepseek-tui.com`).
- GitHub repo URL (`Hmbown/DeepSeek-TUI`).

New artifact:

- `docs/REBRAND.md` documents what changed, what didn't, the
  deprecation window, and migration commands for npm / Cargo /
  Homebrew / manual installs.

CHANGELOG entries:

- Root `CHANGELOG.md` and `crates/tui/CHANGELOG.md` both gain a
  new `[Unreleased]` section describing the rename and the one-
  release deprecation window. Historical entries are untouched.

Issue templates:

- `.github/ISSUE_TEMPLATE/bug_report.md` and `feature_request.md`
  refer to "codewhale" / `codewhale --version` instead of the old
  brand name in their environment fields.

The rebrand sweep was driven by a perl script with bulk patterns
(`deepseek-tui` -> `codewhale-tui`, `DeepSeek TUI` -> `codewhale`,
bare `deepseek` -> `codewhale` with provider/model/host/env-var/
config-path negative lookbehind/lookahead) followed by targeted
reverts for the anti-scope items above. Output was visually
reviewed file-by-file before committing.

Verified:

- `cargo check --workspace --all-targets --locked` — pass.
- `cargo test --workspace --all-features --locked` — pass (no
  test source touched here; suite stayed green to confirm no
  doc-from-string assertions broke).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hunter Bown
2026-05-23 11:25:48 -05:00
parent 23daefbe24
commit a3acdbe70b
25 changed files with 760 additions and 571 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+3 -3
View File
@@ -1,6 +1,6 @@
# DeepSeek TUI Architecture
# codewhale Architecture
This document provides an overview of the DeepSeek TUI architecture for developers and contributors.
This document provides an overview of the codewhale architecture for developers and contributors.
Current boundary note (v0.8.6):
- `crates/tui` is still the live end-user runtime for the TUI, runtime API, task manager, and tool execution loop.
@@ -178,7 +178,7 @@ drives turns through Chat Completions.
- **`prompts.rs`** - System prompt templates
- **`project_doc.rs`** - Project documentation handling
- **`session.rs`** - Session serialization
- **`runtime_api.rs`** - HTTP/SSE runtime API (`deepseek serve --http`)
- **`runtime_api.rs`** - HTTP/SSE runtime API (`codewhale serve --http`)
- **`runtime_threads.rs`** - Durable thread/turn/item store + replayable event timeline
- **`task_manager.rs`** - Durable queue, worker pool, task timelines and artifacts
docs/CNB_MIRROR.md
+11 -11
View File
@@ -38,9 +38,9 @@ mirror carry them to CNB.
When CNB receives a `v*` tag, the root `.cnb.yml` tag pipeline builds Linux x64
release assets from source and publishes a CNB release with:
- `deepseek-linux-x64`
- `deepseek-tui-linux-x64`
- `deepseek-artifacts-sha256.txt`
- `codewhale-linux-x64`
- `codewhale-tui-linux-x64`
- `codewhale-artifacts-sha256.txt`
This gives users who can reach CNB but not GitHub a CNB-native release path.
GitHub remains the canonical full release matrix; the CNB tag pipeline is the
@@ -144,7 +144,7 @@ expired:
```
4. Confirm the run succeeds via `gh run list --workflow=sync-cnb.yml`.
## Binary release assets and `deepseek update`
## Binary release assets and `codewhale update`
CNB now builds Linux x64 assets for `v*` tags from the source-controlled
`.cnb.yml` pipeline. GitHub remains the canonical full release matrix. Users
@@ -152,24 +152,24 @@ behind GitHub-blocking networks should use one of these paths:
- **`cargo install`** from the CNB mirror:
```bash
cargo install --git https://cnb.cool/deepseek-tui.com/DeepSeek-TUI --tag vX.Y.Z deepseek-tui-cli
cargo install --git https://cnb.cool/deepseek-tui.com/DeepSeek-TUI --tag vX.Y.Z deepseek-tui
cargo install --git https://cnb.cool/deepseek-tui.com/DeepSeek-TUI --tag vX.Y.Z codewhale-cli
cargo install --git https://cnb.cool/deepseek-tui.com/DeepSeek-TUI --tag vX.Y.Z codewhale-tui
```
(Both binaries are required — the dispatcher and the TUI ship
separately; see `AGENTS.md` for the two-binary install rationale.)
- **CNB release assets** for Linux x64, when the matching CNB tag pipeline has
completed successfully. Download `deepseek-linux-x64`,
`deepseek-tui-linux-x64`, and `deepseek-artifacts-sha256.txt` from the CNB
completed successfully. Download `codewhale-linux-x64`,
`codewhale-tui-linux-x64`, and `codewhale-artifacts-sha256.txt` from the CNB
release for `vX.Y.Z`, then verify the binaries against the manifest.
- **`DEEPSEEK_TUI_RELEASE_BASE_URL`** environment variable, if a
CDN mirror of release assets exists. The npm
wrapper installer and `deepseek update` read this variable to redirect
binary downloads. For `deepseek update`, also set
wrapper installer and `codewhale update` read this variable to redirect
binary downloads. For `codewhale update`, also set
`DEEPSEEK_TUI_VERSION=X.Y.Z` so the updater can label the mirrored
release without contacting GitHub. The directory pointed to must contain
`deepseek-artifacts-sha256.txt` and the platform binaries; format matches
`codewhale-artifacts-sha256.txt` and the platform binaries; format matches
a GitHub Release asset directory.
## Tencent Cloud remote-first path
docs/CONFIGURATION.md
+40 -40
View File
@@ -1,6 +1,6 @@
# Configuration
DeepSeek TUI reads configuration from a TOML file plus environment variables.
codewhale reads configuration from a TOML file plus environment variables.
At process startup it also loads a workspace-local `.env` file when present.
Use the tracked `.env.example` as the template; copy it to `.env`, then edit
only the provider and safety knobs you need.
@@ -13,7 +13,7 @@ Default config path:
Overrides:
- CLI: `deepseek --config /path/to/config.toml`
- CLI: `codewhale --config /path/to/config.toml`
- Env: `DEEPSEEK_CONFIG_PATH=/path/to/config.toml`
If both are set, `--config` wins. Environment variable overrides are applied after the file is loaded.
@@ -49,28 +49,28 @@ Other settings (skills_dir, hooks, capacity, retry, etc.) stay
user-global. If your repo needs more, file an issue describing the
specific use case.
The `deepseek` facade and `deepseek-tui` binary share the same config file for
DeepSeek auth and model defaults. `deepseek auth set --provider deepseek` (and
the legacy `deepseek login --api-key ...` alias) saves the key to
`~/.deepseek/config.toml`, and `deepseek --model deepseek-v4-flash` is forwarded
The `codewhale` facade and `codewhale-tui` binary share the same config file for
DeepSeek auth and model defaults. `codewhale auth set --provider deepseek` (and
the legacy `codewhale login --api-key ...` alias) saves the key to
`~/.deepseek/config.toml`, and `codewhale --model deepseek-v4-flash` is forwarded
to the TUI as `DEEPSEEK_MODEL`.
Credential lookup uses `config -> keyring -> env` after any explicit CLI
`--api-key`. Run `deepseek auth status` to inspect the active provider's config
`--api-key`. Run `codewhale auth status` to inspect the active provider's config
file, OS keyring backend, environment variable, winning source, and last-four
label without printing the key itself. The command only probes the active
provider's keyring entry.
For hosted, generic OpenAI-compatible, or self-hosted providers, set
`provider = "nvidia-nim"`, `"openai"`, `"atlascloud"`, `"wanjie-ark"`, `"fireworks"`,
`"sglang"`, `"vllm"`, or `"ollama"` or pass `deepseek --provider <name>`. The facade saves provider
`"sglang"`, `"vllm"`, or `"ollama"` or pass `codewhale --provider <name>`. The facade saves provider
credentials to the shared user config and forwards the resolved key, base URL,
provider, and model to the TUI process. Use
`deepseek auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"` or
`deepseek auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"` or
`deepseek auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY"` or
`deepseek auth set --provider wanjie-ark --api-key "YOUR_WANJIE_API_KEY"` or
`deepseek auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"` to
`codewhale auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"` or
`codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"` or
`codewhale auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY"` or
`codewhale auth set --provider wanjie-ark --api-key "YOUR_WANJIE_API_KEY"` or
`codewhale auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"` to
save provider keys through the facade. The generic `openai` provider defaults
to `https://api.openai.com/v1`, accepts `OPENAI_BASE_URL`, and passes model IDs
through unchanged for OpenAI-compatible gateways. `atlascloud` defaults to
@@ -81,7 +81,7 @@ Wanjie Ark's OpenAI-compatible endpoint at
and passes model IDs through unchanged because Wanjie model access is
account-scoped. SGLang, vLLM, and Ollama are
self-hosted and can run without an API key by default. Ollama defaults to
`http://localhost:11434/v1` and sends model tags such as `deepseek-coder:1.3b`
`http://localhost:11434/v1` and sends model tags such as `codewhale-coder:1.3b`
or `qwen2.5-coder:7b` unchanged. Self-hosted providers and loopback custom
URLs (`localhost`, `127.0.0.1`, `[::1]`, `0.0.0.0`) do not read the secret store
unless API-key auth is explicitly requested; use an env var or config-file key
@@ -113,27 +113,27 @@ when they use localhost or loopback addresses. For a non-local `http://`
gateway, launch with `DEEPSEEK_ALLOW_INSECURE_HTTP=1` only on a trusted network:
```bash
DEEPSEEK_ALLOW_INSECURE_HTTP=1 deepseek
DEEPSEEK_ALLOW_INSECURE_HTTP=1 codewhale
```
Third-party OpenAI-compatible gateways that need extra request headers can set
`http_headers = { "X-Model-Provider-Id" = "your-model-provider" }` at the top
level or under a provider table such as `[providers.deepseek]`. When configured,
DeepSeek TUI sends those custom headers on model API requests. The equivalent
codewhale sends those custom headers on model API requests. The equivalent
environment override is `DEEPSEEK_HTTP_HEADERS`, using comma-separated
`name=value` pairs such as
`X-Model-Provider-Id=your-model-provider,X-Gateway-Route=dev`. `Authorization`
and `Content-Type` are managed by the client and are not overridden by this
setting.
To bootstrap MCP and skills directories at their resolved paths, run `deepseek-tui setup`.
To only scaffold MCP, run `deepseek-tui mcp init`.
To bootstrap MCP and skills directories at their resolved paths, run `codewhale-tui setup`.
To only scaffold MCP, run `codewhale-tui mcp init`.
Note: setup, doctor, mcp, features, sessions, resume/fork, exec, review, and eval
are subcommands of the `deepseek-tui` binary. The `deepseek` dispatcher exposes a
are subcommands of the `codewhale-tui` binary. The `codewhale` dispatcher exposes a
distinct set of commands (`auth`, `config`, `model`, `thread`, `sandbox`,
`app-server`, `mcp-server`, `completion`) and forwards plain prompts to
`deepseek-tui`.
`codewhale-tui`.
## Profiles
@@ -184,15 +184,15 @@ default_text_model = "deepseek-ai/DeepSeek-V4-Pro"
[profiles.ollama]
provider = "ollama"
base_url = "http://localhost:11434/v1"
default_text_model = "deepseek-coder:1.3b"
default_text_model = "codewhale-coder:1.3b"
```
Select a profile with:
- CLI: `deepseek --profile work`
- CLI: `codewhale --profile work`
- Env: `DEEPSEEK_PROFILE=work`
If a profile is selected but missing, DeepSeek TUI exits with an error listing available profiles.
If a profile is selected but missing, codewhale exits with an error listing available profiles.
## Environment Variables
@@ -202,7 +202,7 @@ fallbacks after saved config and keyring credentials:
- `DEEPSEEK_API_KEY`
- `DEEPSEEK_BASE_URL`
- `DEEPSEEK_HTTP_HEADERS` (custom model request headers, comma-separated `name=value` pairs)
- `DEEPSEEK_PROVIDER` (`deepseek|nvidia-nim|openai|atlascloud|wanjie-ark|openrouter|novita|fireworks|sglang|vllm|ollama`)
- `DEEPSEEK_PROVIDER` (`codewhale|nvidia-nim|openai|atlascloud|wanjie-ark|openrouter|novita|fireworks|sglang|vllm|ollama`)
- `DEEPSEEK_MODEL` or `DEEPSEEK_DEFAULT_TEXT_MODEL`
- `DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS` (stream idle timeout in seconds; default `300`, clamped to `1..=3600`)
- `DEEPSEEK_STREAM_OPEN_TIMEOUT_SECS` (connection setup + response-header wait in seconds; default `45`, clamped to `5..=300`; distinct from the per-chunk idle timeout)
@@ -322,7 +322,7 @@ round-trip intact.
## Settings File (Persistent UI Preferences)
DeepSeek TUI also stores user preferences in:
codewhale also stores user preferences in:
- `~/.config/deepseek/settings.toml`
@@ -413,7 +413,7 @@ and the capacity controller remains disabled unless configured.
If you are upgrading from older releases:
- Old: `/deepseek`
- Old: `/codewhale`
New: `/links` (aliases: `/dashboard`, `/api`)
- Old: `/set model deepseek-reasoner`
New: `/config` and edit the `model` row to `deepseek-v4-pro` or `deepseek-v4-flash`
@@ -426,10 +426,10 @@ If you are upgrading from older releases:
### Core keys (used by the TUI/engine)
- `provider` (string, optional): `deepseek` (default), `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `openrouter`, `novita`, `fireworks`, `sglang`, `vllm`, or `ollama`. Legacy `deepseek-cn` configs are still accepted as an alias for `deepseek`; DeepSeek uses the same official host [`https://api.deepseek.com`](https://api-docs.deepseek.com/) worldwide. `nvidia-nim` targets NVIDIA's NIM-hosted DeepSeek endpoints through `https://integrate.api.nvidia.com/v1`; `openai` targets a generic OpenAI-compatible endpoint, defaulting to `https://api.openai.com/v1`; `atlascloud` targets AtlasCloud's OpenAI-compatible endpoint at `https://api.atlascloud.ai/v1`; `wanjie-ark` targets Wanjie Ark's OpenAI-compatible endpoint at `https://maas-openapi.wanjiedata.com/api/v1`; `fireworks` targets `https://api.fireworks.ai/inference/v1`; `sglang` targets a self-hosted OpenAI-compatible endpoint, defaulting to `http://localhost:30000/v1`; `vllm` targets a self-hosted vLLM OpenAI-compatible endpoint, defaulting to `http://localhost:8000/v1`; `ollama` targets Ollama's OpenAI-compatible endpoint, defaulting to `http://localhost:11434/v1`.
- `provider` (string, optional): `codewhale` (default), `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `openrouter`, `novita`, `fireworks`, `sglang`, `vllm`, or `ollama`. Legacy `deepseek-cn` configs are still accepted as an alias for `codewhale`; DeepSeek uses the same official host [`https://api.deepseek.com`](https://api-docs.deepseek.com/) worldwide. `nvidia-nim` targets NVIDIA's NIM-hosted DeepSeek endpoints through `https://integrate.api.nvidia.com/v1`; `openai` targets a generic OpenAI-compatible endpoint, defaulting to `https://api.openai.com/v1`; `atlascloud` targets AtlasCloud's OpenAI-compatible endpoint at `https://api.atlascloud.ai/v1`; `wanjie-ark` targets Wanjie Ark's OpenAI-compatible endpoint at `https://maas-openapi.wanjiedata.com/api/v1`; `fireworks` targets `https://api.fireworks.ai/inference/v1`; `sglang` targets a self-hosted OpenAI-compatible endpoint, defaulting to `http://localhost:30000/v1`; `vllm` targets a self-hosted vLLM OpenAI-compatible endpoint, defaulting to `http://localhost:8000/v1`; `ollama` targets Ollama's OpenAI-compatible endpoint, defaulting to `http://localhost:11434/v1`.
- `api_key` (string, required for hosted providers): must be non-empty for DeepSeek/hosted providers (or set the provider API key env var). Self-hosted SGLang, vLLM, and Ollama can omit it.
- `base_url` (string, optional): defaults to `https://api.deepseek.com/beta` for DeepSeek's OpenAI-compatible Chat Completions API, including legacy `provider = "deepseek-cn"` configs, `https://api.openai.com/v1` for `provider = "openai"`, `https://api.atlascloud.ai/v1` for `provider = "atlascloud"`, `https://maas-openapi.wanjiedata.com/api/v1` for `provider = "wanjie-ark"`, or the provider-specific endpoint for hosted/self-hosted providers. Set `https://api.deepseek.com` or `https://api.deepseek.com/v1` explicitly to opt out of DeepSeek beta features.
- `default_text_model` (string, optional): defaults to `deepseek-v4-pro` for DeepSeek, `deepseek-ai/deepseek-v4-pro` for NVIDIA NIM, `gpt-4.1` for generic OpenAI-compatible endpoints, `deepseek-ai/deepseek-v4-flash` for AtlasCloud, `deepseek-reasoner` for Wanjie Ark, `accounts/fireworks/models/deepseek-v4-pro` for Fireworks, `deepseek-ai/DeepSeek-V4-Pro` for SGLang/vLLM, and `deepseek-coder:1.3b` for Ollama. Current public DeepSeek IDs are `deepseek-v4-pro` and `deepseek-v4-flash`, both with 1M context windows, 384K max output, and thinking mode enabled by default. Legacy `deepseek-chat` and `deepseek-reasoner` remain compatibility aliases for `deepseek-v4-flash` until July 24, 2026. Provider-specific mappings translate `deepseek-v4-pro` / `deepseek-v4-flash` to each provider's model ID where supported. Generic `openai`, `atlascloud`, `wanjie-ark`, and Ollama model IDs are passed through unchanged. OpenRouter provider configs with a custom `base_url` also preserve explicit model values, which lets OpenAI-compatible gateways accept bare model IDs. Use `/models` or `deepseek models` to discover live IDs from your configured endpoint. `DEEPSEEK_MODEL` overrides this for a single process.
- `default_text_model` (string, optional): defaults to `deepseek-v4-pro` for DeepSeek, `deepseek-ai/deepseek-v4-pro` for NVIDIA NIM, `gpt-4.1` for generic OpenAI-compatible endpoints, `deepseek-ai/deepseek-v4-flash` for AtlasCloud, `deepseek-reasoner` for Wanjie Ark, `accounts/fireworks/models/deepseek-v4-pro` for Fireworks, `deepseek-ai/DeepSeek-V4-Pro` for SGLang/vLLM, and `codewhale-coder:1.3b` for Ollama. Current public DeepSeek IDs are `deepseek-v4-pro` and `deepseek-v4-flash`, both with 1M context windows, 384K max output, and thinking mode enabled by default. Legacy `deepseek-chat` and `deepseek-reasoner` remain compatibility aliases for `deepseek-v4-flash` until July 24, 2026. Provider-specific mappings translate `deepseek-v4-pro` / `deepseek-v4-flash` to each provider's model ID where supported. Generic `openai`, `atlascloud`, `wanjie-ark`, and Ollama model IDs are passed through unchanged. OpenRouter provider configs with a custom `base_url` also preserve explicit model values, which lets OpenAI-compatible gateways accept bare model IDs. Use `/models` or `codewhale models` to discover live IDs from your configured endpoint. `DEEPSEEK_MODEL` overrides this for a single process.
- `reasoning_effort` (string, optional): `off`, `low`, `medium`, `high`, or `max`; defaults to the configured UI tier. DeepSeek Platform receives top-level `thinking` / `reasoning_effort` fields. NVIDIA NIM receives equivalent settings through `chat_template_kwargs`.
- `allow_shell` (bool, optional): defaults to `true` (sandboxed).
- `approval_policy` (string, optional): `on-request`, `untrusted`, or `never`. Runtime `approval_mode` editing in `/config` also accepts `on-request` and `untrusted` aliases.
@@ -625,10 +625,10 @@ exec_policy = true
You can also override features for a single run:
- `deepseek-tui --enable web_search`
- `deepseek-tui --disable subagents`
- `codewhale-tui --enable web_search`
- `codewhale-tui --disable subagents`
Use `deepseek-tui features list` to inspect known flags and their effective state.
Use `codewhale-tui features list` to inspect known flags and their effective state.
## Web Search Provider
@@ -655,7 +655,7 @@ the composer, press `↑` to select an attachment row, then press `Backspace` or
## Managed Configuration and Requirements
DeepSeek TUI supports a policy layering model:
codewhale supports a policy layering model:
1. user config + profile + env overrides
2. managed config (if present)
@@ -676,17 +676,17 @@ If configured values violate requirements, startup fails with a descriptive erro
See `docs/capacity_controller.md` for formulas, intervention behavior, and telemetry.
## Notes On `deepseek-tui doctor`
## Notes On `codewhale-tui doctor`
`deepseek-tui doctor` follows the same config resolution rules as the rest of the
`codewhale-tui doctor` follows the same config resolution rules as the rest of the
TUI. That means `--config` / `DEEPSEEK_CONFIG_PATH` are respected, and MCP/skills
checks use the resolved `mcp_config_path` / `skills_dir` (including env overrides).
To bootstrap missing MCP/skills paths, run `deepseek-tui setup --all`. You can
also run `deepseek-tui setup --skills --local` to create a workspace-local
To bootstrap missing MCP/skills paths, run `codewhale-tui setup --all`. You can
also run `codewhale-tui setup --skills --local` to create a workspace-local
`./skills` dir.
`deepseek-tui doctor --json` prints a machine-readable report that skips the
`codewhale-tui doctor --json` prints a machine-readable report that skips the
live API connectivity probe. Top-level keys: `version`, `config_path`,
`config_present`, `workspace`, `api_key.source`, `base_url`,
`default_text_model`, `mcp`, `skills`, `tools`, `plugins`, `sandbox`,
@@ -707,7 +707,7 @@ configure reasoning effort.
## Setup status, clean, and extension dirs
`deepseek-tui setup` accepts a few flags beyond the existing `--mcp`,
`codewhale-tui setup` accepts a few flags beyond the existing `--mcp`,
`--skills`, `--local`, `--all`, and `--force`:
- `--status` — print a compact one-screen status (api key, base URL, model,
@@ -732,10 +732,10 @@ configure reasoning effort.
## Why the engine strips XML/`[TOOL_CALL]` text
DeepSeek TUI sends and receives tool calls only over the API tool channel
codewhale sends and receives tool calls only over the API tool channel
(structured `tool_use` / `tool_call` items). The streaming loop in
`crates/tui/src/core/engine.rs` recognizes a fixed set of fake-wrapper start
markers — `[TOOL_CALL]`, `<deepseek:tool_call`, `<tool_call`, `<invoke `,
markers — `[TOOL_CALL]`, `<codewhale:tool_call`, `<tool_call`, `<invoke `,
`<function_calls>` — and scrubs them from visible assistant text without ever
turning them into structured tool calls. When a wrapper is stripped, the loop
emits one compact `status` notice per turn so the user can see why their
docs/DOCKER.md
+13 -13
View File
@@ -12,11 +12,11 @@ docker pull ghcr.io/hmbown/deepseek-tui:latest
Run the published image with a Docker-managed data volume:
```bash
docker volume create deepseek-tui-home
docker volume create codewhale-tui-home
docker run --rm -it \
-e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-v deepseek-tui-home:/home/deepseek/.deepseek \
-v codewhale-tui-home:/home/deepseek/.deepseek \
-v "$PWD:/workspace" \
-w /workspace \
ghcr.io/hmbown/deepseek-tui:latest
@@ -27,7 +27,7 @@ Use a pinned release tag for reproducible installs:
```bash
docker run --rm -it \
-e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-v deepseek-tui-home:/home/deepseek/.deepseek \
-v codewhale-tui-home:/home/deepseek/.deepseek \
-v "$PWD:/workspace" \
-w /workspace \
ghcr.io/hmbown/deepseek-tui:vX.Y.Z
@@ -41,7 +41,7 @@ Replace `vX.Y.Z` with a tag from
Build the image locally from a checkout:
```bash
docker build -t deepseek-tui .
docker build -t codewhale-tui .
```
Then run it with the same Docker-managed data volume:
@@ -49,10 +49,10 @@ Then run it with the same Docker-managed data volume:
```bash
docker run --rm -it \
-e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-v deepseek-tui-home:/home/deepseek/.deepseek \
-v codewhale-tui-home:/home/deepseek/.deepseek \
-v "$PWD:/workspace" \
-w /workspace \
deepseek-tui
codewhale-tui
```
Docker Hub publishing is not configured; GHCR is the supported prebuilt image
@@ -74,13 +74,13 @@ is the safest default because Docker creates it with ownership the container can
write:
```bash
-v deepseek-tui-home:/home/deepseek/.deepseek
-v codewhale-tui-home:/home/deepseek/.deepseek
```
Without this mount the container starts fresh each time.
If you bind-mount an existing host directory instead, the image runs as the
non-root `deepseek` user with UID/GID `1000:1000`. The mounted directory must be
non-root `codewhale` user with UID/GID `1000:1000`. The mounted directory must be
writable by that user, or startup can fail while creating runtime directories
under `.deepseek/tasks`. On Linux hosts, either use the named volume above or
prepare the bind mount explicitly:
@@ -101,8 +101,8 @@ volume instead.
## Non-interactive / pipeline usage
When stdin is not a TTY, `deepseek` drops to the dispatcher's one-shot mode
(`deepseek -c "…"`). Pipe a prompt on stdin:
When stdin is not a TTY, `codewhale` drops to the dispatcher's one-shot mode
(`codewhale -c "…"`). Pipe a prompt on stdin:
```bash
echo "Explain the Cargo.toml in structured English." | \
@@ -113,18 +113,18 @@ echo "Explain the Cargo.toml in structured English." | \
```bash
# Single platform (your host architecture)
docker build -t deepseek-tui .
docker build -t codewhale-tui .
# Multi-platform (requires a builder with emulation)
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t deepseek-tui .
docker buildx build --platform linux/amd64,linux/arm64 -t codewhale-tui .
```
## Devcontainer
The repository includes a [`.devcontainer/devcontainer.json`](../.devcontainer/devcontainer.json)
configuration for VS Code / GitHub Codespaces. It pre-installs the Rust toolchain,
rust-analyzer, and the `deepseek` binary. Open the repo in a devcontainer to get a
rust-analyzer, and the `codewhale` binary. Open the repo in a devcontainer to get a
ready-to-use development environment.
## Release status
docs/INSTALL.md
+77 -77
View File
@@ -1,4 +1,4 @@
# Installing DeepSeek TUI
# Installing codewhale
This page covers every supported install path and the most common
"it didn't install" failures, including **Linux ARM64** and other less
@@ -12,16 +12,16 @@ If you just want the short version, see the
## 1. Supported platforms
`deepseek-tui` ships prebuilt binaries for these
`codewhale-tui` ships prebuilt binaries for these
platform/architecture combinations from v0.8.8 onward:
| Platform | Architecture | npm install | `cargo install` | GitHub release asset |
| ------------ | ------------ | :---------: | :-------------: | ----------------------------------------------------- |
| Linux | x64 (x86_64) | ✅ | ✅ | `deepseek-linux-x64`, `deepseek-tui-linux-x64` |
| Linux | arm64 | ✅ | ✅ | `deepseek-linux-arm64`, `deepseek-tui-linux-arm64` |
| macOS | x64 | ✅ | ✅ | `deepseek-macos-x64`, `deepseek-tui-macos-x64` |
| macOS | arm64 (M-series) | ✅ | ✅ | `deepseek-macos-arm64`, `deepseek-tui-macos-arm64` |
| Windows | x64 | ✅ | ✅ | `deepseek-windows-x64.exe`, `deepseek-tui-windows-x64.exe` |
| Linux | x64 (x86_64) | ✅ | ✅ | `codewhale-linux-x64`, `codewhale-tui-linux-x64` |
| Linux | arm64 | ✅ | ✅ | `codewhale-linux-arm64`, `codewhale-tui-linux-arm64` |
| macOS | x64 | ✅ | ✅ | `codewhale-macos-x64`, `codewhale-tui-macos-x64` |
| macOS | arm64 (M-series) | ✅ | ✅ | `codewhale-macos-arm64`, `codewhale-tui-macos-arm64` |
| Windows | x64 | ✅ | ✅ | `codewhale-windows-x64.exe`, `codewhale-tui-windows-x64.exe` |
| Other Linux (musl, riscv64, …) | — | ❌¹ | ✅² | build from source |
| FreeBSD / OpenBSD | — | ❌ | ✅² | build from source |
@@ -38,8 +38,8 @@ systems such as Alpine should use [Build from source](#7-build-from-source).
> **Linux ARM64 note (v0.8.7 and earlier).** v0.8.7 and earlier do **not**
> publish a Linux ARM64 prebuilt; users on HarmonyOS thin-and-light, Asahi
> Linux, Raspberry Pi, AWS Graviton, etc. saw `Unsupported architecture: arm64`
> from `npm i -g deepseek-tui`. v0.8.8 publishes both `deepseek-linux-arm64`
> and `deepseek-tui-linux-arm64`, so a plain `npm i -g deepseek-tui` works
> from `npm i -g codewhale`. v0.8.8 publishes both `codewhale-linux-arm64`
> and `codewhale-tui-linux-arm64`, so a plain `npm i -g codewhale` works
> on any glibc-based ARM64 Linux. If you're stuck on v0.8.7, jump to
> [Build from source](#7-build-from-source) — `cargo install` works fine.
@@ -49,19 +49,19 @@ systems such as Alpine should use [Build from source](#7-build-from-source).
Official release binaries are published only from
`https://github.com/Hmbown/DeepSeek-TUI/releases` and the npm package named
`deepseek-tui`. Do not install release assets from look-alike repositories,
`codewhale-tui`. Do not install release assets from look-alike repositories,
archives, or search-result mirrors unless you deliberately trust that mirror.
Every GitHub release includes `deepseek-artifacts-sha256.txt`. If you download
Every GitHub release includes `codewhale-artifacts-sha256.txt`. If you download
binaries manually, verify them before running:
```bash
# Run from the directory containing the downloaded binaries.
curl -L -O https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-artifacts-sha256.txt
sha256sum -c deepseek-artifacts-sha256.txt --ignore-missing
curl -L -O https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/codewhale-artifacts-sha256.txt
sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing
```
On macOS, use `shasum -a 256 -c deepseek-artifacts-sha256.txt` instead of
On macOS, use `shasum -a 256 -c codewhale-artifacts-sha256.txt` instead of
`sha256sum`.
If antivirus software flags an official release binary, treat it as unresolved
@@ -70,7 +70,7 @@ the GitHub issue:
- the release tag, for example `v0.8.36`
- the exact download URL
- the filename, for example `deepseek-linux-x64`
- the filename, for example `codewhale-linux-x64`
- the file SHA-256 from your machine
- the antivirus product name and detection name
@@ -82,13 +82,13 @@ a download sourced from an impersonating repository or mirror.
## 3. Install via npm (recommended)
```bash
npm install -g deepseek-tui
deepseek
npm install -g codewhale
codewhale
```
`postinstall` downloads the right pair of binaries from the matching GitHub
release, verifies a SHA-256 manifest, and exposes both `deepseek` and
`deepseek-tui` on your `PATH`.
release, verifies a SHA-256 manifest, and exposes both `codewhale` and
`codewhale-tui` on your `PATH`.
Useful environment variables:
@@ -105,7 +105,7 @@ Useful environment variables:
> (not just the postinstall binary download), use an npm registry mirror:
> ```bash
> npm config set registry https://registry.npmmirror.com
> npm install -g deepseek-tui
> npm install -g codewhale
> ```
> See also [Section 4](#4-install-via-cargo-any-tier-1-rust-target) if you
> prefer Cargo over npm.
@@ -120,9 +120,9 @@ delegates to the TUI runtime at runtime.
```bash
# Requires Rust 1.88+ (https://rustup.rs)
cargo install deepseek-tui-cli --locked # provides `deepseek`
cargo install deepseek-tui --locked # provides `deepseek-tui`
deepseek --version
cargo install codewhale-cli --locked # provides `codewhale`
cargo install codewhale-tui --locked # provides `codewhale-tui`
codewhale --version
```
### China / mirror-friendly install
@@ -201,7 +201,7 @@ If you already have Nix with flake support, run:
nix run github:Hmbown/DeepSeek-TUI
```
Nix builds `deepseek-tui` and then starts the `deepseek` dispatcher. Pass
Nix builds `codewhale-tui` and then starts the `codewhale` dispatcher. Pass
arguments after `--`, for example:
```sh
@@ -217,8 +217,8 @@ Add inputs to `flake.nix`:
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
deepseek-tui.url = "github:Hmbown/DeepSeek-TUI";
deepseek-tui.inputs.nixpkgs.follows = "nixpkgs";
codewhale-tui.url = "github:Hmbown/DeepSeek-TUI";
codewhale-tui.inputs.nixpkgs.follows = "nixpkgs";
};
}
```
@@ -227,7 +227,7 @@ Install into a NixOS module:
```nix
{
outputs = { self, nixpkgs, deepseek-tui }:
outputs = { self, nixpkgs, codewhale-tui }:
let
# replace system "x86_64-linux" with your system
system = "x86_64-linux";
@@ -239,7 +239,7 @@ Install into a NixOS module:
modules = [
# ...
{
environment.systemPackages = [ deepseek-tui.packages.${system}.default ];
environment.systemPackages = [ codewhale-tui.packages.${system}.default ];
}
];
};
@@ -258,32 +258,32 @@ side by side into a directory on your `PATH` (e.g. `~/.local/bin`):
```bash
# Linux ARM64 example
mkdir -p ~/.local/bin
curl -L -o ~/.local/bin/deepseek \
https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-linux-arm64
curl -L -o ~/.local/bin/deepseek-tui \
https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-tui-linux-arm64
chmod +x ~/.local/bin/deepseek ~/.local/bin/deepseek-tui
deepseek --version
curl -L -o ~/.local/bin/codewhale \
https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/codewhale-linux-arm64
curl -L -o ~/.local/bin/codewhale-tui \
https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/codewhale-tui-linux-arm64
chmod +x ~/.local/bin/codewhale ~/.local/bin/codewhale-tui
codewhale --version
```
Verify integrity against the per-release SHA-256 manifest:
```bash
curl -L -o /tmp/deepseek-artifacts-sha256.txt \
https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-artifacts-sha256.txt
( cd ~/.local/bin && sha256sum -c /tmp/deepseek-artifacts-sha256.txt --ignore-missing )
curl -L -o /tmp/codewhale-artifacts-sha256.txt \
https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/codewhale-artifacts-sha256.txt
( cd ~/.local/bin && sha256sum -c /tmp/codewhale-artifacts-sha256.txt --ignore-missing )
```
(Use `shasum -a 256 -c` instead of `sha256sum` on macOS.)
### Windows Scoop
DeepSeek TUI is listed in Scoop's main bucket:
codewhale is listed in Scoop's main bucket:
```powershell
scoop update
scoop install deepseek-tui
deepseek --version
codewhale --version
```
Scoop manifests are maintained outside this repository's release workflow and
@@ -314,10 +314,10 @@ LoongArch, FreeBSD, and pre-2024 ARM64 distros.
git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI
cargo install --path crates/cli --locked # provides `deepseek`
cargo install --path crates/tui --locked # provides `deepseek-tui`
cargo install --path crates/cli --locked # provides `codewhale`
cargo install --path crates/tui --locked # provides `codewhale-tui`
deepseek --version
codewhale --version
```
Both binaries land in `~/.cargo/bin/` by default; make sure that directory is
@@ -336,13 +336,13 @@ rustup target add aarch64-unknown-linux-gnu
cargo install cross --locked
# Per build
cross build --release --target aarch64-unknown-linux-gnu -p deepseek-tui-cli
cross build --release --target aarch64-unknown-linux-gnu -p deepseek-tui
cross build --release --target aarch64-unknown-linux-gnu -p codewhale-cli
cross build --release --target aarch64-unknown-linux-gnu -p codewhale-tui
```
The resulting binaries land in
`target/aarch64-unknown-linux-gnu/release/deepseek` and
`target/aarch64-unknown-linux-gnu/release/deepseek-tui`. Copy the matched pair
`target/aarch64-unknown-linux-gnu/release/codewhale` and
`target/aarch64-unknown-linux-gnu/release/codewhale-tui`. Copy the matched pair
to the ARM64 host (e.g. via `scp`) and `chmod +x` them.
If you don't have Docker available, install the cross-linker directly and let
@@ -357,8 +357,8 @@ cat >> ~/.cargo/config.toml <<'EOF'
linker = "aarch64-linux-gnu-gcc"
EOF
cargo build --release --target aarch64-unknown-linux-gnu -p deepseek-tui-cli
cargo build --release --target aarch64-unknown-linux-gnu -p deepseek-tui
cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-cli
cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-tui
```
The same recipe works for `aarch64-unknown-linux-musl` if your distro is
@@ -420,8 +420,8 @@ set CARGO_HTTP_CHECK_REVOKE=false # may be needed behind some Chinese ISPs
cargo build --release
```
Both binaries appear in `target\release\deepseek.exe` and
`target\release\deepseek-tui.exe`.
Both binaries appear in `target\release\codewhale.exe` and
`target\release\codewhale-tui.exe`.
> **Prefer `npm install -g` on Windows unless you need to modify source.**
> The npm package pulls prebuilt binaries and avoids the C toolchain
@@ -434,30 +434,30 @@ Both binaries appear in `target\release\deepseek.exe` and
### `Unsupported architecture: arm64 on platform linux`
You're on a release earlier than v0.8.8 that doesn't publish Linux ARM64
binaries. Either upgrade (`npm i -g deepseek-tui@latest`) or use
binaries. Either upgrade (`npm i -g codewhale@latest`) or use
`cargo install` per [Section 4](#4-install-via-cargo-any-tier-1-rust-target).
### `MISSING_COMPANION_BINARY` at runtime
The dispatcher (`deepseek`) requires the TUI runtime (`deepseek-tui`) to be on
The dispatcher (`codewhale`) requires the TUI runtime (`codewhale-tui`) to be on
the same `PATH`. If you installed only one crate via `cargo install`, install
both:
```bash
cargo install deepseek-tui-cli --locked
cargo install deepseek-tui --locked
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked
```
### `deepseek update` reports `no asset found for platform deepseek-linux-aarch64`
### `codewhale update` reports `no asset found for platform codewhale-linux-aarch64`
This is [#503](https://github.com/Hmbown/DeepSeek-TUI/issues/503) in v0.8.7 —
the self-updater used Rust's `aarch64`/`x86_64` arch names instead of the
release artifact's `arm64`/`x64`. Workaround until v0.8.8:
```bash
npm i -g deepseek-tui@latest
npm i -g codewhale@latest
# or
cargo install deepseek-tui-cli --locked
cargo install codewhale-cli --locked
```
### npm download is slow or times out from mainland China
@@ -466,26 +466,26 @@ Set `DEEPSEEK_TUI_RELEASE_BASE_URL` to a mirrored release-asset directory
(rsproxy, TUNA, Tencent COS, Aliyun OSS), or skip npm entirely and use the
Cargo mirror setup in [Section 4](#4-install-via-cargo-any-tier-1-rust-target).
### `deepseek update` is blocked by GitHub from mainland China
### `codewhale update` is blocked by GitHub from mainland China
`deepseek update` normally contacts GitHub Releases for metadata and binary
`codewhale update` normally contacts GitHub Releases for metadata and binary
assets. On networks where GitHub is blocked or unreliable, use the CNB source
mirror instead and install both binaries from the release tag:
```bash
cargo install --git https://cnb.cool/deepseek-tui.com/DeepSeek-TUI --tag vX.Y.Z deepseek-tui-cli --locked --force
cargo install --git https://cnb.cool/deepseek-tui.com/DeepSeek-TUI --tag vX.Y.Z deepseek-tui --locked --force
cargo install --git https://cnb.cool/deepseek-tui.com/DeepSeek-TUI --tag vX.Y.Z codewhale-cli --locked --force
cargo install --git https://cnb.cool/deepseek-tui.com/DeepSeek-TUI --tag vX.Y.Z codewhale-tui --locked --force
```
If you operate a binary asset mirror, `deepseek update` can use it directly:
If you operate a binary asset mirror, `codewhale update` can use it directly:
```bash
DEEPSEEK_TUI_VERSION=X.Y.Z \
DEEPSEEK_TUI_RELEASE_BASE_URL=https://your-mirror.example.com/DeepSeek-TUI/vX.Y.Z/ \
deepseek update
codewhale update
```
The mirror directory must contain `deepseek-artifacts-sha256.txt` and the
The mirror directory must contain `codewhale-artifacts-sha256.txt` and the
platform binaries from the GitHub release.
### Debian/Ubuntu: `feature edition2024 is required` from `cargo install`
@@ -511,8 +511,8 @@ export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup default stable
cargo install deepseek-tui-cli --locked
cargo install deepseek-tui --locked
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked
```
Afterward, `which cargo` should point to `~/.cargo/bin/cargo`, not
@@ -526,7 +526,7 @@ Install the C toolchain:
sudo apt-get install -y build-essential pkg-config libdbus-1-dev
```
### Wrapper installs but `deepseek` isn't found
### Wrapper installs but `codewhale` isn't found
`npm i -g` installs into `$(npm prefix -g)/bin`; make sure that directory is on
your shell's `PATH`. With nvm: `nvm use --lts && hash -r`.
@@ -573,10 +573,10 @@ path-agnostic — moving `target-dir` does not help.
1. **Add the project's `target/` directory to your AV exclusions list.**
2. **Close the antivirus software temporarily** during `cargo build`.
3. **Use `npm install -g deepseek-tui` instead** — the npm package ships
3. **Use `npm install -g codewhale` instead** — the npm package ships
prebuilt binaries and skips the Cargo build entirely
([Section 3](#3-install-via-npm-recommended)).
4. **Use `cargo install deepseek-tui-cli --locked`** from crates.io — this
4. **Use `cargo install codewhale-cli --locked`** from crates.io — this
changes the binary path, which some AV tools treat differently.
To verify that the build-script binary itself is valid (not corrupted), locate
@@ -590,7 +590,7 @@ target/debug/build/libsqlite3-sys-*/build-script-build
### npm binary download times out
If `deepseek` waits several seconds and prints `connect ETIMEDOUT` or
If `codewhale` waits several seconds and prints `connect ETIMEDOUT` or
`EAI_AGAIN` while fetching from `github.com`, the npm wrapper installed
successfully but the prebuilt binary download from GitHub Releases is blocked
or unreliable on your network. This download is separate from the npm registry
@@ -602,23 +602,23 @@ Use one of these paths:
```bash
export HTTPS_PROXY=http://your-proxy:port
deepseek
codewhale
```
2. Mirror the release assets internally and set `DEEPSEEK_TUI_RELEASE_BASE_URL`:
```bash
export DEEPSEEK_TUI_RELEASE_BASE_URL=https://your-mirror.example.com/DeepSeek-TUI/
deepseek
codewhale
```
The directory must contain `deepseek-artifacts-sha256.txt` and the platform
The directory must contain `codewhale-artifacts-sha256.txt` and the platform
binaries from the GitHub release.
3. Install via Cargo, which builds locally and does not download GitHub release
assets. See [Section 4](#4-install-via-cargo-any-tier-1-rust-target).
4. Download both `deepseek` and `deepseek-tui` manually from the
4. Download both `codewhale` and `codewhale-tui` manually from the
[Releases page](https://github.com/Hmbown/DeepSeek-TUI/releases), place them
in a directory on `PATH`, and make them executable. See
[Section 6](#6-manual-download-from-github-releases).
@@ -628,9 +628,9 @@ Use one of these paths:
## 9. Verifying your install
```bash
deepseek --version
deepseek doctor # checks API key, provider, runtime, and PATH integrity
deepseek doctor --json
codewhale --version
codewhale doctor # checks API key, provider, runtime, and PATH integrity
codewhale doctor --json
```
`doctor` exits non-zero if it finds a problem and prints structured remediation
docs/MCP.md
+29 -29
View File
@@ -1,15 +1,15 @@
# MCP (External Tool Servers)
DeepSeek TUI can load additional tools via MCP (Model Context Protocol). MCP servers are local processes that the TUI starts and communicates with over stdio.
codewhale can load additional tools via MCP (Model Context Protocol). MCP servers are local processes that the TUI starts and communicates with over stdio.
Browsing note:
- `web.run` is the canonical built-in browsing tool.
- `web_search` remains available as a compatibility alias for older prompts and integrations.
Server mode note:
- `deepseek-tui serve --mcp` runs the MCP stdio server.
- `deepseek-tui serve --http` runs the runtime HTTP/SSE API (separate mode).
- The `deepseek` dispatcher exposes `deepseek mcp-server` as an equivalent stdio
- `codewhale-tui serve --mcp` runs the MCP stdio server.
- `codewhale-tui serve --http` runs the runtime HTTP/SSE API (separate mode).
- The `codewhale` dispatcher exposes `codewhale mcp-server` as an equivalent stdio
entrypoint used by the split CLI.
## Bootstrap MCP Config
@@ -17,22 +17,22 @@ Server mode note:
Create a starter MCP config at your resolved MCP path:
```bash
deepseek-tui mcp init
codewhale-tui mcp init
```
`deepseek-tui setup --mcp` performs the same MCP bootstrap alongside skills setup.
`codewhale-tui setup --mcp` performs the same MCP bootstrap alongside skills setup.
Common management commands:
```bash
deepseek-tui mcp list
deepseek-tui mcp tools [server]
deepseek-tui mcp add <name> --command "<cmd>" --arg "<arg>"
deepseek-tui mcp add <name> --url "http://localhost:3000/mcp"
deepseek-tui mcp enable <name>
deepseek-tui mcp disable <name>
deepseek-tui mcp remove <name>
deepseek-tui mcp validate
codewhale-tui mcp list
codewhale-tui mcp tools [server]
codewhale-tui mcp add <name> --command "<cmd>" --arg "<arg>"
codewhale-tui mcp add <name> --url "http://localhost:3000/mcp"
codewhale-tui mcp enable <name>
codewhale-tui mcp disable <name>
codewhale-tui mcp remove <name>
codewhale-tui mcp validate
```
## In-TUI Manager
@@ -72,7 +72,7 @@ Overrides:
- Config: `mcp_config_path = "/path/to/mcp.json"`
- Env: `DEEPSEEK_MCP_CONFIG=/path/to/mcp.json`
`deepseek-tui mcp init` (and `deepseek-tui setup --mcp`) writes to this resolved path.
`codewhale-tui mcp init` (and `codewhale-tui setup --mcp`) writes to this resolved path.
The interactive `/config` editor also exposes `mcp_config_path`. Changing it in
the TUI updates the path used by `/mcp`, and requires a restart before the
@@ -130,14 +130,14 @@ You can register your local DeepSeek binary as an MCP server so other DeepSeek s
### Quick Setup
```bash
deepseek-tui mcp add-self
codewhale-tui mcp add-self
```
This resolves the current binary path, generates a config entry that runs `deepseek-tui serve --mcp`, and writes it to your MCP config file. The default server name is `deepseek`.
This resolves the current binary path, generates a config entry that runs `codewhale-tui serve --mcp`, and writes it to your MCP config file. The default server name is `codewhale`.
Options:
- `--name <NAME>` — custom server name (default: `deepseek`)
- `--name <NAME>` — custom server name (default: `codewhale`)
- `--workspace <PATH>` — workspace directory for the server
### Manual Config
@@ -147,8 +147,8 @@ Equivalent manual entry in `~/.deepseek/mcp.json`:
```json
{
"servers": {
"deepseek": {
"command": "/path/to/deepseek",
"codewhale": {
"command": "/path/to/codewhale",
"args": ["serve", "--mcp"],
"env": {}
}
@@ -156,9 +156,9 @@ Equivalent manual entry in `~/.deepseek/mcp.json`:
}
```
The `deepseek-tui` binary supports `serve --mcp` directly. The `deepseek`
dispatcher offers the equivalent `deepseek mcp-server` stdio entrypoint. Use
whichever is on your `PATH` (run `which deepseek` or `which deepseek-tui` to
The `codewhale-tui` binary supports `serve --mcp` directly. The `codewhale`
dispatcher offers the equivalent `codewhale mcp-server` stdio entrypoint. Use
whichever is on your `PATH` (run `which codewhale` or `which codewhale-tui` to
find the full path). The `mcp add-self` command automatically resolves the
correct binary.
@@ -172,13 +172,13 @@ correct binary.
Tools from a self-hosted DeepSeek server follow the standard naming convention:
- `mcp_deepseek_<tool>` (if the server is named `deepseek`)
- `mcp_deepseek_<tool>` (if the server is named `codewhale`)
For example, the `shell` tool becomes `mcp_deepseek_shell`.
### MCP Server vs HTTP/SSE API vs ACP
| | `deepseek-tui serve --mcp` | `deepseek-tui serve --http` | `deepseek-tui serve --acp` |
| | `codewhale-tui serve --mcp` | `codewhale-tui serve --http` | `codewhale-tui serve --acp` |
|---|---|---|---|
| **Protocol** | MCP stdio | HTTP/SSE JSON-RPC | ACP stdio |
| **Use case** | Tool server for MCP clients | Runtime API for apps | Editor agent for Zed/custom ACP clients |
@@ -194,8 +194,8 @@ Use `serve --acp` when an editor wants to talk to DeepSeek as an ACP agent.
After adding, test the connection:
```bash
deepseek-tui mcp validate
deepseek-tui mcp tools deepseek
codewhale-tui mcp validate
codewhale-tui mcp tools codewhale
```
## Server Fields
@@ -220,7 +220,7 @@ You should still only configure MCP servers you trust, and treat MCP server conf
## Troubleshooting
- Run `deepseek-tui doctor` to confirm the MCP config path it resolved and whether it exists.
- Run `codewhale-tui doctor` to confirm the MCP config path it resolved and whether it exists.
- In the TUI, run `/mcp validate` to refresh the visible server/tool snapshot.
- If the MCP config is missing, run `deepseek-tui mcp init --force` to regenerate it.
- If the MCP config is missing, run `codewhale-tui mcp init --force` to regenerate it.
- If tools don’t appear, verify the server command works from your shell and that the server supports MCP `tools/list`.
docs/MODES.md
+8 -8
View File
@@ -1,6 +1,6 @@
# Modes and Approvals
DeepSeek TUI has two related concepts:
codewhale has two related concepts:
- **TUI mode**: what kind of visible interaction you're in (Plan/Agent/YOLO).
- **Approval mode**: how aggressively the UI asks before executing tools.
@@ -75,14 +75,14 @@ See `MCP.md`.
## Related CLI Flags
Run `deepseek --help` for the canonical list. Common flags:
Run `codewhale --help` for the canonical list. Common flags:
- `-p, --prompt <TEXT>`: one-shot prompt mode (prints and exits)
- `deepseek exec --output-format stream-json <PROMPT>`: emit one JSON object per line for harnesses and backend wrappers
- `deepseek exec --resume <ID|PREFIX> <PROMPT>` / `--session-id <ID|PREFIX>`: continue a saved session non-interactively
- `deepseek exec --continue <PROMPT>`: continue the most recent saved session for this workspace non-interactively
- `deepseek fork <ID|PREFIX>` / `deepseek fork --last`: copy a saved session into a new sibling session; forked sessions retain additive parent-session metadata and show that lineage in session listings
- `--model <MODEL>`: when using the `deepseek` facade, forward a DeepSeek model override to the TUI
- `codewhale exec --output-format stream-json <PROMPT>`: emit one JSON object per line for harnesses and backend wrappers
- `codewhale exec --resume <ID|PREFIX> <PROMPT>` / `--session-id <ID|PREFIX>`: continue a saved session non-interactively
- `codewhale exec --continue <PROMPT>`: continue the most recent saved session for this workspace non-interactively
- `codewhale fork <ID|PREFIX>` / `codewhale fork --last`: copy a saved session into a new sibling session; forked sessions retain additive parent-session metadata and show that lineage in session listings
- `--model <MODEL>`: when using the `codewhale` facade, forward a DeepSeek model override to the TUI
- `--workspace <DIR>`: workspace root for file tools
- `--yolo`: start in YOLO mode
- `-r, --resume <ID|PREFIX|latest>`: resume a saved session
@@ -97,7 +97,7 @@ Run `deepseek --help` for the canonical list. Common flags:
DeepSeek-TUI has three related but intentionally separate recovery paths:
- `deepseek fork <ID>` creates a new saved session from an existing saved
- `codewhale fork <ID>` creates a new saved session from an existing saved
conversation and records the source session id. This is the safe way to
explore a different answer path without overwriting the original session.
- Esc-Esc backtrack rewinds the live transcript to a previous user prompt and
docs/OPERATIONS_RUNBOOK.md
+2 -2
View File
@@ -1,4 +1,4 @@
# DeepSeek TUI Operations Runbook
# codewhale Operations Runbook
This runbook covers practical debugging and incident response for the local CLI/TUI runtime.
@@ -56,7 +56,7 @@ Expected behavior:
- Startup begins a fresh session unless `--resume`/`--continue` is supplied
Actions:
1. Resume prior work explicitly via `deepseek --resume <id>` or `Ctrl+R` in TUI
1. Resume prior work explicitly via `codewhale --resume <id>` or `Ctrl+R` in TUI
2. If checkpoint inspection is needed, inspect `latest.json` for schema mismatch/details
3. If schema is newer than binary supports, upgrade binary or remove stale checkpoint
docs/REBRAND.md
+138
View File
@@ -0,0 +1,138 @@
# Rebrand: deepseek-tui → codewhale
Starting with **v0.8.41**, this project ships under a new name: `codewhale`.
This document explains what changed, what didn't, and how to migrate. None of the
DeepSeek provider integration changed — only the local CLI / TUI brand.
## TL;DR
```bash
# 1. Uninstall the old wrapper or binaries.
npm uninstall -g deepseek-tui # or cargo uninstall deepseek-tui-cli deepseek-tui
# or brew uninstall deepseek-tui
# 2. Install under the new name.
npm install -g codewhale # or cargo install codewhale-cli codewhale-tui --locked
# or brew install deepseek-tui (Homebrew tap still
# uses the legacy name during the transition;
# it installs the new binaries underneath.)
# 3. Run with the new command.
codewhale doctor
codewhale
```
Your `~/.deepseek/config.toml`, `~/.deepseek/sessions/`, `~/.deepseek/skills/`,
`~/.deepseek/tasks/`, and `~/.deepseek/mcp.json` are untouched. Existing
`DEEPSEEK_*` environment variables continue to work.
## What got renamed
| Surface | Before | After |
|---|---|---|
| CLI dispatcher binary | `deepseek` | `codewhale` |
| TUI runtime binary | `deepseek-tui` | `codewhale-tui` |
| npm wrapper package | `deepseek-tui` | `codewhale` |
| Crates.io crates | `deepseek-tui-cli` / `deepseek-tui` / `deepseek-*` | `codewhale-cli` / `codewhale-tui` / `codewhale-*` |
| Release assets | `deepseek-<platform>` / `deepseek-tui-<platform>` | `codewhale-<platform>` / `codewhale-tui-<platform>` |
| Checksum manifest | `deepseek-artifacts-sha256.txt` | `codewhale-artifacts-sha256.txt` |
## What did NOT change
Anything that targets the DeepSeek provider API stays exactly as it was:
- **Environment variables**: `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`,
`DEEPSEEK_MODEL`, `DEEPSEEK_PROVIDER`, `DEEPSEEK_PROFILE`, `DEEPSEEK_YOLO`,
`DEEPSEEK_LOG_LEVEL`, plus the existing `DEEPSEEK_TUI_*` runtime knobs
(`DEEPSEEK_TUI_BIN`, `DEEPSEEK_TUI_RELEASE_BASE_URL`, etc.). They're kept
for backward compatibility; renaming them would break every shell rc on
the planet.
- **Model IDs**: `deepseek-v4-pro`, `deepseek-v4-flash`, and the legacy
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**: still `https://github.com/Hmbown/DeepSeek-TUI`.
A repo rename is a maintainer-side operation that ships separately.
- **Homebrew tap and formula** (`Hmbown/homebrew-deepseek-tui`): still
installs by the legacy name during the transition. The tap's formula
will be flipped to the new names in a follow-up.
- **Docker image** (`ghcr.io/hmbown/deepseek-tui`): unchanged.
## Deprecation shims (one release cycle)
To keep existing shell aliases, scripts, and CI working through the rename,
v0.8.41 ships **deprecation shims** for one cycle:
- A `deepseek` binary that prints a one-line warning to stderr and forwards
argv to `codewhale`.
- A `deepseek-tui` binary that does the same for `codewhale-tui`.
- An `npm` package at `deepseek-tui@0.8.41` with no `bin` and a postinstall
that prints a clear "rename" notice.
These shims will be removed in **v0.9.0**. Please migrate before then.
## Migrating in practice
### npm
```bash
npm uninstall -g deepseek-tui
npm install -g codewhale
```
### Cargo
```bash
cargo uninstall deepseek-tui-cli deepseek-tui 2>/dev/null || true
cargo install codewhale-cli codewhale-tui --locked
```
Or in a checkout:
```bash
cargo install --path crates/cli --locked --force
cargo install --path crates/tui --locked --force
```
### Homebrew
The tap formula still installs `deepseek-tui` during the transition.
Existing `brew install deepseek-tui` invocations continue to work and land
the new binaries underneath the legacy formula name. The formula and tap
repo will follow up with their own rename.
### Manual / GitHub Releases
`v0.8.41` Releases attach **both** the canonical `codewhale-*` /
`codewhale-tui-*` assets and the legacy `deepseek-*` / `deepseek-tui-*`
shim assets. Existing `deepseek update` invocations on v0.8.40 keep working;
they land you on the deprecation shim, which then prompts the install of
`codewhale`.
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.
## Why the name change
`codewhale` is a shorter, terminal-friendlier handle that doesn't suggest
the project is tied to a single provider. The dispatcher already supports
DeepSeek, NVIDIA NIM, OpenAI-compatible endpoints, AtlasCloud, Wanjie Ark,
OpenRouter, Novita, Fireworks, SGLang, vLLM, and Ollama, with more on the
roadmap. The new name reflects that.
## Reporting issues with the rename
If your install broke during the migration, please open an issue at
<https://github.com/Hmbown/DeepSeek-TUI/issues> and include:
- The output of `codewhale --version` (or `deepseek --version` if you're
still on the shim).
- Which install path you used (npm, cargo, brew, manual).
- The exact command you ran and the full error output.
We'll prioritize migration regressions.
docs/RELEASE_CHECKLIST.md
+3 -3
View File
@@ -29,7 +29,7 @@ publish-crates), see [`RELEASE_RUNBOOK.md`](RELEASE_RUNBOOK.md).
- [ ] `Cargo.toml` workspace `version` is bumped.
- [ ] All per-crate `crates/*/Cargo.toml` path-dependency `version = "..."`
pins match the new workspace version.
- [ ] `npm/deepseek-tui/package.json` `version` AND `deepseekBinaryVersion`
- [ ] `npm/codewhale-tui/package.json` `version` AND `deepseekBinaryVersion`
are both bumped.
- [ ] `Cargo.lock` is refreshed (`cargo update --workspace --offline`).
- [ ] `./scripts/release/check-versions.sh` reports
@@ -51,7 +51,7 @@ Run, in order, from the repo root:
## 4. npm wrapper smoke
- [ ] `cargo build --release --locked -p deepseek-tui-cli -p deepseek-tui`
- [ ] `cargo build --release --locked -p codewhale-cli -p codewhale-tui`
- [ ] `node scripts/release/npm-wrapper-smoke.js`
(Set `DEEPSEEK_TUI_KEEP_SMOKE_DIR=1` if you need to inspect the temp
install afterwards.)
@@ -82,7 +82,7 @@ Run, in order, from the repo root:
- [ ] `git push origin vX.Y.Z`
- [ ] The `release.yml` workflow has built and uploaded artifacts to the
GitHub release for this tag.
- [ ] `npm view deepseek-tui@X.Y.Z version deepseekBinaryVersion --json`
- [ ] `npm view codewhale-tui@X.Y.Z version deepseekBinaryVersion --json`
reports the new version on the npm registry.
- [ ] `crates.io` has the new version (or the `publish-crates.sh` job has
pushed it).
docs/RELEASE_RUNBOOK.md
+54 -54
View File
@@ -1,37 +1,37 @@
# DeepSeek TUI Release Runbook
# codewhale Release Runbook
This runbook is the source of truth for shipping Rust crates, GitHub release assets,
and the `deepseek-tui` npm wrapper.
and the `codewhale-tui` npm wrapper.
Current packaging note:
- `deepseek-tui` is the live runtime and TUI package shipped to users today.
- `deepseek-tui-core` is a supporting workspace crate for the extraction/parity effort, not a replacement for the shipping runtime.
- `codewhale-tui` is the live runtime and TUI package shipped to users today.
- `codewhale-tui-core` is a supporting workspace crate for the extraction/parity effort, not a replacement for the shipping runtime.
## Canonical Publish Targets
- End-user crates:
- `deepseek-tui`
- `deepseek-tui-cli`
- `codewhale-tui`
- `codewhale-cli`
- Supporting crates published from this workspace:
- `deepseek-secrets`
- `deepseek-config`
- `deepseek-protocol`
- `deepseek-state`
- `deepseek-agent`
- `deepseek-execpolicy`
- `deepseek-hooks`
- `deepseek-mcp`
- `deepseek-tools`
- `deepseek-core`
- `deepseek-app-server`
- `deepseek-tui-core`
- `deepseek-cli` on crates.io is an unrelated crate and is not part of this release flow.
- `codewhale-secrets`
- `codewhale-config`
- `codewhale-protocol`
- `codewhale-state`
- `codewhale-agent`
- `codewhale-execpolicy`
- `codewhale-hooks`
- `codewhale-mcp`
- `codewhale-tools`
- `codewhale-core`
- `codewhale-app-server`
- `codewhale-tui-core`
- `codewhale-cli` on crates.io is an unrelated crate and is not part of this release flow.
## Version Coordination
- Rust crates inherit the shared workspace version from [Cargo.toml](../Cargo.toml).
- Internal path dependency versions should match the shared workspace version; stale older pins are release blockers once the workspace version moves.
- The npm wrapper version lives in [npm/deepseek-tui/package.json](../npm/deepseek-tui/package.json).
- The npm wrapper version lives in [npm/codewhale-tui/package.json](../npm/codewhale-tui/package.json).
- `deepseekBinaryVersion` controls which GitHub release binaries the npm wrapper downloads.
- Packaging-only npm releases are allowed:
- bump the npm package version
@@ -48,13 +48,13 @@ cargo fmt --all -- --check
cargo check --workspace --all-targets --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-features --locked
cargo publish --dry-run --locked --allow-dirty -p deepseek-tui
cargo publish --dry-run --locked --allow-dirty -p codewhale-tui
./scripts/release/publish-crates.sh dry-run
```
`check-versions.sh` also runs in CI on every push/PR (the `versions` job in
`.github/workflows/ci.yml`), so drift between `Cargo.toml`, the per-crate
manifests, `npm/deepseek-tui/package.json`, and `Cargo.lock` is caught before
manifests, `npm/codewhale-tui/package.json`, and `Cargo.lock` is caught before
release time rather than at it.
`publish-crates.sh dry-run` performs a full `cargo publish --dry-run` for crates
@@ -65,11 +65,11 @@ new workspace version while still validating package contents before publish.
For npm wrapper verification, build the two shipped binaries and run the
cross-platform smoke harness. This packs the npm wrapper, installs it into a
clean temporary project, serves local release assets over HTTP, and checks both
the dispatcher-to-TUI path (`deepseek doctor --help`) and the direct TUI
entrypoint (`deepseek-tui --help`).
the dispatcher-to-TUI path (`codewhale doctor --help`) and the direct TUI
entrypoint (`codewhale-tui --help`).
```bash
cargo build --release --locked -p deepseek-tui-cli -p deepseek-tui
cargo build --release --locked -p codewhale-cli -p codewhale-tui
node scripts/release/npm-wrapper-smoke.js
```
@@ -81,7 +81,7 @@ directory with a full asset matrix fixture before starting the server:
```bash
DEEPSEEK_TUI_PREPARE_ALL_ASSETS=1 node scripts/release/prepare-local-release-assets.js
cd npm/deepseek-tui
cd npm/codewhale-tui
DEEPSEEK_TUI_VERSION=X.Y.Z DEEPSEEK_TUI_RELEASE_BASE_URL=http://127.0.0.1:8123/ npm run release:check
```
@@ -96,8 +96,8 @@ After publishing, prove the release is visible in both registries:
./scripts/release/check-published.sh X.Y.Z
```
Do not mark a Rust release complete until that command sees `deepseek-tui@X.Y.Z`
on npm and every `deepseek-*` crate at `X.Y.Z` on crates.io. For a rare
Do not mark a Rust release complete until that command sees `codewhale-tui@X.Y.Z`
on npm and every `codewhale-*` crate at `X.Y.Z` on crates.io. For a rare
npm packaging-only release, run with `--allow-npm-binary-mismatch` and keep the
release notes explicit that no new Rust binary version shipped.
@@ -115,20 +115,20 @@ configured.
`main` and letting `auto-tag.yml` create the tag — see the npm wrapper
release section below for the `RELEASE_TAG_PAT` requirement).
4. Publish crates in this order with `./scripts/release/publish-crates.sh publish`:
- `deepseek-secrets`
- `deepseek-config`
- `deepseek-protocol`
- `deepseek-state`
- `deepseek-agent`
- `deepseek-execpolicy`
- `deepseek-hooks`
- `deepseek-mcp`
- `deepseek-tools`
- `deepseek-core`
- `deepseek-app-server`
- `deepseek-tui-core`
- `deepseek-tui-cli`
- `deepseek-tui`
- `codewhale-secrets`
- `codewhale-config`
- `codewhale-protocol`
- `codewhale-state`
- `codewhale-agent`
- `codewhale-execpolicy`
- `codewhale-hooks`
- `codewhale-mcp`
- `codewhale-tools`
- `codewhale-core`
- `codewhale-app-server`
- `codewhale-tui-core`
- `codewhale-cli`
- `codewhale-tui`
5. Wait for each published crate version to appear on crates.io before publishing dependents.
The publish helper is idempotent for reruns: already-published crate versions are skipped.
@@ -137,16 +137,16 @@ The publish helper is idempotent for reruns: already-published crate versions ar
`.github/workflows/release.yml` builds these binaries:
- `deepseek-linux-x64`
- `deepseek-macos-x64`
- `deepseek-macos-arm64`
- `deepseek-windows-x64.exe`
- `deepseek-tui-linux-x64`
- `deepseek-tui-macos-x64`
- `deepseek-tui-macos-arm64`
- `deepseek-tui-windows-x64.exe`
- `codewhale-linux-x64`
- `codewhale-macos-x64`
- `codewhale-macos-arm64`
- `codewhale-windows-x64.exe`
- `codewhale-tui-linux-x64`
- `codewhale-tui-macos-x64`
- `codewhale-tui-macos-arm64`
- `codewhale-tui-windows-x64.exe`
The release job also uploads `deepseek-artifacts-sha256.txt`. The npm installer and
The release job also uploads `codewhale-artifacts-sha256.txt`. The npm installer and
release verification script both depend on that checksum manifest.
## npm Wrapper Release
@@ -159,14 +159,14 @@ on a workstation with `npm login` and an authenticator app.
### Steps
1. Set the npm package version in [npm/deepseek-tui/package.json](../npm/deepseek-tui/package.json) to match the workspace `Cargo.toml`. CI's version-drift guard will catch mismatches before tag.
1. Set the npm package version in [npm/codewhale-tui/package.json](../npm/codewhale-tui/package.json) to match the workspace `Cargo.toml`. CI's version-drift guard will catch mismatches before tag.
2. Set `deepseekBinaryVersion` to the GitHub release tag that should supply binaries.
3. Push the version bump to `main`. `auto-tag.yml` creates the matching `vX.Y.Z` tag, and `release.yml` builds the binary matrix and drafts the GitHub Release.
4. **Wait for the GitHub Release to finalize** with all eight signed binaries plus `deepseek-artifacts-sha256.txt`. The npm `prepublishOnly` hook (`scripts/verify-release-assets.js`) requires every asset to be present.
4. **Wait for the GitHub Release to finalize** with all eight signed binaries plus `codewhale-artifacts-sha256.txt`. The npm `prepublishOnly` hook (`scripts/verify-release-assets.js`) requires every asset to be present.
5. From a developer machine, publish the npm wrapper manually:
```bash
cd npm/deepseek-tui
cd npm/codewhale-tui
npm publish --access public
# (you will be prompted for the npm OTP from your authenticator)
```
docs/RUNTIME_API.md
+18 -18
View File
@@ -1,8 +1,8 @@
# Runtime API & Integration Contract
DeepSeek TUI exposes a local runtime API through `deepseek serve --http` and
machine-readable health via `deepseek doctor --json`. It also exposes
`deepseek serve --acp` for editor clients that speak the Agent Client Protocol
codewhale exposes a local runtime API through `codewhale serve --http` and
machine-readable health via `codewhale doctor --json`. It also exposes
`codewhale serve --acp` for editor clients that speak the Agent Client Protocol
over stdio. This document is the stable integration contract for native macOS
workbench applications (and other local supervisors) that embed the DeepSeek
engine without screen-scraping terminal output.
@@ -12,19 +12,19 @@ engine without screen-scraping terminal output.
```
macOS workbench (or any local supervisor)
│
├─ deepseek doctor --json → machine-readable health & capability
├─ deepseek serve --http → HTTP/SSE runtime API
├─ deepseek serve --acp → ACP stdio agent for editors such as Zed
├─ deepseek serve --mcp → MCP stdio server
└─ deepseek [args] → interactive TUI session
├─ codewhale doctor --json → machine-readable health & capability
├─ codewhale serve --http → HTTP/SSE runtime API
├─ codewhale serve --acp → ACP stdio agent for editors such as Zed
├─ codewhale serve --mcp → MCP stdio server
└─ codewhale [args] → interactive TUI session
```
The engine runs as a local-only process. All APIs bind to `localhost` by
default. No hosted relay, no provider-token custody, no secret leakage.
## ACP stdio adapter: `deepseek serve --acp`
## ACP stdio adapter: `codewhale serve --acp`
`deepseek serve --acp` speaks JSON-RPC 2.0 over newline-delimited stdio for
`codewhale serve --acp` speaks JSON-RPC 2.0 over newline-delimited stdio for
ACP-compatible editor clients. The initial adapter implements the ACP baseline:
- `initialize`
@@ -38,16 +38,16 @@ followed by a `session/prompt` response with `stopReason: "end_turn"`.
The adapter is intentionally conservative: it does not yet expose shell tools,
file-write tools, checkpoint replay, or session loading through ACP. Use
`deepseek serve --http` for the full local runtime API and `deepseek serve --mcp`
`codewhale serve --http` for the full local runtime API and `codewhale serve --mcp`
when another client needs DeepSeek's tools as MCP tools.
## Capability endpoint: `deepseek doctor --json`
## Capability endpoint: `codewhale doctor --json`
Returns a JSON object describing the current installation's readiness state.
Suitable for health-check polling from a macOS workbench.
```bash
deepseek doctor --json
codewhale doctor --json
```
### Response schema (key fields)
@@ -88,7 +88,7 @@ deepseek doctor --json
"version": "0.8.9",
"config_path": "/Users/you/.deepseek/config.toml",
"config_present": true,
"workspace": "/Users/you/projects/deepseek-tui",
"workspace": "/Users/you/projects/codewhale-tui",
"api_key": {
"source": "env"
},
@@ -113,10 +113,10 @@ deepseek doctor --json
}
```
## HTTP/SSE runtime API: `deepseek serve --http`
## HTTP/SSE runtime API: `codewhale serve --http`
```bash
deepseek serve --http [--host 127.0.0.1] [--port 7878] [--workers 2] [--auth-token TOKEN]
codewhale serve --http [--host 127.0.0.1] [--port 7878] [--workers 2] [--auth-token TOKEN]
```
Defaults: host `127.0.0.1`, port `7878`, 2 workers (clamped 1–8).
@@ -333,7 +333,7 @@ The runtime API ships with a built-in dev-origin allow-list:
`http://127.0.0.1:1420`, `tauri://localhost`. To add additional origins (e.g.
when developing a UI on Vite's default `:5173`), use any of:
- CLI flag (repeatable): `deepseek serve --http --cors-origin http://localhost:5173`
- CLI flag (repeatable): `codewhale serve --http --cors-origin http://localhost:5173`
- Env var (comma-separated): `DEEPSEEK_CORS_ORIGINS="http://localhost:5173,http://localhost:8080"`
- Config (`~/.deepseek/config.toml`):
```toml
@@ -366,7 +366,7 @@ model is preserved. Added in v0.8.10 (#561).
Contract snapshots live in `crates/protocol/tests/`. Run:
```bash
cargo test -p deepseek-protocol --test parity_protocol --locked
cargo test -p codewhale-protocol --test parity_protocol --locked
```
This validates that the app-server's event schema hasn't drifted from the
docs/TENCENT_CLOUD_REMOTE_FIRST.md
+14 -14
View File
@@ -1,10 +1,10 @@
# Tencent Cloud Remote-First Quickstart
This is the opinionated Tencent-native teaching path for DeepSeek TUI users
This is the opinionated Tencent-native teaching path for codewhale users
who want an always-on agent workspace, a phone control surface, and a stack
that works well from mainland China.
It complements the local install path. If you only want to use `deepseek` on a
It complements the local install path. If you only want to use `codewhale` on a
laptop, start with the README quickstart. If you want "DS-TUI as a remote
workbench I can control from my phone", start here.
@@ -15,10 +15,10 @@ GitHub main/tags
-> CNB mirror: cnb.cool/deepseek-tui.com/DeepSeek-TUI
-> optional CNB build/deploy pipeline
-> Tencent Lighthouse HK
/opt/whalebro/deepseek-tui
/opt/whalebro/codewhale-tui
/opt/whalebro/worktrees
deepseek-runtime.service on 127.0.0.1:7878
deepseek-feishu-bridge.service
codewhale-runtime.service on 127.0.0.1:7878
codewhale-feishu-bridge.service
-> Feishu/Lark phone DM
EdgeOne is optional:
@@ -32,7 +32,7 @@ EdgeOne is optional:
slow. Optional CNB deploy templates live under
`deploy/tencent-lighthouse/cnb/`.
- **Lighthouse** is the private always-on host. It owns `/opt/whalebro`,
systemd, Rust/Node installs, and the `deepseek serve --http` runtime.
systemd, Rust/Node installs, and the `codewhale serve --http` runtime.
- **Feishu/Lark** is the first phone UI. The bridge uses long-connection mode,
so the first setup does not need a public webhook URL.
- **EdgeOne** is the public edge only when you intentionally expose a web
@@ -57,14 +57,14 @@ EdgeOne is optional:
```bash
export DEEPSEEK_BRANCH=main
git clone --branch "$DEEPSEEK_BRANCH" "$DEEPSEEK_REPO_URL" /tmp/deepseek-tui
cd /tmp/deepseek-tui
git clone --branch "$DEEPSEEK_BRANCH" "$DEEPSEEK_REPO_URL" /tmp/codewhale-tui
cd /tmp/codewhale-tui
sudo DEEPSEEK_REPO_URL="$DEEPSEEK_REPO_URL" \
DEEPSEEK_REPO_BRANCH="$DEEPSEEK_BRANCH" \
bash scripts/tencent-lighthouse/bootstrap-ubuntu.sh
```
4. Install Rust for the `deepseek` user, build both binaries, and install the
4. Install Rust for the `codewhale` user, build both binaries, and install the
systemd units using `docs/TENCENT_LIGHTHOUSE_HK.md`.
5. Configure a Feishu/Lark self-built app, fill
`/etc/deepseek/feishu-bridge.env`, run the validator, then run the VPS
@@ -85,7 +85,7 @@ The intended deploy button should:
1. Run bridge validation/tests and lightweight release-version checks.
2. SSH to Lighthouse with a deploy key stored as a CNB secret.
3. Update `/opt/whalebro/deepseek-tui`.
3. Update `/opt/whalebro/codewhale-tui`.
4. Rebuild/install both binaries.
5. Reinstall/restart systemd services.
6. Run `scripts/tencent-lighthouse/doctor.sh`.
@@ -105,7 +105,7 @@ you want a public domain in front of a deliberate HTTP service:
Keep these rules:
- `deepseek serve --http` stays bound to `127.0.0.1`.
- `codewhale serve --http` stays bound to `127.0.0.1`.
- `/v1/*` runtime endpoints are never public.
- `DEEPSEEK_RUNTIME_TOKEN` never leaves the server env files.
- Feishu/Lark group control stays off until a specific group allowlist is set.
@@ -114,13 +114,13 @@ Keep these rules:
## Teaching Order
Use this sequence when explaining DeepSeek TUI to a new remote-first user:
Use this sequence when explaining codewhale to a new remote-first user:
1. **Local mental model:** `deepseek` is the dispatcher, `deepseek-tui` is the
1. **Local mental model:** `codewhale` is the dispatcher, `codewhale-tui` is the
companion runtime, and both binaries matter.
2. **Agent safety:** Plan/Agent/YOLO are separate from approval mode and
sandboxing.
3. **Remote runtime:** `deepseek serve --http` is a localhost runtime API, not
3. **Remote runtime:** `codewhale serve --http` is a localhost runtime API, not
a public web app.
4. **Phone bridge:** Feishu/Lark messages become runtime requests through an
allowlisted bridge.
docs/TENCENT_LIGHTHOUSE_HK.md
+24 -24
View File
@@ -1,7 +1,7 @@
# Tencent Lighthouse Hong Kong Phone Setup
This runbook sets up a Tencent Cloud Lighthouse instance in Hong Kong as an
always-on DeepSeek TUI host controlled from Feishu/Lark on a phone.
always-on codewhale host controlled from Feishu/Lark on a phone.
If you are teaching this as the Tencent-native default path, start with
[docs/TENCENT_CLOUD_REMOTE_FIRST.md](TENCENT_CLOUD_REMOTE_FIRST.md). This file
@@ -11,14 +11,14 @@ is the implementation runbook for the Lighthouse host itself.
```text
CNB mirror or GitHub branch
-> /opt/whalebro/deepseek-tui
-> /opt/whalebro/codewhale-tui
Feishu/Lark mobile app
-> Feishu/Lark long-connection bot
-> deepseek-feishu-bridge systemd service
-> http://127.0.0.1:7878 deepseek serve --http
-> codewhale-feishu-bridge systemd service
-> http://127.0.0.1:7878 codewhale serve --http
-> /opt/whalebro
-> deepseek-tui/
-> codewhale-tui/
Optional public edge:
EdgeOne -> Caddy/Nginx public site on Lighthouse
@@ -31,11 +31,11 @@ HTTP service, not the runtime API.
## Remote Whalebro Workspace
Use `/opt/whalebro` as the VPS workspace root. The first-class checkout is
`/opt/whalebro/deepseek-tui`.
`/opt/whalebro/codewhale-tui`.
Create these paths first:
- `/opt/whalebro/deepseek-tui`
- `/opt/whalebro/codewhale-tui`
- `/opt/whalebro/worktrees`
Linux is enough for Rust, Node, and service work. Mac-only release work such
@@ -88,8 +88,8 @@ sudo apt-get update
sudo apt-get install -y git
export DEEPSEEK_BRANCH=main
export DEEPSEEK_REPO_URL=https://cnb.cool/deepseek-tui.com/DeepSeek-TUI.git
git clone --branch "$DEEPSEEK_BRANCH" "$DEEPSEEK_REPO_URL" /tmp/deepseek-tui
cd /tmp/deepseek-tui
git clone --branch "$DEEPSEEK_BRANCH" "$DEEPSEEK_REPO_URL" /tmp/codewhale-tui
cd /tmp/codewhale-tui
sudo DEEPSEEK_REPO_URL="$DEEPSEEK_REPO_URL" \
DEEPSEEK_REPO_BRANCH="$DEEPSEEK_BRANCH" \
bash scripts/tencent-lighthouse/bootstrap-ubuntu.sh
@@ -120,16 +120,16 @@ If this deployment setup has not been pushed to Git yet, either push the branch
first or copy this checkout to the VPS before running these commands. A fresh
VPS clone cannot see uncommitted local files.
Install Rust 1.88+ for the `deepseek` user, then build both shipped binaries:
Install Rust 1.88+ for the `codewhale` user, then build both shipped binaries:
```bash
sudo -iu deepseek
sudo -iu codewhale
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup-init.sh
sed -n '1,120p' /tmp/rustup-init.sh
sh /tmp/rustup-init.sh -y --profile minimal
. "$HOME/.cargo/env"
rustup default stable
cd /opt/whalebro/deepseek-tui
cd /opt/whalebro/codewhale-tui
cargo install --path crates/cli --locked --force
cargo install --path crates/tui --locked --force
exit
@@ -138,14 +138,14 @@ exit
Copy and install the bridge/service files:
```bash
cd /opt/whalebro/deepseek-tui
cd /opt/whalebro/codewhale-tui
sudo bash scripts/tencent-lighthouse/install-services.sh
```
After editing both env files, validate the bridge/runtime pairing:
```bash
sudo -u deepseek node /opt/deepseek/bridge/scripts/validate-config.mjs \
sudo -u codewhale node /opt/deepseek/bridge/scripts/validate-config.mjs \
--env /etc/deepseek/feishu-bridge.env \
--runtime-env /etc/deepseek/runtime.env \
--workspace-root /opt/whalebro \
@@ -185,25 +185,25 @@ For first pairing, either:
## Start Services
```bash
sudo systemctl start deepseek-runtime
sudo systemctl status deepseek-runtime --no-pager
sudo systemctl start codewhale-runtime
sudo systemctl status codewhale-runtime --no-pager
curl -s http://127.0.0.1:7878/health
sudo systemctl start deepseek-feishu-bridge
sudo journalctl -u deepseek-feishu-bridge -f
sudo systemctl start codewhale-feishu-bridge
sudo journalctl -u codewhale-feishu-bridge -f
```
Run the Lighthouse doctor after both services are configured:
```bash
cd /opt/whalebro/deepseek-tui
cd /opt/whalebro/codewhale-tui
sudo bash scripts/tencent-lighthouse/doctor.sh
```
Enable on boot is done by `install-services.sh`; if needed:
```bash
sudo systemctl enable deepseek-runtime deepseek-feishu-bridge
sudo systemctl enable codewhale-runtime codewhale-feishu-bridge
```
## Phone Commands
@@ -280,14 +280,14 @@ From a phone DM to the bot:
5. Trigger a tool approval and verify both `/allow <approval_id>` and
`/deny <approval_id>` paths.
6. Restart both services and re-run `/status`.
7. Reboot the instance, then confirm `systemctl status deepseek-runtime` and
`systemctl status deepseek-feishu-bridge` return to active.
7. Reboot the instance, then confirm `systemctl status codewhale-runtime` and
`systemctl status codewhale-feishu-bridge` return to active.
## Operational Notes
- Bind `deepseek serve --http` to `127.0.0.1`.
- Bind `codewhale serve --http` to `127.0.0.1`.
- Keep the Lighthouse firewall focused on SSH for this setup.
- Use SSH key auth.
- Use `tmux` for emergency terminal work from Blink/Termius.
- Keep `/opt/whalebro/deepseek-tui` on a personal branch while working from the
- Keep `/opt/whalebro/codewhale-tui` on a personal branch while working from the
phone.
docs/TOOL_SURFACE.md
+2 -2
View File
@@ -258,8 +258,8 @@ while the registry contract stays stable.
Version smoke:
```bash
deepseek --version
deepseek-tui --version
codewhale --version
codewhale-tui --version
```
Tool-surface smoke:
docs/capacity_controller.md
+1 -1
View File
@@ -1,6 +1,6 @@
# Capacity Controller
`deepseek-tui` includes an opt-in capacity-aware context controller. In the
`codewhale-tui` includes an opt-in capacity-aware context controller. In the
default V4 path it is disabled, because its active interventions can rewrite
the live prompt and break prefix-cache affinity. Treat it as telemetry or an
experimental guardrail unless `capacity.enabled = true` is set explicitly.