# CodeWhale User Guide This guide is for your first hour with CodeWhale. It explains the main workflow, the important safety controls, and where to go next when you need a complete reference. CodeWhale has deeper reference documents for installation, configuration, providers, modes, keybindings, tools, and operations. Use this page as a guided walkthrough, then follow the "Next" links when you need every option. ## 1. Welcome to CodeWhale CodeWhale is a terminal coding agent. You run it from a workspace, give it a task, and it can use structured tools to inspect files, run commands, edit code, and report back with evidence. The important difference from a normal chat model is that CodeWhale is built around a harness: - It keeps the active workspace and session visible. - It routes each turn through explicit modes and approval rules. - It shows tool calls in the transcript instead of hiding the work. - It can preserve sessions, fork conversations, and continue later. - It can run sub-agents for focused background work. You can use CodeWhale for small questions: ```text Explain the authentication flow in this repository. ``` You can also use it for multi-step work: ```text Find the failing validation path, propose a fix, and wait for my approval before editing files. ``` For a new repository, start conservatively. Ask CodeWhale to explore and plan before asking it to change files. That gives you a reviewable path and makes it easier to catch wrong assumptions early. Next: [ARCHITECTURE.md](ARCHITECTURE.md) explains the internal harness and runtime model. ## 2. First Launch Install CodeWhale with the path that fits your machine. Each supported install path provides both the `codewhale` dispatcher and the `codewhale-tui` runtime. ```bash # npm npm install -g codewhale # Cargo cargo install codewhale-cli --locked cargo install codewhale-tui --locked # Homebrew, legacy installs only # The tap/formula still uses the old deepseek-tui name. Prefer npm, Cargo, # Docker, or direct downloads for new installs until the formula is renamed. brew tap Hmbown/deepseek-tui brew install deepseek-tui ``` Docker is also available when you want an isolated runtime: ```bash docker volume create codewhale-home docker run --rm -it \ -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ -v codewhale-home:/home/codewhale/.codewhale \ -v "$PWD:/workspace" \ -w /workspace \ ghcr.io/hmbown/codewhale:latest ``` Launch CodeWhale from the repository or directory you want it to work in: ```bash codewhale ``` On first launch, CodeWhale needs an API key for the active provider. DeepSeek is the default provider. The most direct setup path is: ```bash codewhale auth set --provider deepseek ``` You can also provide a key through the environment: ```bash export DEEPSEEK_API_KEY="your-key" codewhale ``` New CodeWhale config is stored under `~/.codewhale/config.toml`. Legacy `~/.deepseek/config.toml` files are still supported for users migrating from the old name. After setup, run a doctor check: ```bash codewhale doctor ``` Use the JSON form when you need a machine-readable report for an issue: ```bash codewhale doctor --json ``` If the doctor command reports that a rejected key came from the environment, remove or replace that environment variable before testing saved config again. Next: [INSTALL.md](INSTALL.md) covers platform-specific install paths, [CONFIGURATION.md](CONFIGURATION.md) covers config resolution, and [PROVIDERS.md](PROVIDERS.md) covers provider IDs and credentials. ## 3. Your First Task Start with a read-only task in a real workspace: ```text Map the repository structure and tell me where the CLI entrypoint lives. ``` Then ask for a focused plan: ```text I want to add a small validation for empty config values. Inspect the relevant code and propose the smallest safe change before editing anything. ``` When you are ready for edits, be specific about the acceptance criteria: ```text Implement the validation you proposed. Keep the change scoped to config parsing, add or update the narrowest test, and run the relevant check. ``` Good first prompts include four details: - The outcome you want. - The files, feature, or behavior you care about. - What is out of scope. - What verification should count as done. For example: ```text Fix the broken provider error message in the config loader. Do not change the provider registry. Add a regression test and run only the config crate tests. ``` If you are not sure where the bug is, say that: ```text Investigate why `codewhale doctor` reports the wrong provider. Do not edit files yet. Return the likely cause, evidence, and a proposed patch plan. ``` CodeWhale works best when you let investigation and implementation happen in separate steps for unfamiliar code. For small, well-understood changes, a single implementation request is fine. Next: [MODES.md](MODES.md) explains when to use Plan, Agent, and YOLO. ## 4. Understanding the Interface The interactive TUI has a few stable regions: - Header: current session, active model, mode, and high-level status. - Transcript: the conversation, tool calls, command output summaries, and model responses. - Composer: where you type prompts, slash commands, and file mentions. - Sidebar: contextual panels for work state, tasks, agents, or related session information. - Status and footer areas: live activity, queued follow-ups, and short command hints. The footer status line is configurable. Run `/statusline` to choose which footer chips are visible, or set `[tui].status_items` in `config.toml` to control both selection and order. Supported keys currently include `mode`, `model`, `cost`, `balance` (DeepSeek / DeepSeekCN only), `status`, `coherence`, `agents`, `reasoning_replay`, `prefix_stability`, `cache`, `context_percent`, `git_branch`, `last_tool_elapsed` (placeholder), `rate_limit` (placeholder), and `tokens`. Omit `status_items` to keep the built-in default order; set it to `[]` to hide configurable chips. The transcript is the audit trail. When CodeWhale reads files, runs commands, or edits code, the action appears there. If a command fails, use the visible failure output as part of your next instruction instead of starting over. The composer accepts normal prompts and slash commands. Type `/` to discover available commands. Use file mentions when you want the model to focus on a specific file or directory instead of searching broadly. The sidebar is useful when a turn spans multiple steps. It can keep goals, agent state, and contextual information visible while the transcript continues to grow. Keyboard shortcuts vary by context, terminal, and platform. This guide avoids duplicating the full shortcut catalog so it does not drift from the TUI. Next: [KEYBINDINGS.md](KEYBINDINGS.md) is the complete shortcut reference. ## 5. Modes CodeWhale has three visible TUI modes: | Mode | Use it for | Default posture | | --- | --- | --- | | Plan | Exploration, design, and review before changes | Read-only investigation | | Agent | Normal multi-step coding work | Tool use with approval gates | | YOLO | Trusted repos where you want automatic execution | Auto-approval and trust | Switch modes from the TUI with the mode picker: ```text /mode ``` Or switch directly: ```text /mode plan /mode agent /mode yolo ``` Plan mode is the safest place to start in an unfamiliar repository. It is for inspection and decision-making, not file edits. Agent mode is the default for most contribution work. It lets CodeWhale read, run checks, and edit files while keeping risky actions behind approval gates. YOLO mode is for trusted workspaces where you intentionally want the model to act without stopping for approvals. Do not use it in a repository you do not trust. Modes are separate from model routing. `Tab` cycles visible modes when the composer is idle, while `/model auto` controls model and thinking selection for turns. You can also change approval behavior from `/config` by editing the approval mode. Use this only when you understand how it changes tool execution. Next: [MODES.md](MODES.md) has the full mode, approval, and trust-mode reference. ## 6. Slash Commands Slash commands are typed into the composer. They are useful when you want to change CodeWhale state directly instead of asking the model in natural language. Common commands for first-time users: | Command | Use | | --- | --- | | `/mode` | Open the mode picker or switch with `/mode agent` | | `/model` | Select a model or use `/model auto` | | `/models` | Fetch or list models from the active endpoint | | `/provider` | Pick the active API provider | | `/config` | Edit runtime and provider settings | | `/statusline` | Choose which footer status chips are visible | | `/settings` | Inspect persistent UI preferences | | `/compact` | Summarize long context to recover token budget | | `/review` | Ask for a structured review workflow | | `/memory` | Inspect or manage memory when enabled | | `/mcp` | Configure or inspect MCP server integration | Use `/provider` when you want to switch away from the default DeepSeek route. Provider IDs, environment variables, model defaults, and capability notes are kept in the provider registry document. Use `/model auto` when you want CodeWhale to choose the model and thinking level per turn. Use a fixed model when you need repeatable benchmarking or a strict cost profile. Use `/compact` when a session gets long and the model starts carrying too much history. Compaction trades raw transcript detail for a concise working summary. This guide intentionally does not list every command. The command surface changes more often than the onboarding flow, and the TUI command palette is the source of truth while you are inside a session. Next: [CONFIGURATION.md](CONFIGURATION.md) covers runtime settings and [MCP.md](MCP.md) covers Model Context Protocol integration. ## 7. Working with Tools CodeWhale tools are structured actions. Instead of only producing prose, the model can call tools to inspect and change the workspace. Examples of tool-backed work include: - Reading a file before explaining it. - Searching for call sites before proposing a refactor. - Running a focused test command. - Applying a small patch. - Opening a sub-agent for parallel investigation. Tool use is governed by mode, approvals, and sandbox policy. The exact behavior depends on the current mode and config, but the basic rule is simple: start in Plan for read-only exploration, use Agent for normal changes, and reserve YOLO for trusted automation. The workspace boundary matters. CodeWhale is expected to work in the directory you launched it from or the workspace you configured. Be explicit when a task should stay inside a repo: ```text Only inspect and edit files under this repository. Do not touch parent directories or global config. ``` When a command needs network, writes outside the workspace, or a risky shell operation, expect an approval prompt unless you have configured more permissive behavior. Good tool instructions are concrete: ```text Run the narrowest test that covers this parser change. If it fails, report the failure and stop before broadening the test scope. ``` Avoid asking for broad cleanup during a focused fix. Smaller tool scopes make the transcript easier to review and the final diff easier to merge. Next: [TOOL_SURFACE.md](TOOL_SURFACE.md) lists the tool surface and [SANDBOX.md](SANDBOX.md) explains sandbox behavior. ## 8. Sub-agents and Parallel Work Sub-agents are background child agents. The parent session gives a child a focused task, receives an agent id, and can continue working while the child runs. The main orchestration tools are: - `agent_open`: start a child with a task and role. - `agent_eval`: wait for and collect the child result. - `agent_close`: cancel a running child. You normally do not need to call these tools directly. Ask for parallel work in plain language: ```text Open one read-only explorer for the config crate and another for the TUI provider picker. Have both return file references and risks before we plan the fix. ``` Useful roles include: | Role | Good for | | --- | --- | | `general` | Multi-step tasks; the default when no role is specified | | `explore` | Read-only code mapping | | `plan` | Design and migration planning | | `review` | Bug-focused review of an existing change | | `implementer` | A tightly specified edit | | `verifier` | Running checks and reporting pass/fail evidence | Sub-agents are most useful when work can be separated cleanly. Do not use them for tiny edits, and do not ask multiple agents to write the same files at the same time. Next: [SUBAGENTS.md](SUBAGENTS.md) covers roles, lifecycle, concurrency, and output contracts. ## 9. Skills Skills are reusable instruction packs. A skill is usually a `SKILL.md` file that teaches CodeWhale how to perform a recurring workflow, use a tool family, or follow a project convention. Use skills when a task has a repeatable process: - Reviewing a specific kind of PR. - Working with a document or spreadsheet format. - Following a team release checklist. - Using a project-specific memory or wiki workflow. Inside the TUI, `/skill` activates a skill when one is available, and `/skills` lists installed skills. The command palette can also surface skill entries alongside normal slash commands. Good skills are narrow. They should tell the model what workflow to follow, what evidence to collect, and what to avoid. They should not hide credentials or replace normal repository documentation. If a repository has its own instructions, treat them as part of the active work. Read the local guidance before editing, and keep any contribution within the repository's conventions. Next: see the "Publishing Your Own Skill" section in [README.md](../README.md) and configuration details in [CONFIGURATION.md](CONFIGURATION.md). ## 10. Getting Help Start with doctor output: ```bash codewhale doctor ``` Use JSON when filing a detailed issue: ```bash codewhale doctor --json ``` For authentication problems, check which source is winning: saved config, keyring, environment, or an explicit launch flag. A stale `DEEPSEEK_API_KEY` environment variable can override what you expected to use. For provider problems, confirm the active provider and model: ```text /provider /model ``` For long or confusing sessions, use `/compact` to reduce context pressure, or start a fresh session in the same workspace and summarize what you need. When reporting an issue, include: - CodeWhale version. - Install method. - Operating system and terminal. - Provider and model. - The exact command or prompt. - Relevant doctor output. - Whether the problem happens in a fresh workspace. Do not paste API keys, private source code, or secrets into a public issue. Next: [OPERATIONS_RUNBOOK.md](OPERATIONS_RUNBOOK.md) has operational triage and recovery steps. ## FAQ ### Is CodeWhale only for DeepSeek? DeepSeek is the default and first-class route, but CodeWhale also supports other hosted and local OpenAI-compatible providers. Use `/provider` or `codewhale --provider ` to choose a provider. Keep the provider registry open when configuring a non-default route. ### Which mode should I use first? Use Plan for unfamiliar code, Agent for normal implementation, and YOLO only for trusted repositories where automatic execution is acceptable. ### Why does CodeWhale ask before running commands? Approvals are part of the safety model. Shell commands, paid tools, writes, and actions outside the expected workspace can have side effects. Approval prompts let you keep control while still letting the model do useful work. ### How do I run a Python file on macOS? Open Terminal in the folder that contains the file and run: ```bash python3 your_file.py ``` If macOS says `python3` is missing, install Python from [python.org](https://www.python.org/downloads/macos/) or with Homebrew: ```bash brew install python ``` Inside CodeWhale, ask the agent to inspect the file and run it with `python3 your_file.py`. If the script needs packages, install them in a virtual environment first: ```bash python3 -m venv .venv source .venv/bin/activate python3 -m pip install -r requirements.txt python3 your_file.py ``` ### Where is my config stored? New CodeWhale config uses `~/.codewhale/config.toml`. Legacy `~/.deepseek/config.toml` remains supported for compatibility. Project overlays can also affect behavior when a workspace config exists. ### How do I keep costs predictable? Use `/model auto` for routing, choose a fixed model when you need a strict profile, and compact long sessions. For larger tasks, ask CodeWhale to plan before implementing so you do not spend tokens on the wrong path. ### How do I continue previous work? CodeWhale saves sessions. Use the session picker or resume/continue CLI paths documented in the README and modes guide. For a risky experiment, fork the session before changing direction. The `/sessions` picker starts scoped to the current workspace so resumes stay attached to the project you opened. Press `a` in the picker to show sessions from every workspace, or run `codewhale sessions` to list all saved sessions with last-updated timestamps before resuming a specific id. ### What should I do when the model gets confused? Stop and restate the goal, constraints, and current evidence. If the transcript is long, use `/compact` or start a fresh session with a short handoff. If the problem is operational, run `codewhale doctor` and inspect the reported config and provider state. ### Should I put project rules in prompts or files? Use repository files for durable project rules and prompts for turn-specific intent. If a workflow repeats across projects, consider turning it into a skill. ### Can CodeWhale edit files outside the current repository? That depends on workspace boundaries, sandbox settings, trust mode, and approval policy. For contribution work, keep instructions scoped to the current repository unless you intentionally need something else. ### Where should I go after this guide? Read the focused reference for the thing you are changing. For most users, the next pages are install, configuration, providers, modes, keybindings, tools, and sub-agents. Next: [INSTALL.md](INSTALL.md), [CONFIGURATION.md](CONFIGURATION.md), [PROVIDERS.md](PROVIDERS.md), [MODES.md](MODES.md), and [TOOL_SURFACE.md](TOOL_SURFACE.md).