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

docs: add first-run user guide

Browse Source
This commit is contained in:
ningjingkun
2026-05-27 19:53:28 +08:00
committed by Hunter Bown
parent 02d1145add
commit dc6dcdfda2
2 changed files with 502 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1
View File
@@ -564,6 +564,7 @@ without recreating skills the user deliberately deleted.
| Doc | Topic |
|---|---|
| [GUIDE.md](docs/GUIDE.md) | First-run user guide |
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Codebase internals |
| [CONFIGURATION.md](docs/CONFIGURATION.md) | Full config reference |
| [PROVIDERS.md](docs/PROVIDERS.md) | Provider IDs, auth, model defaults, and capability metadata |
docs/GUIDE.md
+501
View File
@@ -0,0 +1,501 @@
# 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
# The tap/formula name is legacy; it installs codewhale and codewhale-tui.
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 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 |
| `/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 <id>` 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.
### 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.
### 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).