From 26e2de86f0c9d9694c3dbde505cfc983cfb7f0bb Mon Sep 17 00:00:00 2001 From: Hunter Bown Date: Sun, 31 May 2026 02:39:53 -0700 Subject: [PATCH] docs: align configuration paths with codewhale home (#2413) Harvested from #2400 with thanks to @axobase001.\n\nAligns the configuration docs around CODEWHALE_HOME while preserving the DEEPSEEK_HOME legacy alias and spelling out how legacy checkpoints can still be scanned during cleanup.\n\nCloses #2322. --- docs/CONFIGURATION.md | 73 ++++++++++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 25 deletions(-) diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 8830e71e..0fe1dd3f 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -9,22 +9,26 @@ only the provider and safety knobs you need. Default config path: -- `~/.deepseek/config.toml` +- `~/.codewhale/config.toml` +- Legacy fallback: `~/.deepseek/config.toml` Overrides: - CLI: `codewhale --config /path/to/config.toml` -- Env: `DEEPSEEK_CONFIG_PATH=/path/to/config.toml` +- Env: `CODEWHALE_CONFIG_PATH=/path/to/config.toml` +- Legacy env alias: `DEEPSEEK_CONFIG_PATH=/path/to/config.toml` If both are set, `--config` wins. Environment variable overrides are applied after the file is loaded. ### Per-project overlay (#485) When the TUI starts in a workspace that contains a -`/.deepseek/config.toml` file, the values declared in that -file are merged on top of the global config. This lets a repo lock its -own provider, model, sandbox policy, or approval policy without -touching the user's `~/.deepseek/config.toml`. Pass +`/.codewhale/config.toml` file, the values declared in that +file are merged on top of the global config. Legacy +`/.deepseek/config.toml` files are still read when the +CodeWhale path is absent. This lets a repo lock its own provider, +model, sandbox policy, or approval policy without touching the user's +`~/.codewhale/config.toml`. Pass `--no-project-config` to skip the overlay for one launch. Supported keys in the project overlay (top-level fields only): @@ -52,8 +56,9 @@ specific use case. 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`. +`~/.codewhale/config.toml` (migrating legacy `~/.deepseek/config.toml` on first +launch when needed), 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 `codewhale auth status` to inspect the active provider's config @@ -298,11 +303,17 @@ Remaining variables: - `DEEPSEEK_MANAGED_CONFIG_PATH` - `DEEPSEEK_REQUIREMENTS_PATH` - `DEEPSEEK_MAX_SUBAGENTS` (clamped to `1..=20`) -- `DEEPSEEK_TASKS_DIR` (runtime task queue/artifact storage, default `~/.deepseek/tasks`) +- `DEEPSEEK_TASKS_DIR` (runtime task queue/artifact storage, default + `~/.codewhale/tasks`, with legacy `~/.deepseek/tasks` fallback when only the + legacy directory exists) - `DEEPSEEK_ALLOW_INSECURE_HTTP` (`1`/`true` allows non-local `http://` base URLs; default is reject) - `DEEPSEEK_FORCE_HTTP1` (`1|true|yes|on` pins the HTTP client to HTTP/1.1, disabling HTTP/2; useful on Windows or behind proxies that mishandle long-lived H2 streams) -- `DEEPSEEK_HOME` (override the base data directory; defaults to `~/.deepseek`) -- `DEEPSEEK_AUTOMATIONS_DIR` (override the automations storage directory; defaults to `~/.deepseek/automations`) +- `CODEWHALE_HOME` (override the base data directory; defaults to `~/.codewhale`). + If you previously exported `DEEPSEEK_HOME`, rename it to `CODEWHALE_HOME`; + the old env var is not used for new CodeWhale state paths. +- `DEEPSEEK_AUTOMATIONS_DIR` (override the automations storage directory; uses + `~/.codewhale/automations` when that directory exists, otherwise the legacy + `~/.deepseek/automations` path) - `DEEPSEEK_CAPACITY_ENABLED` - `DEEPSEEK_CAPACITY_LOW_RISK_MAX` - `DEEPSEEK_CAPACITY_MEDIUM_RISK_MAX` @@ -336,7 +347,7 @@ concatenated, in declared order, alongside the auto-loaded ```toml instructions = [ "./AGENTS.md", - "~/.deepseek/global.md", + "~/.codewhale/global.md", "~/team/agents-shared.md", ] ``` @@ -348,7 +359,8 @@ Rules: truncated with a `[…elided]` marker rather than skipped. - Missing files are skipped with a tracing warning so a stale entry doesn't fail the launch. -- Project config (`/.deepseek/config.toml`) +- Project config (`/.codewhale/config.toml`, or legacy + `/.deepseek/config.toml`) **replaces** the user array wholesale rather than merging. If you want both, list `~/global.md` inside the project array. Set `instructions = []` in the project to clear the @@ -508,24 +520,28 @@ If you are upgrading from older releases: `[subagents.models]` accepts lower-case role or type keys such as `worker`, `explorer`, `general`, `explore`, `plan`, and `review`. Values must normalize to a supported DeepSeek model id before an agent is spawned. -- `skills_dir` (string, optional): defaults to `~/.deepseek/skills` (each skill is +- `skills_dir` (string, optional): defaults to `~/.codewhale/skills` (each skill is a directory containing `SKILL.md`). Workspace-local `.agents/skills` or `./skills` are preferred when present; the runtime also discovers global agentskills.io-compatible `~/.agents/skills` and the broader Claude-ecosystem `~/.claude/skills`. First launch installs versioned bundled skills for common workflows including skill creation, delegation, MCP/plugin scaffolding, documents, presentations, spreadsheets, PDFs, and Feishu/Lark. -- `mcp_config_path` (string, optional): defaults to `~/.deepseek/mcp.json`. +- `mcp_config_path` (string, optional): defaults to `~/.codewhale/mcp.json`, with + legacy `~/.deepseek/mcp.json` fallback when the CodeWhale path is absent. It is visible in `/config` and can be changed from the TUI. The new path is used immediately by `/mcp`, but rebuilding the model-visible MCP tool pool requires restarting the TUI. -- `notes_path` (string, optional): defaults to `~/.deepseek/notes.txt` and is used by the model-visible `note` tool. +- `notes_path` (string, optional): defaults to `~/.codewhale/notes.txt`, with + legacy `~/.deepseek/notes.txt` fallback when the CodeWhale path is absent, and + is used by the model-visible `note` tool. - `[memory].enabled` (bool, optional): defaults to `false`. When `true`, the TUI loads the user memory file into a `` prompt block, enables `# foo` quick-capture in the composer, surfaces the `/memory` slash command, and registers the `remember` tool. The same toggle is available via `DEEPSEEK_MEMORY=on`. -- `memory_path` (string, optional): defaults to `~/.deepseek/memory.md`. +- `memory_path` (string, optional): defaults to `~/.codewhale/memory.md`, with + legacy `~/.deepseek/memory.md` fallback when the CodeWhale path is absent. Used by the user-memory feature when enabled — see [`MEMORY.md`](MEMORY.md) for the full feature surface (`# foo` composer prefix, `/memory` slash command, `remember` tool, opt-in @@ -533,7 +549,10 @@ If you are upgrading from older releases: - `snapshots.*` (optional): side-git workspace snapshots for file rollback: - `[snapshots].enabled` (bool, default `true`) - `[snapshots].max_age_days` (int, default `7`) - - snapshots live under `~/.deepseek/snapshots///.git` and never use the workspace's own `.git` directory + - snapshots live under + `~/.codewhale/snapshots///.git`, with legacy + `~/.deepseek/snapshots/...` fallback when only the legacy state exists, and + never use the workspace's own `.git` directory - `context.*` (optional): append-only Fin seam manager, currently opt-in. Fin is the fast `deepseek-v4-flash` path with thinking off used for coordination work such as routing, summaries, and context maintenance. @@ -617,7 +636,7 @@ User memory is split across one top-level path setting and one opt-in toggle table: ```toml -memory_path = "~/.deepseek/memory.md" +memory_path = "~/.codewhale/memory.md" [memory] enabled = true @@ -755,7 +774,8 @@ See `docs/capacity_controller.md` for formulas, intervention behavior, and telem ## Notes On `codewhale-tui doctor` `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 +TUI. That means `--config`, `CODEWHALE_CONFIG_PATH`, and the legacy +`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 `codewhale-tui setup --all`. You can @@ -790,19 +810,22 @@ configure reasoning effort. MCP/skills/tools/plugins counts, sandbox, `.env` presence). Read-only and network-free; safe to run in CI. If `.env` is missing and `.env.example` is present in the workspace, the status output points at `cp .env.example .env`. -- `--tools` — scaffold `~/.deepseek/tools/` with a `README.md` describing the +- `--tools` — scaffold `~/.codewhale/tools/` with a `README.md` describing the self-describing frontmatter convention (`# name:` / `# description:` / `# usage:`) and an `example.sh` that follows it. The directory is intentionally not auto-loaded; wire individual scripts into the agent via MCP, hooks, or skills. -- `--plugins` — scaffold `~/.deepseek/plugins/` with a `README.md` and an +- `--plugins` — scaffold `~/.codewhale/plugins/` with a `README.md` and an `example/PLUGIN.md` placeholder using the same frontmatter shape as `SKILL.md`. Plugins are not loaded automatically either; reference them from a skill, hook, or MCP wrapper when you want them active. - `--all` now scaffolds MCP + skills + tools + plugins together. -- `--clean` — list `~/.deepseek/sessions/checkpoints/latest.json` and - `offline_queue.json` if they exist. Pass `--force` to actually remove them. - This never touches real session history or the task queue. +- `--clean` — list `~/.codewhale/sessions/checkpoints/latest.json` and + `offline_queue.json` if they exist. Legacy + `~/.deepseek/sessions/checkpoints/` files are not scanned automatically; set + `CODEWHALE_HOME=~/.deepseek` for a one-off legacy cleanup. Pass `--force` to + actually remove matched files. This never touches real session history or the + task queue. `--status` and `--clean` are mutually exclusive with the scaffold flags.