diff --git a/README.md b/README.md index 7629fc38..8550d983 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/docs/GUIDE.md b/docs/GUIDE.md new file mode 100644 index 00000000..60362570 --- /dev/null +++ b/docs/GUIDE.md @@ -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 ` 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).