| 1 | # Codewhale User Guide |
| 2 | |
| 3 | This guide is for your first hour with Codewhale. It explains the main |
| 4 | workflow, the important safety controls, and where to go next when you need a |
| 5 | complete reference. |
| 6 | |
| 7 | Codewhale has deeper reference documents for installation, configuration, |
| 8 | providers, modes, keybindings, tools, and operations. Use this page as a guided |
| 9 | walkthrough, then follow the "Next" links when you need every option. |
| 10 | |
| 11 | ## 1. Welcome to Codewhale |
| 12 | |
| 13 | Codewhale is a terminal coding agent. You run it from a workspace, give it a |
| 14 | task, and it can use structured tools to inspect files, run commands, edit |
| 15 | code, and report back with evidence. |
| 16 | |
| 17 | The important difference from a normal chat model is that Codewhale is built |
| 18 | around a harness: |
| 19 | |
| 20 | - It keeps the active workspace and session visible. |
| 21 | - It routes each turn through explicit modes and approval rules. |
| 22 | - It shows tool calls in the transcript instead of hiding the work. |
| 23 | - It can preserve sessions, fork conversations, and continue later. |
| 24 | - It can run sub-agents for focused background work. |
| 25 | |
| 26 | You can use Codewhale for small questions: |
| 27 | |
| 28 | ```text |
| 29 | Explain the authentication flow in this repository. |
| 30 | ``` |
| 31 | |
| 32 | You can also use it for multi-step work: |
| 33 | |
| 34 | ```text |
| 35 | Find the failing validation path, propose a fix, and wait for my approval |
| 36 | before editing files. |
| 37 | ``` |
| 38 | |
| 39 | For a new repository, start conservatively. Ask Codewhale to explore and plan |
| 40 | before asking it to change files. That gives you a reviewable path and makes it |
| 41 | easier to catch wrong assumptions early. |
| 42 | |
| 43 | Next: [ARCHITECTURE.md](ARCHITECTURE.md) explains the internal harness and |
| 44 | runtime model. |
| 45 | |
| 46 | ## 2. First Launch |
| 47 | |
| 48 | For a new macOS or Linux installation, use the official GitHub release. |
| 49 | The installer verifies the release checksums and provides the same runtime |
| 50 | under the `codewhale` and `codew` command names: |
| 51 | |
| 52 | ```bash |
| 53 | curl -fsSL https://codewhale.net/install.sh | sh |
| 54 | ``` |
| 55 | |
| 56 | Windows users should choose the matching installer or archive from |
| 57 | [GitHub Releases](https://github.com/codewhale-hq/CodeWhale/releases/latest). |
| 58 | For an existing direct install, use `codewhale update --check`, then |
| 59 | `codewhale update`. npm and Cargo remain secondary packaging routes; Cargo |
| 60 | also supports source builds where a compatible prebuilt is unavailable. |
| 61 | For occupied directories, package-managed installs, and PATH setup, follow |
| 62 | [the installation and migration guide](INSTALL.md#recommended-official-github-releases). |
| 63 | Android/Termux uses its own [preview archive or source-build path](INSTALL.md#android--termux-arm64). |
| 64 | |
| 65 | Docker is also available when you want an isolated runtime: |
| 66 | |
| 67 | ```bash |
| 68 | docker volume create codewhale-home |
| 69 | docker run --rm -it \ |
| 70 | -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ |
| 71 | -v codewhale-home:/home/codewhale/.codewhale \ |
| 72 | -v "$PWD:/workspace" \ |
| 73 | -w /workspace \ |
| 74 | ghcr.io/codewhale-hq/codewhale:latest |
| 75 | ``` |
| 76 | |
| 77 | Once the install directory is on PATH, launch Codewhale from the repository or |
| 78 | directory you want it to work in: |
| 79 | |
| 80 | ```bash |
| 81 | codewhale |
| 82 | ``` |
| 83 | |
| 84 | For the default GitHub installer destination, you can use |
| 85 | `"$HOME/.local/bin/codewhale"` until that directory is on PATH. |
| 86 | |
| 87 | On first launch, Codewhale asks only for decisions this installation still |
| 88 | needs: language when it cannot infer one, a provider when no usable route is |
| 89 | configured, and workspace trust when the folder requires a decision. The |
| 90 | provider step includes an explicit offline route. The ready screen then opens |
| 91 | the real composer, preserving a task supplied on the command line or suggesting |
| 92 | a first task for the current folder. |
| 93 | |
| 94 | Everything optional stays available after that. Use `/setup` for the |
| 95 | progressive setup and repair guide, `/settings` for the full typed editor, and |
| 96 | `/constitution` when you want to customize the bundled working agreement. |
| 97 | The localized telemetry choice appears only after the workspace is ready and |
| 98 | does not block the composer. |
| 99 | |
| 100 | DeepSeek is the default provider. If you want to configure its key before or |
| 101 | after the first launch, the most direct setup path is: |
| 102 | |
| 103 | ```bash |
| 104 | codewhale auth set --provider deepseek |
| 105 | ``` |
| 106 | |
| 107 | You can also provide a key through the environment: |
| 108 | |
| 109 | ```bash |
| 110 | export DEEPSEEK_API_KEY="your-key" |
| 111 | codewhale |
| 112 | ``` |
| 113 | |
| 114 | New Codewhale config is stored under `~/.codewhale/config.toml`. Legacy |
| 115 | `~/.deepseek/config.toml` files are still supported for users migrating from |
| 116 | the old name. |
| 117 | |
| 118 | Use `/constitution` to review or change standing guidance. After setup, run a |
| 119 | doctor check: |
| 120 | |
| 121 | ```bash |
| 122 | codewhale doctor |
| 123 | ``` |
| 124 | |
| 125 | Use the JSON form when you need a machine-readable report for an issue: |
| 126 | |
| 127 | ```bash |
| 128 | codewhale doctor --json |
| 129 | ``` |
| 130 | |
| 131 | Both forms are offline by default. They report structural configuration and |
| 132 | literal unknown/not-probed credential states without loading workspace `.env` |
| 133 | credentials, opening secret/OAuth files, probing a keyring, contacting a |
| 134 | provider, or starting MCP servers. Use `--check-updates`, `--probe-api`, |
| 135 | `--probe-local`, or `--probe-mcp` only when you intentionally want that live |
| 136 | boundary. JSON remains offline and does not accept live flags. |
| 137 | |
| 138 | JSON reports credential `source` separately from literal `availability`. |
| 139 | Configured environment, external-auth, OAuth, consent, and secret-store sources |
| 140 | remain `not_probed`; their declaration alone does not make Setup or fleet ready. |
| 141 | Only a structurally present literal config value, or a route where credentials |
| 142 | are not required, certifies offline readiness. A legacy secret-store sentinel on |
| 143 | a route that cannot use the shared store is reported separately as |
| 144 | `secret_store_unavailable`/`unavailable`, not as eligible or merely unknown. |
| 145 | |
| 146 | Both `doctor` and `doctor --json` also include a session-recovery diagnostic |
| 147 | that compares legacy session filenames against the current store and reports |
| 148 | one of `isolated`, `no_legacy_sessions`, `migration_pending`, |
| 149 | `migration_incomplete`, `migration_complete`, or `scan_failed`; it never reads |
| 150 | session contents. Use `migration_pending` or `migration_incomplete` as your |
| 151 | cue to finish moving sessions from `~/.deepseek` to `~/.codewhale`, the same |
| 152 | legacy-path migration described above. Setting an explicit `CODEWHALE_HOME` |
| 153 | suppresses this ambient inspection. |
| 154 | |
| 155 | Next: [INSTALL.md](INSTALL.md) covers platform-specific install paths, |
| 156 | [CONFIGURATION.md](CONFIGURATION.md) covers config resolution, and |
| 157 | [PROVIDERS.md](PROVIDERS.md) covers provider IDs and credentials. |
| 158 | |
| 159 | ## 3. Your First Task |
| 160 | |
| 161 | Start with a read-only task in a real workspace: |
| 162 | |
| 163 | ```text |
| 164 | Map the repository structure and tell me where the CLI entrypoint lives. |
| 165 | ``` |
| 166 | |
| 167 | Then ask for a focused plan: |
| 168 | |
| 169 | ```text |
| 170 | I want to add a small validation for empty config values. Inspect the relevant |
| 171 | code and propose the smallest safe change before editing anything. |
| 172 | ``` |
| 173 | |
| 174 | When you are ready for edits, be specific about the acceptance criteria: |
| 175 | |
| 176 | ```text |
| 177 | Implement the validation you proposed. Keep the change scoped to config |
| 178 | parsing, add or update the narrowest test, and run the relevant check. |
| 179 | ``` |
| 180 | |
| 181 | Good first prompts include four details: |
| 182 | |
| 183 | - The outcome you want. |
| 184 | - The files, feature, or behavior you care about. |
| 185 | - What is out of scope. |
| 186 | - What verification should count as done. |
| 187 | |
| 188 | For example: |
| 189 | |
| 190 | ```text |
| 191 | Fix the broken provider error message in the config loader. Do not change the |
| 192 | provider registry. Add a regression test and run only the config crate tests. |
| 193 | ``` |
| 194 | |
| 195 | If you are not sure where the bug is, say that: |
| 196 | |
| 197 | ```text |
| 198 | Investigate why `codewhale doctor` reports the wrong provider. Do not edit |
| 199 | files yet. Return the likely cause, evidence, and a proposed patch plan. |
| 200 | ``` |
| 201 | |
| 202 | Codewhale works best when you let investigation and implementation happen in |
| 203 | separate steps for unfamiliar code. For small, well-understood changes, a |
| 204 | single implementation request is fine. |
| 205 | |
| 206 | Next: [MODES.md](MODES.md) explains when to use Plan, Work, and Operate. |
| 207 | |
| 208 | ## 4. Understanding the Interface |
| 209 | |
| 210 | The interactive TUI has a few stable regions: |
| 211 | |
| 212 | - Header: current session, active model, mode, and high-level status. |
| 213 | - Transcript: the conversation, tool calls, command output summaries, and |
| 214 | model responses. |
| 215 | - Composer: where you type prompts, slash commands, and file mentions. |
| 216 | - Workbar: the strip under the composer (or an optional side workbar) that |
| 217 | holds the active goal, the to-do list, and sub-agents. Rows stay for the |
| 218 | whole session — finished work reads as done rather than disappearing — and |
| 219 | clicking a row (or pressing `Enter` on it) opens its detail. |
| 220 | - Status and footer areas: live activity, queued follow-ups, and short command |
| 221 | hints. |
| 222 | |
| 223 | When the model asks a question (`request_user_input`), a bottom sheet opens |
| 224 | over the transcript rather than a centered overlay. The conversation stays |
| 225 | visible above it. Use `PageUp`/`PageDown`, `Home`/`End`, or modified `↑`/`↓` |
| 226 | (`Ctrl`, `Alt`, or `Shift`) to review the transcript while the sheet stays open. |
| 227 | The mouse wheel scrolls the transcript above the sheet and the question content |
| 228 | over the sheet itself. Moving the highlight or typing brings that content back |
| 229 | into view after wheel browsing. Use `↑`/`↓` to move, `Enter` to confirm, `←`/`h` |
| 230 | to go back to a previous question, and `Esc` to cancel the whole request. |
| 231 | Every question offers an "Other" row for a custom response; that text stays on |
| 232 | screen while you type. Keys for the sheet are in [KEYBINDINGS.md](KEYBINDINGS.md). |
| 233 | |
| 234 | The bottom chrome is configurable. Run `/statusline` to choose what is |
| 235 | visible, or set `[tui].status_items` in `config.toml`. Each key owns exactly |
| 236 | one thing on screen: `mode` is the posture bar's plan/act/operate chip, and |
| 237 | `model`, `context_percent`, `cost`, `balance` (prepaid providers only: |
| 238 | DeepSeek, DeepSeekCN, OpenRouter, SiliconFlow), `cache`, `tokens` and |
| 239 | `ttft`, `output_rate`, `workspace` and `git_branch` are segments of the metrics line below it. Omit |
| 240 | `status_items` to keep the built-in default; set it to `[]` to strip the |
| 241 | metrics line down to the help hint. |
| 242 | |
| 243 | `workspace` and `git_branch` are opt-in. The workspace chip shows the folder |
| 244 | name; linked worktrees include its parent to distinguish repeated names. The |
| 245 | branch chip shows the current branch or a short detached HEAD SHA, with `(wt)` |
| 246 | for linked worktrees. Both keep the last 24 display columns when long. Git |
| 247 | metadata refreshes in the background on the existing 15-second cadence and |
| 248 | when a refresh is requested; unavailable Git data removes the branch chip. |
| 249 | These identify the active session workspace. The full path remains in `/status`. |
| 250 | |
| 251 | `context_percent` is on by default and shows `ctx NN%` at every fullness — |
| 252 | 0.9.12 went silent below 50% and left most of a session with no context |
| 253 | signal at all. The reading keeps its warning colour from 80% up. |
| 254 | |
| 255 | The keys `status`, `agents`, `reasoning_replay`, `prefix_stability`, |
| 256 | `last_tool_elapsed` and `rate_limit` were retired in 0.9.13: |
| 257 | they drove nothing. Old configuration files still load — the retired keys are |
| 258 | ignored with a warning in the log. |
| 259 | |
| 260 | `status_items` composes the rows; two size presets decide how much of each |
| 261 | row paints. `[tui].posture_bar` and `[tui].metrics_line` each take `full`, |
| 262 | `compact`, or `hidden`. The posture bar defaults to `full` so active controls |
| 263 | stay visible; the metrics line defaults to `compact` to keep selected performance |
| 264 | readings while removing secondary counts and help. These are also settable at runtime with |
| 265 | `/config posture_bar compact`. TOML values must be lowercase; `/config` |
| 266 | accepts either case. `compact` is the row after its first shed |
| 267 | rungs: the posture bar keeps its permission and mode chips — and the cap |
| 268 | warning, which is advice, not decoration — and drops the clocks, counts and |
| 269 | hint; the metrics line keeps the route, the context reading, the cost and |
| 270 | the balance, plus selected TTFT and output rate when space allows, and drops |
| 271 | secondary counts and the help hint. `hidden` gives the |
| 272 | row back to the transcript. A small tmux pane can hide both rows without |
| 273 | touching what `/statusline` composes. |
| 274 | |
| 275 | Both `ttft` and `output_rate` are on by default and work in full or compact |
| 276 | rows. `/statusline` lets you toggle them separately; Space previews, Enter saves, |
| 277 | and Esc restores your previous settings. Legacy `session_metrics` still enables |
| 278 | both readings. The pair shows: `ttft 1.5s` — the mean time to first streamed token — and `120 avg tok/s`, |
| 279 | the session's provider-reported output tokens divided by the measured request |
| 280 | seconds for those same calls. The rate includes connection setup, time to first |
| 281 | token and pauses within a response, and excludes tools and idle time between |
| 282 | calls. It measures effective request throughput, not decoder speed. Streaming |
| 283 | and non-streaming calls follow the same rule; receipts without individual |
| 284 | request timing are excluded from both tokens and time. While a request runs, |
| 285 | the last measured average stays visible. Both readings use the same |
| 286 | accumulators `/status` prints in full. Missing evidence is omitted rather than |
| 287 | estimated. On narrow rows the pair sheds before cost and context. |
| 288 | |
| 289 | Every file read, command, and edit appears in the transcript as it happens. |
| 290 | `/receipts` lists what the session did, one line per action; see |
| 291 | [What Codewhale records](#what-codewhale-records). If a command fails, use the |
| 292 | visible failure output as part of your next instruction instead of starting |
| 293 | over. |
| 294 | |
| 295 | The composer accepts normal prompts and slash commands. Type `/` to discover |
| 296 | available commands. Use file mentions when you want the model to focus on a |
| 297 | specific file or directory instead of searching broadly. |
| 298 | |
| 299 | The workbar is useful when a turn spans multiple steps. It keeps the goal, |
| 300 | the to-do list, and agent state visible while the transcript continues to |
| 301 | grow — including after the work settles, so you can still open what happened. |
| 302 | |
| 303 | Keyboard shortcuts vary by context, terminal, and platform. This guide avoids |
| 304 | duplicating the full shortcut catalog so it does not drift from the TUI. |
| 305 | |
| 306 | Next: [KEYBINDINGS.md](KEYBINDINGS.md) is the complete shortcut reference. |
| 307 | |
| 308 | ## 5. Modes |
| 309 | |
| 310 | Codewhale has three visible TUI modes: |
| 311 | |
| 312 | | Mode | Use it for | Default posture | |
| 313 | | --- | --- | --- | |
| 314 | | Plan | Exploration, design, and review before changes | Read-only investigation | |
| 315 | | Work | Normal multi-step coding work | Tool use with approval gates | |
| 316 | | Operate | Direct work plus parallel or background coordination | Tools follow the active posture; delegate when useful | |
| 317 | |
| 318 | Switch modes from the TUI with the mode picker: |
| 319 | |
| 320 | ```text |
| 321 | /mode |
| 322 | ``` |
| 323 | |
| 324 | Or switch directly: |
| 325 | |
| 326 | ```text |
| 327 | /mode plan |
| 328 | /mode work |
| 329 | /mode operate |
| 330 | ``` |
| 331 | |
| 332 | Plan mode is the safest place to start in an unfamiliar repository. It is for |
| 333 | inspection and decision-making, not file edits. |
| 334 | For non-trivial work, Plan mode's confirmation prompt can show a grounded |
| 335 | PlanArtifact: objective, context, sources used, critical files, constraints, |
| 336 | approach, verification plan, risks, and handoff notes. Empty sections are |
| 337 | visible when the agent uses the rich artifact shape, so you can ask for a |
| 338 | revision instead of accepting an under-specified plan. |
| 339 | |
| 340 | Work mode is the default for most contribution work. It lets Codewhale read, |
| 341 | run checks, and edit files while keeping risky actions behind approval gates. |
| 342 | |
| 343 | Operate keeps that direct tool surface and its approval, sandbox, shell, |
| 344 | ask-rule, and repository protections. Small or tightly coupled work stays |
| 345 | direct. Multi-step delegation uses a compact Workflow plan with dependencies, |
| 346 | bounded scopes, and completion evidence passed between steps. Fleet configures |
| 347 | and manages those same sub-agents and their roles. One bounded, independent |
| 348 | task can use a direct agent; continued work reuses it through `followup`. |
| 349 | Heavy work can also be proposed to a Daytona cloud agent with `codewhale |
| 350 | dispatch` or `/dispatch` (explicit confirmation; remotes are `github` / `cnb` / |
| 351 | `gitee`). See [DAYTONA_CLOUD_DISPATCH.md](DAYTONA_CLOUD_DISPATCH.md). |
| 352 | |
| 353 | For trusted workspaces where you intentionally want actions to proceed without |
| 354 | approval prompts, select the Full Access permission posture with `Shift+Tab`. |
| 355 | Do not use Full Access in a repository you do not trust. |
| 356 | |
| 357 | Modes are separate from model routing. `Tab` cycles visible modes when the |
| 358 | composer is idle, while `/model auto` controls model and thinking selection for |
| 359 | turns. |
| 360 | |
| 361 | You can also change approval behavior from `/config` by editing the approval |
| 362 | mode. Use this only when you understand how it changes tool execution. |
| 363 | |
| 364 | Next: [MODES.md](MODES.md) has the full mode, approval, and trust-mode |
| 365 | reference. |
| 366 | |
| 367 | ## 6. Slash Commands |
| 368 | |
| 369 | Slash commands are typed into the composer. They are useful when you want to |
| 370 | change Codewhale state directly instead of asking the model in natural |
| 371 | language. |
| 372 | |
| 373 | Common commands for first-time users: |
| 374 | |
| 375 | | Command | Use | |
| 376 | | --- | --- | |
| 377 | | `/mode` | Open the mode picker or switch with `/mode agent` | |
| 378 | | `/model` | Select a model or use `/model auto` | |
| 379 | | `/provider` | Pick the active API provider | |
| 380 | | `/fleet` | Open the selected fleet's member roster | |
| 381 | | `/fleet saved` | Pick or switch among named saved fleets | |
| 382 | | `/goal` | Set a persistent objective the agent works toward across turns; bare `/goal` shows progress | |
| 383 | | `/workflow` | Orchestrate the current work as a Workflow; `status`, `cancel`, `settings` answer without a model turn | |
| 384 | | `/workflows` | Open the live Workflow run dashboard: every run this workspace's journal keeps, with phases, children, progress, and host-side cancel | |
| 385 | | `/config` | Edit runtime and provider settings | |
| 386 | | `/statusline` | Choose which footer status chips are visible | |
| 387 | | `/receipts` | List what this session did: files changed, commands run, web and MCP calls, agents, approvals and who gave them, failures | |
| 388 | | `/compact` | Summarize long context to recover token budget | |
| 389 | | `/copy` | Copy the last completed assistant response to the clipboard | |
| 390 | | `/review` | Ask for a structured review workflow | |
| 391 | | `/memory` | Inspect or manage memory when enabled | |
| 392 | | `/mcp` | Configure or inspect MCP server integration | |
| 393 | | `/plugin` | Review and manage disabled-by-default local plugin bundles | |
| 394 | | `/rc` | Hand this exact session to the signed-in Codewhale web app | |
| 395 | |
| 396 | Toolbox commands stay searchable when you type them directly: `/models` |
| 397 | fetches live endpoint IDs, `/modeldb` opens the bundled model reference, and |
| 398 | `/rlm` loads a file or block of text into a working context that stays |
| 399 | available for the rest of the session. |
| 400 | |
| 401 | Use `/provider` when you want to switch away from the default DeepSeek route. |
| 402 | Provider IDs, environment variables, model defaults, and capability notes are |
| 403 | kept in the provider registry document. |
| 404 | |
| 405 | Soft-auto multi-agent work: [AUTOMATIC_WORKFLOWS.md](AUTOMATIC_WORKFLOWS.md). |
| 406 | |
| 407 | Posting Codewhale PR reviews as a bot identity: |
| 408 | [GITHUB_APP.md](GITHUB_APP.md). |
| 409 | |
| 410 | Next for durable multi-worker work: [FLEET_WORKFLOW_TUTORIAL.md](FLEET_WORKFLOW_TUTORIAL.md) |
| 411 | walks through fleet task specs, monitoring, and Workflow authoring. |
| 412 | |
| 413 | Fleet is the public noun for the durable roster. `codewhale fleet …` is |
| 414 | the command and `/fleet` the slash command. The Fleet name is |
| 415 | shared by what has to stay stable across versions: the durable ledger |
| 416 | `.codewhale/fleet.jsonl`, saved rosters `fleets/<name>.toml`, the `[fleet]` |
| 417 | config table, and the `codewhale workflow run --fleet` flag. |
| 418 | |
| 419 | Use `/model auto` when you want Codewhale to choose the model and thinking |
| 420 | level per turn. When the DeepSeek routing model is available, Auto may select |
| 421 | any runnable provider/model pair in the redacted inventory. That classification |
| 422 | sends the latest request (capped at 4,000 characters) plus a bounded summary of |
| 423 | up to six recent context rows (900 characters each) to |
| 424 | `DeepSeek / deepseek-v4-flash`. Credentials, endpoints, and provider error text |
| 425 | are not included in the inventory. Without that router, Auto uses a local, |
| 426 | provider-aware heuristic and sends no routing request. If a classifier attempt |
| 427 | fails validation or errors, Auto falls back to that heuristic while retaining |
| 428 | the attempted classifier data path in the turn receipt. |
| 429 | |
| 430 | The `/model` picker states which data path is available and shows the last |
| 431 | resolved route. `Ctrl+O` opens the reasoning detail for the selected or current |
| 432 | turn; `Ctrl+Alt+O` (or `/turn inspect`) opens the whole-turn Turn Inspector, |
| 433 | whose model-route section records the concrete provider/model, strong/fast pair, |
| 434 | selected tier, selection scope, route reason, and whether the classifier received |
| 435 | routing context. Use a |
| 436 | fixed model when you need repeatable comparisons, a strict provider boundary, |
| 437 | or no classification request. |
| 438 | |
| 439 | Use `/compact` when a session gets long and the model starts carrying too much |
| 440 | history. Compaction trades raw transcript detail for a concise working summary. |
| 441 | |
| 442 | This guide intentionally does not list every command. The command surface |
| 443 | changes more often than the onboarding flow, and the TUI command palette is the |
| 444 | source of truth while you are inside a session. |
| 445 | |
| 446 | Next: [CONFIGURATION.md](CONFIGURATION.md) covers runtime settings and |
| 447 | [MCP.md](MCP.md) covers Model Context Protocol integration. |
| 448 | [PLUGIN_BUNDLES.md](PLUGIN_BUNDLES.md) covers the disabled-by-default bundle |
| 449 | inventory, capability review, and namespaced Skill/MCP activation boundary. |
| 450 | |
| 451 | ## 7. Working with Tools |
| 452 | |
| 453 | Codewhale tools are structured actions. Instead of only producing prose, the |
| 454 | model can call tools to inspect and change the workspace. |
| 455 | |
| 456 | Examples of tool-backed work include: |
| 457 | |
| 458 | - Reading a file before explaining it. |
| 459 | - Searching for call sites before proposing a refactor. |
| 460 | - Running a focused test command. |
| 461 | - Applying a small patch. |
| 462 | - Opening a sub-agent for parallel investigation. |
| 463 | |
| 464 | Tool use is governed by mode, approvals, and sandbox policy. The exact behavior |
| 465 | depends on the current mode and config, but the basic rule is simple: start in |
| 466 | Plan for read-only exploration, use Work for normal changes, and reserve Full |
| 467 | Access for trusted automation. |
| 468 | |
| 469 | The workspace boundary matters. Codewhale is expected to work in the directory |
| 470 | you launched it from or the workspace you configured. Be explicit when a task |
| 471 | should stay inside a repo: |
| 472 | |
| 473 | ```text |
| 474 | Only inspect and edit files under this repository. Do not touch parent |
| 475 | directories or global config. |
| 476 | ``` |
| 477 | |
| 478 | When a command needs network, writes outside the workspace, or a risky shell |
| 479 | operation, expect an approval prompt unless you have configured more permissive |
| 480 | behavior. |
| 481 | |
| 482 | Good tool instructions are concrete: |
| 483 | |
| 484 | ```text |
| 485 | Run the narrowest test that covers this parser change. If it fails, report the |
| 486 | failure and stop before broadening the test scope. |
| 487 | ``` |
| 488 | |
| 489 | Avoid asking for broad cleanup during a focused fix. Smaller tool scopes make |
| 490 | the transcript easier to review and the final diff easier to merge. |
| 491 | |
| 492 | Next: [TOOL_SURFACE.md](TOOL_SURFACE.md) lists the tool surface and |
| 493 | [SANDBOX.md](SANDBOX.md) explains sandbox behavior. |
| 494 | |
| 495 | ### What Codewhale records |
| 496 | |
| 497 | Codewhale keeps these records on your machine, under `~/.codewhale/`: |
| 498 | |
| 499 | - **The session.** `sessions/<id>.json` holds the full conversation, |
| 500 | including every tool call and its result text. App and `codewhale serve` |
| 501 | threads keep each call as a turn item under `tasks/runtime/`, with its |
| 502 | input, status, start and end time, and structured result. |
| 503 | - **Approvals.** `sessions/<id>/approval_receipts.jsonl` records every |
| 504 | approval Codewhale asked for, the decision, and who made it: you, a |
| 505 | session rule, or the active posture. App threads also record each decision |
| 506 | in their event log. A call that ran without asking (Full Access, an allow |
| 507 | rule, a remembered grant) has no approval record; the posture each turn |
| 508 | ran under is saved with the turn. |
| 509 | - **Undo points.** Workspace snapshots let `/undo` and `/restore` roll files |
| 510 | back. |
| 511 | - **Security events.** `audit.log` records credential changes, hook |
| 512 | environment key names, compaction passes, the terminal's approval |
| 513 | routing, and Auto-Review verdicts. It is not a list of what a session did. |
| 514 | |
| 515 | To see what a session did, run `/receipts`, or from a shell: |
| 516 | |
| 517 | ```bash |
| 518 | codewhale receipts --last |
| 519 | codewhale receipts <session-id> --format json |
| 520 | ``` |
| 521 | |
| 522 | A receipt says what it cannot show. A terminal session's receipt lists the |
| 523 | files a command changed from each turn's workspace snapshots; a Runtime |
| 524 | thread's lists only file tools. Terminal sessions do not save a passing |
| 525 | command's exit code or how long each call took. A call Codewhale blocked |
| 526 | before it started (Auto-Review, a policy, invalid input) is listed as |
| 527 | blocked, with the reason, and is not counted as run. [RECEIPTS.md](RECEIPTS.md) has the full contract. |
| 528 | |
| 529 | ## 8. Sub-agents and Parallel Work |
| 530 | |
| 531 | Sub-agents are background child agents. The parent session gives a child a |
| 532 | focused task, receives an agent id, and can continue working while the child |
| 533 | runs. |
| 534 | |
| 535 | The main orchestration tool is: |
| 536 | |
| 537 | - `agent`: start a focused child with a task and role. The child runs in the |
| 538 | background and returns a compact receipt plus transcript handle. |
| 539 | |
| 540 | You normally do not need to call these tools directly. Ask for parallel work in |
| 541 | plain language: |
| 542 | |
| 543 | ```text |
| 544 | Open one read-only explorer for the config crate and another for the TUI |
| 545 | provider picker. Have both return file references and risks before we plan the |
| 546 | fix. |
| 547 | ``` |
| 548 | |
| 549 | Useful roles include: |
| 550 | |
| 551 | | Role | Good for | |
| 552 | | --- | --- | |
| 553 | | `general` | Multi-step tasks; the default when no role is specified | |
| 554 | | `explore` | Read-only code mapping | |
| 555 | | `plan` | Design and migration planning | |
| 556 | | `review` | Bug-focused review of an existing change | |
| 557 | | `implementer` | A tightly specified edit | |
| 558 | | `verifier` | Running checks and reporting pass/fail evidence | |
| 559 | |
| 560 | Sub-agents are most useful when work can be separated cleanly. Do not use them |
| 561 | for tiny edits, and do not ask multiple agents to write the same files at the |
| 562 | same time. |
| 563 | |
| 564 | ### How long work stays coherent |
| 565 | |
| 566 | Work that spans many turns does not rely on an ever-growing chat transcript. |
| 567 | This is ordinary Agent behavior — there is nothing to turn on and no separate |
| 568 | workflow to learn: |
| 569 | |
| 570 | - A working context stays loaded for the session. Large source material and the |
| 571 | durable transcript are held as data the agent can search and slice, and useful |
| 572 | variables and imports survive across turns. |
| 573 | - Workflow composes independent `task(...)` calls and parallel fan-out. |
| 574 | - `agent` messages and follow-ups coordinate active children directly. |
| 575 | - Goals retain the durable objective across the work. |
| 576 | |
| 577 | `/rlm <file-or-text>` points that working context at a specific file or block |
| 578 | of text. The historic action-shaped `rlm` tool remains registered only so older |
| 579 | sessions replay, and is deliberately not taught to new model turns. |
| 580 | |
| 581 | Codewhale can also keep a small project-local ledger at |
| 582 | `.codewhale/harness/state.json`: evidence-backed prompt notes, reusable child |
| 583 | briefs, and skill-routing hints. Later turns receive it as untrusted |
| 584 | supplemental guidance, never as authority or executable instructions. Reading it |
| 585 | is automatic; adding or removing an entry goes through the normal approval |
| 586 | receipt. It is separate from personal memory, and it must never hold secrets, |
| 587 | scratch transcripts, or unverified claims. |
| 588 | |
| 589 | Next: [SUBAGENTS.md](SUBAGENTS.md) covers roles, lifecycle, concurrency, and |
| 590 | output contracts. |
| 591 | |
| 592 | ## 9. Skills |
| 593 | |
| 594 | Skills are reusable instruction packs. A skill is usually a `SKILL.md` file |
| 595 | that teaches Codewhale how to perform a recurring workflow, use a tool family, |
| 596 | or follow a project convention. |
| 597 | |
| 598 | Use skills when a task has a repeatable process: |
| 599 | |
| 600 | - Reviewing a specific kind of PR. |
| 601 | - Working with a document or spreadsheet format. |
| 602 | - Following a team release checklist. |
| 603 | - Using a project-specific memory or wiki workflow. |
| 604 | |
| 605 | Inside the TUI, `/skill <name>` activates a skill when one is available, and |
| 606 | bare `/skills` opens the Skills Manager (owned-only inventory, no network). Use |
| 607 | `/skills <prefix>`, `/skills inspect`, `/skills --remote`, `/skills suggest <task>`, |
| 608 | or `/skills sync` for the text/registry paths. Suggestions rank the remote |
| 609 | catalog but never install or activate anything. The command palette can also |
| 610 | surface skill entries alongside normal slash commands. |
| 611 | |
| 612 | Good skills are narrow. They should tell the model what workflow to follow, |
| 613 | what evidence to collect, and what to avoid. They should not hide credentials |
| 614 | or replace normal repository documentation. |
| 615 | |
| 616 | If a repository has its own instructions, treat them as part of the active |
| 617 | work. Read the local guidance before editing, and keep any contribution within |
| 618 | the repository's conventions. |
| 619 | |
| 620 | Next: see [SKILLS.md](SKILLS.md) for the manager, ownership, and provenance |
| 621 | rules; [CLAUDE_PLUGIN_COMPAT.md](CLAUDE_PLUGIN_COMPAT.md) for Claude Code |
| 622 | skill/plugin compatibility; and [CONFIGURATION.md](CONFIGURATION.md) for config |
| 623 | paths and project authority. |
| 624 | |
| 625 | ## 10. Getting Help |
| 626 | |
| 627 | Start with doctor output: |
| 628 | |
| 629 | ```bash |
| 630 | codewhale doctor |
| 631 | ``` |
| 632 | |
| 633 | Use JSON when filing a detailed issue: |
| 634 | |
| 635 | ```bash |
| 636 | codewhale doctor --json |
| 637 | ``` |
| 638 | |
| 639 | For authentication problems, use the structural source state to identify what |
| 640 | is declared. Doctor deliberately does not inspect environment, secret-store, |
| 641 | keyring, or OAuth token values. When a live check is appropriate, opt in with |
| 642 | `codewhale doctor --probe-api` (or `--probe-local` for a local endpoint). |
| 643 | |
| 644 | For provider problems, confirm the active provider and model: |
| 645 | |
| 646 | ```text |
| 647 | /provider |
| 648 | /model |
| 649 | ``` |
| 650 | |
| 651 | For long or confusing sessions, use `/compact` to reduce context pressure, or |
| 652 | start a fresh session in the same workspace and summarize what you need. |
| 653 | |
| 654 | When reporting an issue, include: |
| 655 | |
| 656 | - Codewhale version. |
| 657 | - Install method. |
| 658 | - Operating system and terminal. |
| 659 | - Provider and model. |
| 660 | - The exact command or prompt. |
| 661 | - Relevant doctor output. |
| 662 | - Whether the problem happens in a fresh workspace. |
| 663 | |
| 664 | Do not paste API keys, private source code, or secrets into a public issue. |
| 665 | |
| 666 | Next: [OPERATIONS_RUNBOOK.md](OPERATIONS_RUNBOOK.md) has operational triage and |
| 667 | recovery steps. |
| 668 | |
| 669 | ## FAQ |
| 670 | |
| 671 | ### Is Codewhale only for DeepSeek? |
| 672 | |
| 673 | DeepSeek is the default and first-class route, but Codewhale also supports |
| 674 | other hosted and local OpenAI-compatible providers. Use `/provider` or |
| 675 | `codewhale --provider <id>` to choose a provider. Keep the provider registry |
| 676 | open when configuring a non-default route. |
| 677 | |
| 678 | ### Which mode should I use first? |
| 679 | |
| 680 | Use Plan for unfamiliar code, Work for normal implementation, and Full Access |
| 681 | only for trusted repositories where automatic execution is acceptable. |
| 682 | |
| 683 | ### Why does Codewhale ask before running commands? |
| 684 | |
| 685 | Approvals are part of the safety model. Shell commands, paid tools, writes, and |
| 686 | actions outside the expected workspace can have side effects. Approval prompts |
| 687 | let you keep control while still letting the model do useful work. |
| 688 | |
| 689 | ### How do I run a Python file on macOS? |
| 690 | |
| 691 | Open Terminal in the folder that contains the file and run: |
| 692 | |
| 693 | ```bash |
| 694 | python3 your_file.py |
| 695 | ``` |
| 696 | |
| 697 | If macOS says `python3` is missing, install Python from |
| 698 | [python.org](https://www.python.org/downloads/macos/) or with Homebrew: |
| 699 | |
| 700 | ```bash |
| 701 | brew install python |
| 702 | ``` |
| 703 | |
| 704 | Inside Codewhale, ask the agent to inspect the file and run it with |
| 705 | `python3 your_file.py`. If the script needs packages, install them in a virtual |
| 706 | environment first: |
| 707 | |
| 708 | ```bash |
| 709 | python3 -m venv .venv |
| 710 | source .venv/bin/activate |
| 711 | python3 -m pip install -r requirements.txt |
| 712 | python3 your_file.py |
| 713 | ``` |
| 714 | |
| 715 | ### Where is my config stored? |
| 716 | |
| 717 | New Codewhale config uses `~/.codewhale/config.toml`. Legacy |
| 718 | `~/.deepseek/config.toml` remains supported for compatibility. Project overlays |
| 719 | can also affect behavior when a workspace config exists. |
| 720 | |
| 721 | ### How do I keep costs predictable? |
| 722 | |
| 723 | Use `/model auto` for routing, choose a fixed model when you need a strict |
| 724 | profile, and compact long sessions. For larger tasks, ask Codewhale to plan |
| 725 | before implementing so you do not spend tokens on the wrong path. |
| 726 | |
| 727 | ### How do I continue previous work? |
| 728 | |
| 729 | Codewhale saves sessions. Use the session picker or resume/continue CLI paths |
| 730 | documented in the README and modes guide. For a risky experiment, fork the |
| 731 | session before changing direction. |
| 732 | |
| 733 | The `/sessions` picker starts scoped to the current workspace so resumes stay |
| 734 | attached to the project you opened. Press `a` in the picker to show sessions |
| 735 | from every workspace, or run `codewhale sessions` to list all saved sessions |
| 736 | with last-updated timestamps before resuming a specific id. |
| 737 | |
| 738 | To archive the durable record and its artifacts, run: |
| 739 | |
| 740 | ```sh |
| 741 | codewhale sessions export <id-or-unique-prefix> --output session.tar.xz |
| 742 | ``` |
| 743 | |
| 744 | The archive contains `session.json`, a portable `container.json`, a manifest, |
| 745 | and regular files under `artifacts/`. Use `--skip-artifacts` for the record |
| 746 | only, `--compression 0` through `9` to choose the xz preset (default `6`), |
| 747 | and `--force` to replace an existing output. Store the archive outside the |
| 748 | session store. Symlinks are skipped; linked artifact roots, hard links, |
| 749 | nonportable filenames, and trees exceeding 64 directory levels or 100,000 |
| 750 | entries fail the export without replacing the destination. |
| 751 | |
| 752 | Unlike the sanitized Markdown `/export`, these archives retain unredacted |
| 753 | session content, including system prompts, thinking, tool calls and results, |
| 754 | journal branches, and approval receipts. Extract `session.json` and open it |
| 755 | with `/load` in the TUI; `/resume` imports the conversation only. Extracted |
| 756 | artifacts remain separate files and are not installed into the artifact store |
| 757 | by `/load`. Pause writes before archiving if every artifact must reflect the |
| 758 | same instant; growing files are bounded to their recorded size and shrinking |
| 759 | files abort the export. |
| 760 | |
| 761 | To continue the exact running session from the web app, type `/rc` or launch |
| 762 | with `codewhale rc`. Approve the one-time code in the system browser. While the |
| 763 | lease is active, the browser owns new prompts and approvals and the terminal is |
| 764 | a readable safety surface. Once connected, the banner and a transcript note |
| 765 | show the live session link (`https://app.codewhale.net/session?run=…`); |
| 766 | `/rc open` opens it in your browser and `/rc link` prints it. `/rc status` |
| 767 | shows ownership, `/rc stop` returns it to the terminal, and interrupt remains |
| 768 | available. A dropped connection keeps local input locked until the last web |
| 769 | lease expires so two controllers never race. Every folder you enroll from one |
| 770 | terminal shares a single stable device id, so the web app lists one computer |
| 771 | per machine rather than one per session. |
| 772 | |
| 773 | > Note (2026-09-14): the hosted web app at app.codewhale.net sunsets in phases |
| 774 | > under the 2026-09-14 product-client decision; the native GPUI desktop app |
| 775 | > (private `codehwhale-gpui` repo, phase map in `docs/TRANSITION.md`) is the |
| 776 | > successor surface. `/rc` keeps working against the web app while it remains |
| 777 | > live. |
| 778 | |
| 779 | ### What should I do when the model gets confused? |
| 780 | |
| 781 | Stop and restate the goal, constraints, and current evidence. If the transcript |
| 782 | is long, use `/compact` or start a fresh session with a short handoff. If the |
| 783 | problem is operational, run `codewhale doctor` and inspect the reported config |
| 784 | and provider state. |
| 785 | |
| 786 | ### Should I put project rules in prompts or files? |
| 787 | |
| 788 | Use repository files for durable project rules and prompts for turn-specific |
| 789 | intent. If a workflow repeats across projects, consider turning it into a |
| 790 | skill. |
| 791 | |
| 792 | ### Can Codewhale edit files outside the current repository? |
| 793 | |
| 794 | That depends on workspace boundaries, sandbox settings, trust mode, and |
| 795 | approval policy. For contribution work, keep instructions scoped to the current |
| 796 | repository unless you intentionally need something else. |
| 797 | |
| 798 | ### Where should I go after this guide? |
| 799 | |
| 800 | Read the focused reference for the thing you are changing. For most users, the |
| 801 | next pages are install, configuration, providers, modes, keybindings, tools, |
| 802 | and sub-agents. |
| 803 | |
| 804 | Next: [INSTALL.md](INSTALL.md), [CONFIGURATION.md](CONFIGURATION.md), |
| 805 | [PROVIDERS.md](PROVIDERS.md), [MODES.md](MODES.md), and |
| 806 | [TOOL_SURFACE.md](TOOL_SURFACE.md). |
| 807 |