| 1 | { |
| 2 | "chrome": { |
| 3 | "navDocs": "Docs", |
| 4 | "navStart": "Start", |
| 5 | "navInstall": "Install", |
| 6 | "navFaq": "FAQ", |
| 7 | "navCommunity": "Community", |
| 8 | "navContribute": "Contribute", |
| 9 | "navProduct": "Product", |
| 10 | "navModels": "Models", |
| 11 | "navPlugins": "Plugins", |
| 12 | "skipToContent": "Skip to main content", |
| 13 | "navPrimaryAria": "Primary", |
| 14 | "navHomeAria": "Codewhale home", |
| 15 | "installCta": "Install →", |
| 16 | "authSignIn": "Sign in", |
| 17 | "dateLocale": "en-US", |
| 18 | "menuOpen": "Open menu", |
| 19 | "menuClose": "Close menu", |
| 20 | "themeAuto": "auto", |
| 21 | "themeLight": "light", |
| 22 | "themeDark": "dark", |
| 23 | "themeAria": "Theme: {mode} (click to cycle)", |
| 24 | "themeTitle": "Theme · auto / light / dark", |
| 25 | "footerTagline": "Edit code, run tests, and review changes with the models you choose.", |
| 26 | "footerProduct": "Product", |
| 27 | "footerProject": "Project", |
| 28 | "footerDocs": "Docs", |
| 29 | "footerGuide": "Getting started", |
| 30 | "footerInstall": "Install", |
| 31 | "footerModels": "Models", |
| 32 | "footerRuntime": "Runtime", |
| 33 | "footerFaq": "FAQ", |
| 34 | "footerIssues": "Issues", |
| 35 | "footerContribute": "Contribute", |
| 36 | "footerLicense": "MIT license", |
| 37 | "footerTerms": "Terms", |
| 38 | "footerPrivacy": "Privacy", |
| 39 | "footerChangelog": "Changelog", |
| 40 | "footerCanonicalSource": "Canonical source: ", |
| 41 | "footerReleases": " · Releases: ", |
| 42 | "footerReleasesLink": "GitHub Releases", |
| 43 | "footerSecurity": "Security", |
| 44 | "switcherLabel": "Language", |
| 45 | "switcherSwitchTo": "Switch to {label}", |
| 46 | "partialBadge": "(partial)" |
| 47 | }, |
| 48 | "home": { |
| 49 | "metaTitle": "Codewhale: the open-source coding agent for any model", |
| 50 | "metaDescription": "Codewhale is an open-source coding agent for your terminal. It reads your project, edits files, and runs your tests with the hosted or local model you choose.", |
| 51 | "heroTitle": "The open-source coding agent for any model", |
| 52 | "heroIntro": "{brand} reads your project, edits files, and runs your tests from your terminal. Connect a hosted or local model, and choose which actions need your approval.", |
| 53 | "getCodewhale": "Install Codewhale", |
| 54 | "heroInstallAria": "Install command", |
| 55 | "exploreProduct": "See how it works", |
| 56 | "shotPreview": "Terminal preview", |
| 57 | "shotBuild": "v{version} pre-release build", |
| 58 | "screenshotAlt": "Codewhale v{version} pre-release build: whale mark, new session, message composer, Ask permissions, Work mode and model status. Rendered from an isolated terminal capture.", |
| 59 | "latestRelease": "Latest release {tag}", |
| 60 | "releaseUnavailable": "Release status unavailable", |
| 61 | "currentSource": "Source", |
| 62 | "sourceCandidate": "Unreleased", |
| 63 | "publishedRelease": "released", |
| 64 | "figcaptionSourceCandidate": "unreleased", |
| 65 | "chapterTerminal": "Your terminal", |
| 66 | "chapterTerminalTitle": "Follow each edit and command as it runs", |
| 67 | "gainHeading": "Delegate the task and keep control", |
| 68 | "gainLede": "Ask for a result: fix a bug, explain a module, or automate a task you repeat. Start with one agent, and add more agents when the job grows.", |
| 69 | "gain": [ |
| 70 | [ |
| 71 | "Change code and check it", |
| 72 | "The agent inspects your project, edits files, and runs your tests. Follow each edit and command result as it works." |
| 73 | ], |
| 74 | [ |
| 75 | "Automate repeated work", |
| 76 | "Run codewhale exec from scripts and CI. Use a Fleet to divide a larger job among several agents." |
| 77 | ], |
| 78 | [ |
| 79 | "Stay in control", |
| 80 | "Set permissions before work starts, answer approval requests, and stop a task at any point. Run /receipts to list every file, command, and approval in a session." |
| 81 | ] |
| 82 | ], |
| 83 | "chapterModels": "Your models", |
| 84 | "modelsHeading": "Choose a model for each task", |
| 85 | "modelsBody": "Choose a built-in provider, any OpenAI-compatible endpoint, or a local model for each session. Your model connection stays separate from any Codewhale account.", |
| 86 | "modelsFacts": [ |
| 87 | [ |
| 88 | "Hosted", |
| 89 | "Your own API key, saved with codewhale auth set --provider <id>" |
| 90 | ], |
| 91 | [ |
| 92 | "Gateway", |
| 93 | "One endpoint for many models; you still choose the provider" |
| 94 | ], |
| 95 | [ |
| 96 | "Local", |
| 97 | "vLLM, SGLang, or Ollama on localhost, usually with no key" |
| 98 | ] |
| 99 | ], |
| 100 | "modelsLink": "Browse models and providers", |
| 101 | "startHeading": "Install, connect a model, run a task", |
| 102 | "startLede": "Run your first task in three steps from your project folder. Add a Fleet later if the work needs several agents.", |
| 103 | "startGuideLink": "Follow the getting-started guide", |
| 104 | "startVocabularyLink": "Look up a term", |
| 105 | "chapterAvailability": "Where it runs", |
| 106 | "availabilityHeading": "Use it in your terminal today", |
| 107 | "availabilityLede": "Use the terminal, the local browser client, or the community CodeWhale GUI now. The desktop app and the rebuilt hosted web app are in development and share the same session model.", |
| 108 | "availability": [ |
| 109 | [ |
| 110 | "Terminal and local browser", |
| 111 | "Released", |
| 112 | "Install on Linux, macOS, or Windows, then run codewhale, or codewhale web for the local browser client. npm and Cargo also work; Android on Termux is a preview." |
| 113 | ], |
| 114 | [ |
| 115 | "CodeWhale GUI (VS Code)", |
| 116 | "Available", |
| 117 | "A separate, community-maintained project: chat, threads, and file changes in a VS Code sidebar over the same Codewhale Runtime. Install it from the VS Code Marketplace.", |
| 118 | "https://marketplace.visualstudio.com/items?itemName=HengQuWorld.brotherwhale-vscode" |
| 119 | ], |
| 120 | [ |
| 121 | "Hosted web app", |
| 122 | "Development preview", |
| 123 | "Being rebuilt to match the desktop app. Today you can sign in, then type /rc in a running terminal session to continue it on the web; hosted task execution is still being qualified." |
| 124 | ], |
| 125 | [ |
| 126 | "Desktop", |
| 127 | "Development build", |
| 128 | "The native app becoming the main Codewhale client: folders, conversations, and model connections in one window. No public download yet." |
| 129 | ], |
| 130 | [ |
| 131 | "Cloud computers", |
| 132 | "In development", |
| 133 | "Hosted computers that run your tasks." |
| 134 | ] |
| 135 | ], |
| 136 | "availabilityNote": "The terminal, local browser, and GUI need no Codewhale account. Hosted web and desktop use an account, which does not replace your model connection; your provider bills usage on your own key.", |
| 137 | "accountLink": "Create an account", |
| 138 | "surfacesHeading": "Extend what the agent can reach", |
| 139 | "surfaces": [ |
| 140 | [ |
| 141 | "Files and commands", |
| 142 | "Read the project, edit files, run tests, and inspect output within the permissions you set." |
| 143 | ], |
| 144 | [ |
| 145 | "Plugins and MCP", |
| 146 | "Connect more tools and services. Each plugin stays off until you review and enable it." |
| 147 | ], |
| 148 | [ |
| 149 | "Computer Use · preview", |
| 150 | "A plugin that lets the agent see and operate other apps. You enable it and grant the system permissions it asks for." |
| 151 | ], |
| 152 | [ |
| 153 | "Saved sessions", |
| 154 | "Keep the conversation and tool results together, and resume instead of starting over. The local browser opens the same session on your computer." |
| 155 | ], |
| 156 | [ |
| 157 | "Fleet", |
| 158 | "Assign parts of a task to agents with different models and roles, then follow their progress." |
| 159 | ] |
| 160 | ], |
| 161 | "runtimeLink": "See all integrations", |
| 162 | "installBandHeading": "Install on macOS or Linux", |
| 163 | "copy": "Copy", |
| 164 | "copied": "Copied ✓", |
| 165 | "binaries": "Binaries", |
| 166 | "chinaMirrors": "China mirrors", |
| 167 | "installGuideLink": "Read the install guide", |
| 168 | "communityHeading": "Build Codewhale with us", |
| 169 | "communityBody": "Report a bug, propose a feature, or send your first pull request on GitHub. Small, tested fixes are welcome.", |
| 170 | "communityLinksAria": "Community links", |
| 171 | "contribute": "Send a pull request" |
| 172 | }, |
| 173 | "docs-guide": { |
| 174 | "metaTitle": "Start your first task · Codewhale Docs", |
| 175 | "metaDescription": "Install Codewhale, connect a model, and give it a task in your project. Add a Fleet later if you want several models and roles.", |
| 176 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 177 | "overviewTitle": "Start your first task", |
| 178 | "overviewLead": "Four steps take you from nothing installed to a finished first task. Each step links to the page with the details; the Fleet step is optional.", |
| 179 | "sessionTitle": "Watch a real session", |
| 180 | "sessionLead": "Follow a task from the first request to the finished result.", |
| 181 | "nextTitle": "Next", |
| 182 | "sourceNote": "Source documents: docs/GUIDE.md, docs/INSTALL.md, docs/KEYBINDINGS.md · Update docs-map.ts when changing." |
| 183 | }, |
| 184 | "docs-shell": { |
| 185 | "metaTitle": "Docs · Codewhale", |
| 186 | "metaDescription": "Install Codewhale, connect a provider, and get work done: modes and approvals, reviewing changes, workflows, sub-agents, MCP tools, hooks, the Runtime API, and troubleshooting.", |
| 187 | "portalMark": "Codewhale documentation", |
| 188 | "heroTitle": "Get something done with Codewhale.", |
| 189 | "heroLead": "Start from what you want to do. Each page says what you need, shows commands you can run today, and points to the next step.", |
| 190 | "installCta": "Install Codewhale", |
| 191 | "releaseLabel": "Release", |
| 192 | "releasePublished": "Latest release {tag} · {date}", |
| 193 | "releaseCandidate": "These pages describe the {version} source candidate, which is not published yet.", |
| 194 | "releaseMatches": "These pages describe {tag}, the published release.", |
| 195 | "releaseChangelog": "Changelog →", |
| 196 | "searchLabel": "Search the documentation", |
| 197 | "searchPlaceholder": "Search by task or topic… (press / to focus)", |
| 198 | "searchClear": "Clear", |
| 199 | "searchMatches": "{matched} of {total} entries match “{query}”", |
| 200 | "searchNoMatches": "Nothing matches “{query}”", |
| 201 | "tasksHeading": "By task", |
| 202 | "tasksLead": "Start from what you are trying to do.", |
| 203 | "topicsHeading": "By topic", |
| 204 | "webGuideTag": "Web guide", |
| 205 | "sourceDocTag": "Source doc", |
| 206 | "sourceDetails": "Details", |
| 207 | "emptyTitle": "No matching entry", |
| 208 | "emptyBody": "Try a different word — searches match English and Chinese — or browse the complete docs directory on GitHub.", |
| 209 | "emptyCta": "GitHub docs directory ↗", |
| 210 | "indexNote": "Web guides open on codewhale.net. Source docs open the full reference in the GitHub repository.", |
| 211 | "sidebarHeading": "Documentation", |
| 212 | "sidebarAria": "Documentation index", |
| 213 | "breadcrumbAria": "Breadcrumb", |
| 214 | "breadcrumbHome": "Home", |
| 215 | "breadcrumbDocs": "Docs", |
| 216 | "helpTitle": "Need more than this page?", |
| 217 | "helpLead": "Every guide is checked against a document in the repository. If something is wrong or missing, say so where the maintainer will see it.", |
| 218 | "helpSource": "Source: {name}", |
| 219 | "helpTroubleshooting": "Fix a problem", |
| 220 | "helpFaq": "FAQ", |
| 221 | "helpDiscord": "Ask on Discord ↗", |
| 222 | "helpIssue": "Report a docs problem ↗", |
| 223 | "nextHeading": "Next", |
| 224 | "noteLabel": "Note:", |
| 225 | "onThisPage": "On this page", |
| 226 | "mediaPendingNote": "There is no recording yet. When there is, it goes here with captions, a transcript, and an optional GIF download.", |
| 227 | "mediaPlanLink": "Recording plan and acceptance checklist ↗", |
| 228 | "mediaGifFallback": "GIF fallback download (no-video environments)", |
| 229 | "mediaTranscript": "Transcript ↗" |
| 230 | }, |
| 231 | "docs-hooks": { |
| 232 | "metaTitle": "Run commands on events · Codewhale Docs", |
| 233 | "metaDescription": "Run your own scripts when a session starts, before a tool call, when a turn ends, or when Codewhale is waiting for you — to add context, enforce a rule, or get notified.", |
| 234 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 235 | "title": "Run commands on events", |
| 236 | "lede": "Hooks run a command of yours at set moments in a Codewhale session. Use them to block a risky command, add context to a message, log what happened, or get told when Codewhale is waiting for you.", |
| 237 | "sections": [ |
| 238 | { |
| 239 | "id": "first-hook", |
| 240 | "title": "Add your first hook", |
| 241 | "blocks": [ |
| 242 | { |
| 243 | "p": "Hooks live in `~/.codewhale/config.toml`. This one prints a line whenever a session starts:" |
| 244 | }, |
| 245 | { |
| 246 | "code": "[hooks]\nenabled = true\n\n[[hooks.hooks]]\nname = \"announce\"\nevent = \"session_start\"\ncommand = \"echo 'Codewhale session started'\"", |
| 247 | "lang": "config.toml" |
| 248 | }, |
| 249 | { |
| 250 | "p": "Start a session, then run `/hooks` to see every configured hook, whether hooks are on, and any entry that was rejected. `/hooks events` lists the event names." |
| 251 | } |
| 252 | ] |
| 253 | }, |
| 254 | { |
| 255 | "id": "gate", |
| 256 | "title": "Block a command before it runs", |
| 257 | "blocks": [ |
| 258 | { |
| 259 | "p": "A `tool_call_before` hook sees each tool call before it executes and can allow it, deny it, or force an approval prompt. This one refuses force-pushes. Save the script and make it executable:" |
| 260 | }, |
| 261 | { |
| 262 | "code": "#!/bin/sh\n# ~/.codewhale/hooks/no-force-push.sh\ncase \"$DEEPSEEK_TOOL_ARGS\" in\n *\"push --force\"*|*\"push -f\"*)\n echo '{\"decision\": \"deny\", \"reason\": \"Force-push is blocked by a hook.\"}' ;;\nesac\nexit 0", |
| 263 | "lang": "no-force-push.sh" |
| 264 | }, |
| 265 | { |
| 266 | "code": "[[hooks.hooks]]\nname = \"no-force-push\"\nevent = \"tool_call_before\"\ncommand = \"~/.codewhale/hooks/no-force-push.sh\"\ncondition = { type = \"tool_name\", name = \"bash\" }", |
| 267 | "lang": "config.toml" |
| 268 | }, |
| 269 | { |
| 270 | "p": "The hook reads the call from environment variables and answers with JSON on standard output: `allow`, `deny`, or `ask`, plus an optional `reason`, a rewritten input (`updatedInput`), or extra context for the model (`additionalContext`). Exit code 2 always denies. When several hooks answer, deny beats ask, and ask beats allow." |
| 271 | }, |
| 272 | { |
| 273 | "note": "`ask` forces a prompt in Ask and Auto-Review. Full Access never shows approval prompts, so there `ask` does not add one." |
| 274 | } |
| 275 | ] |
| 276 | }, |
| 277 | { |
| 278 | "id": "events", |
| 279 | "title": "Choose the moment", |
| 280 | "blocks": [ |
| 281 | { |
| 282 | "p": "Three events can change what happens next. The rest only observe; their output is ignored and a failure is a warning." |
| 283 | }, |
| 284 | { |
| 285 | "rows": [ |
| 286 | [ |
| 287 | "message_submit", |
| 288 | "Before your message reaches the model. Can replace the text or block it." |
| 289 | ], |
| 290 | [ |
| 291 | "tool_call_before", |
| 292 | "Before each tool call. Can allow, deny, ask, rewrite the input, or add context." |
| 293 | ], |
| 294 | [ |
| 295 | "shell_env", |
| 296 | "Before each shell command. Can add environment variables." |
| 297 | ], |
| 298 | [ |
| 299 | "session_start / session_end", |
| 300 | "When a session opens or closes cleanly." |
| 301 | ], |
| 302 | [ |
| 303 | "turn_end", |
| 304 | "After a turn finishes, with its status, duration, and token usage." |
| 305 | ], |
| 306 | [ |
| 307 | "tool_call_after", |
| 308 | "After each tool result, with its exit code when there is one." |
| 309 | ], |
| 310 | [ |
| 311 | "waiting_for_user", |
| 312 | "When Codewhale starts waiting for an approval, an answer, or a paused goal." |
| 313 | ], |
| 314 | [ |
| 315 | "session_idle / session_busy", |
| 316 | "When the session settles or starts working again." |
| 317 | ], |
| 318 | [ |
| 319 | "session_error / on_error", |
| 320 | "When a turn fails for good, or on any error or failed tool." |
| 321 | ], |
| 322 | [ |
| 323 | "mode_change", |
| 324 | "When you switch between Plan, Work, and Operate." |
| 325 | ], |
| 326 | [ |
| 327 | "subagent_spawn / subagent_complete", |
| 328 | "When a sub-agent starts or finishes." |
| 329 | ] |
| 330 | ], |
| 331 | "codeTerms": true |
| 332 | }, |
| 333 | { |
| 334 | "p": "A `condition` narrows when a hook fires: by tool name (with `*` globs), tool category, mode, or exit code, and combinations with `all` and `any`. A condition that can never match its event is rejected when the config loads, so a gate you think is armed never sits silently inert." |
| 335 | } |
| 336 | ] |
| 337 | }, |
| 338 | { |
| 339 | "id": "options", |
| 340 | "title": "Set timeouts and failure behavior", |
| 341 | "blocks": [ |
| 342 | { |
| 343 | "rows": [ |
| 344 | [ |
| 345 | "timeout_secs", |
| 346 | "How long the hook may run. Default 30." |
| 347 | ], |
| 348 | [ |
| 349 | "continue_on_error", |
| 350 | "`true` (default): a failing hook only warns. `false`: the failure blocks." |
| 351 | ], |
| 352 | [ |
| 353 | "background", |
| 354 | "`true` runs the hook as an observer only; it cannot block or rewrite." |
| 355 | ], |
| 356 | [ |
| 357 | "working_dir", |
| 358 | "Under `[hooks]`: where hooks run. Default: the session's workspace." |
| 359 | ] |
| 360 | ], |
| 361 | "codeTerms": true |
| 362 | }, |
| 363 | { |
| 364 | "note": "`[hooks] default_timeout_secs` replaces every hook's own `timeout_secs`, not just the missing ones. Leave it unset if you want per-hook timeouts." |
| 365 | } |
| 366 | ] |
| 367 | }, |
| 368 | { |
| 369 | "id": "project", |
| 370 | "title": "Use hooks a repository ships", |
| 371 | "blocks": [ |
| 372 | { |
| 373 | "p": "A repository can include hooks in `.codewhale/hooks.toml`. Because they run commands on your machine, they load only after you trust the workspace and approve that exact file:" |
| 374 | }, |
| 375 | { |
| 376 | "code": "/hooks review\n/hooks approve <digest>\n/hooks revoke", |
| 377 | "lang": "Codewhale" |
| 378 | }, |
| 379 | { |
| 380 | "p": "`/hooks review` shows the commands and a digest of the file; approving that digest enables those exact bytes from the next session. Any change to the file needs a new approval. Review the scripts the commands call, too." |
| 381 | } |
| 382 | ] |
| 383 | }, |
| 384 | { |
| 385 | "id": "headless", |
| 386 | "title": "Use hooks in scripts and CI", |
| 387 | "blocks": [ |
| 388 | { |
| 389 | "p": "Hooks run in the interactive session. `codewhale exec` fires none by default; add `--hooks` to fire `tool_call_before` and `shell_env`. With no one to answer, an `ask` becomes a deny." |
| 390 | }, |
| 391 | { |
| 392 | "code": "codewhale exec --auto --hooks \"run the test suite and fix the first failure\"", |
| 393 | "lang": "Terminal" |
| 394 | } |
| 395 | ] |
| 396 | } |
| 397 | ], |
| 398 | "next": [ |
| 399 | { |
| 400 | "href": "/docs/modes", |
| 401 | "label": "Set modes and approvals", |
| 402 | "note": "How hook decisions combine with Ask, Auto-Review, and Full Access." |
| 403 | }, |
| 404 | { |
| 405 | "href": "/docs/mcp", |
| 406 | "label": "Connect tools with MCP", |
| 407 | "note": "Gate MCP tools with the same `tool_call_before` hooks." |
| 408 | }, |
| 409 | { |
| 410 | "href": "/docs/configuration", |
| 411 | "label": "Change settings", |
| 412 | "note": "Where `config.toml` lives and what a project may override." |
| 413 | } |
| 414 | ], |
| 415 | "sourceNote": "Source documents: docs/HOOKS.md (authoritative), docs/CONFIGURATION.md · Update docs-map.ts when changing." |
| 416 | }, |
| 417 | "docs-troubleshooting": { |
| 418 | "metaTitle": "Fix a problem · Codewhale Docs", |
| 419 | "metaDescription": "Diagnose Codewhale in one command, then fix the common problems: command not found, no reply, a rejected key, network errors, a stuck turn, a session that will not resume, and MCP servers.", |
| 420 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 421 | "title": "Fix a problem", |
| 422 | "lede": "Start with one diagnostic command, then find your symptom below. Each fix names the exact message you will see.", |
| 423 | "sections": [ |
| 424 | { |
| 425 | "id": "diagnose", |
| 426 | "title": "Run the diagnostics", |
| 427 | "blocks": [ |
| 428 | { |
| 429 | "code": "codewhale --version\ncodewhale doctor\ncodewhale doctor --probe-api # one real test call to your provider\ncodewhale auth status --provider deepseek # which key is in use", |
| 430 | "lang": "Terminal" |
| 431 | }, |
| 432 | { |
| 433 | "p": "`codewhale doctor --json` produces a diagnostics bundle without secrets, ready to attach to an issue. Plain `doctor` does not tell you which key is active and exits successfully even with no key; use `auth status` for that." |
| 434 | } |
| 435 | ] |
| 436 | }, |
| 437 | { |
| 438 | "id": "install", |
| 439 | "title": "Install and update", |
| 440 | "blocks": [ |
| 441 | { |
| 442 | "rows": [ |
| 443 | [ |
| 444 | "`codewhale: command not found`", |
| 445 | "`~/.local/bin` is not on your PATH in this terminal. Add `export PATH=\"$HOME/.local/bin:$PATH\"` to your shell profile and open a new terminal." |
| 446 | ], |
| 447 | [ |
| 448 | "`npm error code EACCES`", |
| 449 | "Your Node install is owned by the system. Do not use sudo: point npm at a folder you own with `npm config set prefix \"$HOME/.npm-global\"`, add its `bin` to your PATH, and install again." |
| 450 | ], |
| 451 | [ |
| 452 | "`refusing to replace existing ~/.local/bin/codewhale`", |
| 453 | "A different version is already there. Run `codewhale update`, or remove the old binaries first." |
| 454 | ], |
| 455 | [ |
| 456 | "`checksum mismatch`", |
| 457 | "The download was corrupted or altered, and nothing was installed. Try again; if it repeats, do not use a mirror." |
| 458 | ], |
| 459 | [ |
| 460 | "`The package-managed executable was not changed.`", |
| 461 | "You installed with npm, Cargo, or Homebrew. Update with that tool, for example `npm install -g codewhale`." |
| 462 | ] |
| 463 | ] |
| 464 | } |
| 465 | ] |
| 466 | }, |
| 467 | { |
| 468 | "id": "model", |
| 469 | "title": "No reply, or the key is rejected", |
| 470 | "blocks": [ |
| 471 | { |
| 472 | "rows": [ |
| 473 | [ |
| 474 | "Your message appears but nothing answers", |
| 475 | "No key is configured, and v0.10.0 does not warn you. Press F3, choose your provider, and paste the key." |
| 476 | ], |
| 477 | [ |
| 478 | "`API key not found`", |
| 479 | "No key anywhere. Save one with `codewhale auth set --provider <name>`." |
| 480 | ], |
| 481 | [ |
| 482 | "`Authentication Fails … is invalid`", |
| 483 | "The key is wrong or revoked. Run `auth status` to see which source is used — a saved key beats an environment variable — then save the right key or `codewhale auth clear --provider <name>`." |
| 484 | ], |
| 485 | [ |
| 486 | "`Network error: SSE stream request failed …`", |
| 487 | "Usually no connection to the provider. Check with `curl -sI https://api.deepseek.com` (a 401 means it is reachable). Behind a proxy, export `HTTPS_PROXY`. On Windows or strict proxies, try `CODEWHALE_FORCE_HTTP1=1`." |
| 488 | ] |
| 489 | ] |
| 490 | } |
| 491 | ] |
| 492 | }, |
| 493 | { |
| 494 | "id": "turn", |
| 495 | "title": "A turn is stuck", |
| 496 | "blocks": [ |
| 497 | { |
| 498 | "list": [ |
| 499 | "Press Esc to cancel the turn. Esc also closes menus first, so press it again if a menu was open.", |
| 500 | "If a long shell command is holding the turn, press Ctrl-B to move it into the background. The turn continues, and `/jobs` shows the command.", |
| 501 | "`/retry` sends the last request again." |
| 502 | ] |
| 503 | }, |
| 504 | { |
| 505 | "p": "For a detailed record, start Codewhale with `RUST_LOG=codewhale_tui=debug` (or `RUST_LOG=codewhale_tui::client=debug` for connection retries). Logs are written to `~/.codewhale/logs/`." |
| 506 | } |
| 507 | ] |
| 508 | }, |
| 509 | { |
| 510 | "id": "sessions", |
| 511 | "title": "Resume a session", |
| 512 | "blocks": [ |
| 513 | { |
| 514 | "code": "codewhale sessions # list saved sessions\ncodewhale resume <id> # an id or a unique prefix\ncodewhale -c # the latest session in this folder", |
| 515 | "lang": "Terminal" |
| 516 | }, |
| 517 | { |
| 518 | "p": "Inside Codewhale, Ctrl-R opens the session picker. `No saved sessions found for workspace` after `codewhale exec --continue` means the earlier run was a plain `exec`, which is not saved; use `--output-format stream-json` for runs you want to continue." |
| 519 | }, |
| 520 | { |
| 521 | "p": "Messages you send while offline wait in a queue, saved with the session. `/queue list` shows them. When the connection is back, open one with `/queue edit <n>` and press Enter to send it." |
| 522 | } |
| 523 | ] |
| 524 | }, |
| 525 | { |
| 526 | "id": "mcp", |
| 527 | "title": "MCP tools are missing", |
| 528 | "blocks": [ |
| 529 | { |
| 530 | "list": [ |
| 531 | "After changing `mcp.json` or a server's credentials, run `/mcp reload`. `/mcp validate` only refreshes what you see.", |
| 532 | "Run the server's command yourself in a shell to confirm it starts.", |
| 533 | "If the config file is missing or broken, `codewhale mcp init --force` writes a fresh one." |
| 534 | ] |
| 535 | } |
| 536 | ] |
| 537 | }, |
| 538 | { |
| 539 | "id": "docker", |
| 540 | "title": "Run in Docker", |
| 541 | "blocks": [ |
| 542 | { |
| 543 | "code": "docker volume create codewhale-home\ndocker run --rm -it \\\n -e DEEPSEEK_API_KEY=\"$DEEPSEEK_API_KEY\" \\\n -v codewhale-home:/home/codewhale/.codewhale \\\n -v \"$PWD:/workspace\" -w /workspace \\\n ghcr.io/codewhale-hq/codewhale:latest", |
| 544 | "lang": "Terminal" |
| 545 | }, |
| 546 | { |
| 547 | "p": "The image runs as a non-root user and keeps your settings and sessions in the named volume. Pin a release tag instead of `latest` for repeatable setups, use one volume per project, and never bake keys into an image." |
| 548 | } |
| 549 | ] |
| 550 | } |
| 551 | ], |
| 552 | "next": [ |
| 553 | { |
| 554 | "href": "/docs/auth", |
| 555 | "label": "Connect a provider", |
| 556 | "note": "Save a key, check which one is used, or switch to a local model." |
| 557 | }, |
| 558 | { |
| 559 | "href": "/install", |
| 560 | "label": "Install Codewhale", |
| 561 | "note": "Every install method, with the output each step should print." |
| 562 | }, |
| 563 | { |
| 564 | "href": "/docs/review", |
| 565 | "label": "Review what changed", |
| 566 | "note": "Roll files back to the snapshot before a turn went wrong." |
| 567 | } |
| 568 | ], |
| 569 | "sourceNote": "Source documents: docs/INSTALL.md §13, docs/OPERATIONS_RUNBOOK.md, docs/DOCKER.md · Update docs-map.ts when changing." |
| 570 | }, |
| 571 | "docs-configuration": { |
| 572 | "metaTitle": "Change settings · Codewhale Docs", |
| 573 | "metaDescription": "Find Codewhale's config file, change a setting from the session or the shell, try one for a single run, and see what a repository is allowed to override.", |
| 574 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 575 | "title": "Change settings", |
| 576 | "lede": "Most settings can be changed without opening a file: from the session with `/config`, or from the shell with `codewhale config`. This page shows where settings live, how to change them, and what a repository can and cannot change for you.", |
| 577 | "sections": [ |
| 578 | { |
| 579 | "id": "file", |
| 580 | "title": "Find the config file", |
| 581 | "blocks": [ |
| 582 | { |
| 583 | "p": "Your settings live in `~/.codewhale/config.toml`. Print the exact path, or open the file in your editor:" |
| 584 | }, |
| 585 | { |
| 586 | "code": "codewhale config path\ncodewhale config edit", |
| 587 | "lang": "Terminal" |
| 588 | }, |
| 589 | { |
| 590 | "p": "To use a different file, pass `--config <path>` or set `CODEWHALE_CONFIG_PATH`; the flag wins when both are set. Codewhale was once called DeepSeek-TUI: if only an old `~/.deepseek/` folder exists, it is still read, and new settings are always written to `~/.codewhale/`." |
| 591 | } |
| 592 | ] |
| 593 | }, |
| 594 | { |
| 595 | "id": "change", |
| 596 | "title": "Change a setting", |
| 597 | "blocks": [ |
| 598 | { |
| 599 | "p": "Inside a session, `/config` opens the settings editor and `/settings` opens the settings screen. `/config audit` lists which settings can change in this session, which can be saved, and which only take effect after a restart — check it before editing by hand." |
| 600 | }, |
| 601 | { |
| 602 | "p": "From the shell:" |
| 603 | }, |
| 604 | { |
| 605 | "code": "codewhale config get tools\ncodewhale config set telemetry false\ncodewhale config unset telemetry\ncodewhale config dump # the settings in effect, secrets redacted\ncodewhale config doctor # unknown keys, empty secrets, malformed URLs", |
| 606 | "lang": "Terminal" |
| 607 | }, |
| 608 | { |
| 609 | "p": "`config set` handles its named keys; for anything else it tells you which TOML table to edit instead of guessing." |
| 610 | } |
| 611 | ] |
| 612 | }, |
| 613 | { |
| 614 | "id": "one-run", |
| 615 | "title": "Try a setting for one run", |
| 616 | "blocks": [ |
| 617 | { |
| 618 | "p": "`--set KEY=VALUE` changes a setting for one launch and saves nothing. It accepts `provider`, `model`, `verbosity`, `approval_policy`, `sandbox_mode`, and `telemetry`, and can be repeated." |
| 619 | }, |
| 620 | { |
| 621 | "code": "codewhale --set model=deepseek-v4-pro --set sandbox_mode=read-only", |
| 622 | "lang": "Terminal" |
| 623 | } |
| 624 | ] |
| 625 | }, |
| 626 | { |
| 627 | "id": "project", |
| 628 | "title": "Share settings with a repository", |
| 629 | "blocks": [ |
| 630 | { |
| 631 | "p": "A repository can include `.codewhale/config.toml` to suggest settings to everyone who works in it. Only a few keys are honored, and safety settings can only get stricter:" |
| 632 | }, |
| 633 | { |
| 634 | "rows": [ |
| 635 | [ |
| 636 | "model", |
| 637 | "The default model for this repository." |
| 638 | ], |
| 639 | [ |
| 640 | "reasoning_effort", |
| 641 | "For example `\"high\"` for a complex codebase." |
| 642 | ], |
| 643 | [ |
| 644 | "approval_policy, sandbox_mode", |
| 645 | "Only values stricter than yours." |
| 646 | ], |
| 647 | [ |
| 648 | "allow_shell", |
| 649 | "`false` turns shell commands off; `true` is ignored." |
| 650 | ], |
| 651 | [ |
| 652 | "max_subagents", |
| 653 | "Fewer parallel sub-agents, from 1 to 128." |
| 654 | ], |
| 655 | [ |
| 656 | "notes_path", |
| 657 | "Keep notes in the repository." |
| 658 | ] |
| 659 | ], |
| 660 | "codeTerms": true |
| 661 | }, |
| 662 | { |
| 663 | "p": "Keys, endpoints, provider choice, MCP servers, hooks, skills, and extra instruction files always come from your own config, so a cloned repository cannot point Codewhale at its own server or files. Start with `--no-project-config` to ignore a repository's file for one launch." |
| 664 | }, |
| 665 | { |
| 666 | "p": "Project instructions — how an agent should work in this repository — belong in `AGENTS.md` instead. Run `/init` to create one." |
| 667 | } |
| 668 | ] |
| 669 | } |
| 670 | ], |
| 671 | "next": [ |
| 672 | { |
| 673 | "href": "/docs/auth", |
| 674 | "label": "Connect a provider", |
| 675 | "note": "Save a key and see which one Codewhale is using." |
| 676 | }, |
| 677 | { |
| 678 | "href": "/docs/modes", |
| 679 | "label": "Set modes and approvals", |
| 680 | "note": "The settings most people change first." |
| 681 | }, |
| 682 | { |
| 683 | "href": "/docs/hooks", |
| 684 | "label": "Run commands on events", |
| 685 | "note": "Add your own scripts to the `[hooks]` table." |
| 686 | } |
| 687 | ], |
| 688 | "sourceNote": "Source documents: docs/CONFIGURATION.md, docs/LEGACY_PATHS.md · Update docs-map.ts when changing." |
| 689 | }, |
| 690 | "docs-fleet": { |
| 691 | "metaTitle": "Run a workflow · Codewhale Docs", |
| 692 | "metaDescription": "Save roles and models in a Fleet, write a repeatable Workflow, run it as a Lane you can watch and stop, and run batches of tasks with durable workers.", |
| 693 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 694 | "title": "Run a workflow", |
| 695 | "lede": "For most multi-step work you only need to ask: in Operate, Codewhale plans the steps and runs independent ones in parallel. Write a Workflow when you want the same ordered plan every time — phases, parallel branches, and a summary — with a record of each run.", |
| 696 | "sections": [ |
| 697 | { |
| 698 | "id": "fleet", |
| 699 | "title": "Save roles in a Fleet", |
| 700 | "blocks": [ |
| 701 | { |
| 702 | "p": "Your Fleet is the list of roles Codewhale can hand work to, and the model each role uses. Set it up once inside a session:" |
| 703 | }, |
| 704 | { |
| 705 | "code": "/fleet setup\n/fleet\n/fleet saved", |
| 706 | "lang": "Codewhale" |
| 707 | }, |
| 708 | { |
| 709 | "p": "`/fleet setup` walks you through a role, its model (or “use the session's model”), and where to save it: this project, or your personal profile for every repository. You review the exact file before it is written. `/fleet` shows the members of the selected Fleet, and `/fleet saved` switches between named Fleets." |
| 710 | }, |
| 711 | { |
| 712 | "p": "A Fleet only chooses who does the work. What a worker may read, write, or run still comes from your workspace trust, [approval setting](/docs/modes), and sandbox." |
| 713 | } |
| 714 | ] |
| 715 | }, |
| 716 | { |
| 717 | "id": "write", |
| 718 | "title": "Write a workflow", |
| 719 | "blocks": [ |
| 720 | { |
| 721 | "p": "A Workflow is a JavaScript file in your repository's `workflows/` folder. It describes steps; it does not do the work itself. This one reviews two areas in parallel, then combines the findings. Save it as `workflows/docs_readiness.workflow.js`:" |
| 722 | }, |
| 723 | { |
| 724 | "code": "export default workflow({\n \"id\": \"docs-readiness\",\n \"goal\": \"Review the docs and code for gaps, then summarize the next edit\",\n \"nodes\": [\n {\n \"branch\": {\n \"id\": \"parallel-review\",\n \"parallel\": true,\n \"children\": [\n { \"agent\": { \"id\": \"code-review\", \"prompt\": \"Inspect src/ for undocumented behavior.\",\n \"agent_type\": \"review\", \"mode\": \"read_only\", \"file_scope\": [\"src\"] } },\n { \"agent\": { \"id\": \"docs-review\", \"prompt\": \"Inspect docs/ for stale or missing steps.\",\n \"agent_type\": \"review\", \"mode\": \"read_only\", \"file_scope\": [\"docs\"] } }\n ]\n }\n },\n {\n \"reduce\": {\n \"id\": \"summary\",\n \"inputs\": [\"code-review\", \"docs-review\"],\n \"prompt\": \"Combine the findings into the safest next edit.\"\n }\n }\n ]\n});", |
| 725 | "lang": "workflows/docs_readiness.workflow.js" |
| 726 | }, |
| 727 | { |
| 728 | "p": "Steps can be `agent`, `branch`, `sequence`, `reduce`, `loop_until`, `cond`, `expand`, and `teacher_review`. A workflow file has no file, shell, or network access of its own, and `import`, `fetch`, `eval`, and `async` are rejected. The agents it starts do the real work, under your normal permissions." |
| 729 | }, |
| 730 | { |
| 731 | "note": "One run can start up to 1,000 agents, with at most 16 working at once; the rest wait for a slot. Loops must declare `max_iterations`." |
| 732 | } |
| 733 | ] |
| 734 | }, |
| 735 | { |
| 736 | "id": "run", |
| 737 | "title": "Run it", |
| 738 | "blocks": [ |
| 739 | { |
| 740 | "code": "codewhale workflow run docs-readiness --runtime inline\ncodewhale workflow run docs-readiness --goal \"prepare the 1.2 release\" --verify", |
| 741 | "lang": "Terminal" |
| 742 | }, |
| 743 | { |
| 744 | "p": "Codewhale finds `workflows/docs_readiness.workflow.js` from the name, checks it, and starts it. `--runtime inline` runs it in this terminal. The default, `tmux`, runs it in a detached tmux session that keeps going after you close the terminal. `--verify` runs the verification gates after a successful finish, and `--fleet <name>` uses a named Fleet instead of the built-in roles." |
| 745 | }, |
| 746 | { |
| 747 | "p": "To keep the work off your checkout, add `--worktree-repo . --branch <name>`: the run gets its own git worktree and branch." |
| 748 | }, |
| 749 | { |
| 750 | "p": "Inside a session, `/workflow` starts a workflow and `/workflows` lists or cancels the runs in that session." |
| 751 | } |
| 752 | ] |
| 753 | }, |
| 754 | { |
| 755 | "id": "watch", |
| 756 | "title": "Watch and stop a run", |
| 757 | "blocks": [ |
| 758 | { |
| 759 | "p": "Each run is a Lane. Lanes are saved to disk, so you can check on them from any terminal:" |
| 760 | }, |
| 761 | { |
| 762 | "code": "codewhale lane list\ncodewhale lane status <lane-id>\ncodewhale lane logs <lane-id>\ncodewhale lane attach <lane-id>\ncodewhale lane interrupt <lane-id>", |
| 763 | "lang": "Terminal" |
| 764 | }, |
| 765 | { |
| 766 | "p": "`lane list`, `lane status`, and `lane interrupt` accept `--json` and print a machine-readable receipt. In a session, `/lane` offers the same controls with the same results." |
| 767 | } |
| 768 | ] |
| 769 | }, |
| 770 | { |
| 771 | "id": "batch", |
| 772 | "title": "Run a batch of tasks", |
| 773 | "blocks": [ |
| 774 | { |
| 775 | "p": "When you have a list of separate tasks rather than one plan, write them as a task file and run them as a Fleet run. Each task names its goal, its role, and the paths it may write. [The tutorial](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/FLEET_WORKFLOW_TUTORIAL.md) has a complete `tasks.json`." |
| 776 | }, |
| 777 | { |
| 778 | "code": "codewhale fleet init\ncodewhale fleet run tasks.json --max-workers 4\ncodewhale fleet status\ncodewhale fleet logs <worker-id>\ncodewhale fleet resume <run-id>\ncodewhale fleet stop --all", |
| 779 | "lang": "Terminal" |
| 780 | }, |
| 781 | { |
| 782 | "p": "`fleet status` counts queued, running, finished, and failed work from this workspace's run record. `fleet resume` picks a run back up after the laptop slept or the manager exited, without starting a new one. For the agents attached to your current session only, use `/fleet workers` (or `/subagents`)." |
| 783 | } |
| 784 | ] |
| 785 | } |
| 786 | ], |
| 787 | "next": [ |
| 788 | { |
| 789 | "href": "/docs/subagents", |
| 790 | "label": "Run agents in parallel", |
| 791 | "note": "Hand independent pieces of one task to sub-agents without writing a workflow." |
| 792 | }, |
| 793 | { |
| 794 | "href": "/docs/review", |
| 795 | "label": "Review what changed", |
| 796 | "note": "Check the diff a run produced and get a review before you push." |
| 797 | }, |
| 798 | { |
| 799 | "href": "/docs/vocabulary", |
| 800 | "label": "Product terms", |
| 801 | "note": "Fleet, Workflow, Lane, and Runtime, each in one sentence." |
| 802 | } |
| 803 | ], |
| 804 | "sourceNote": "Source documents: docs/FLEET.md, docs/FLEET_WORKFLOW_TUTORIAL.md, docs/WORKFLOW_AUTHORING.md · Update docs-map.ts when changing." |
| 805 | }, |
| 806 | "docs-mcp": { |
| 807 | "metaTitle": "Connect tools with MCP · Codewhale Docs", |
| 808 | "metaDescription": "Add Model Context Protocol servers so Codewhale can use more tools, sign in to remote servers, run Codewhale itself as an MCP server, and try code mode.", |
| 809 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 810 | "title": "Connect tools with MCP", |
| 811 | "lede": "MCP servers give Codewhale more tools — a database, an issue tracker, a browser. Add a local server that Codewhale starts for you, or a remote server by URL. Its tools then go through the same approvals as built-in ones.", |
| 812 | "sections": [ |
| 813 | { |
| 814 | "id": "add", |
| 815 | "title": "Add a server", |
| 816 | "blocks": [ |
| 817 | { |
| 818 | "code": "codewhale mcp add git --command \"uvx\" --arg \"mcp-server-git\"\ncodewhale mcp add docs --url \"https://example.com/mcp\"\ncodewhale mcp list\ncodewhale mcp validate", |
| 819 | "lang": "Terminal" |
| 820 | }, |
| 821 | { |
| 822 | "p": "`--command` starts a local server over stdio; repeat `--arg` for each argument. `--url` connects to a remote server over Streamable HTTP, with legacy SSE as a fallback. `mcp validate` checks the config and the servers you require." |
| 823 | }, |
| 824 | { |
| 825 | "p": "Inside a session, `/mcp` opens the MCP manager: each server's state, transport, timeouts, errors, and discovered tools. The same actions are available there, for example `/mcp add stdio <name> <command>` and `/mcp add http <name> <url>`." |
| 826 | }, |
| 827 | { |
| 828 | "note": "An MCP server runs with your permissions. Add only servers you trust, as you would any program you install." |
| 829 | } |
| 830 | ] |
| 831 | }, |
| 832 | { |
| 833 | "id": "remote-auth", |
| 834 | "title": "Sign in to a remote server", |
| 835 | "blocks": [ |
| 836 | { |
| 837 | "p": "For a server that uses OAuth, add it by URL and log in. For a bearer token, keep the token in an environment variable instead of the config file:" |
| 838 | }, |
| 839 | { |
| 840 | "code": "codewhale mcp login docs\ncodewhale mcp add tracker --url \"https://example.com/mcp\" --bearer-token-env-var TRACKER_TOKEN", |
| 841 | "lang": "Terminal" |
| 842 | }, |
| 843 | { |
| 844 | "p": "An explicit Authorization header always wins: headers from config apply first, then the bearer-token variable, then a stored OAuth login. `codewhale mcp logout <name>` removes the stored login on this machine; the provider may keep its own grant until you revoke it there." |
| 845 | } |
| 846 | ] |
| 847 | }, |
| 848 | { |
| 849 | "id": "config", |
| 850 | "title": "Edit the config file", |
| 851 | "blocks": [ |
| 852 | { |
| 853 | "p": "Servers live in `~/.codewhale/mcp.json`. `codewhale mcp init` writes a starter file. The `mcpServers` key used by other clients works too, so you can paste an existing entry." |
| 854 | }, |
| 855 | { |
| 856 | "code": "{\n \"servers\": {\n \"example\": {\n \"command\": \"node\",\n \"args\": [\"./path/to/your-mcp-server.js\"],\n \"env\": {},\n \"disabled\": false\n }\n }\n}", |
| 857 | "lang": "mcp.json" |
| 858 | }, |
| 859 | { |
| 860 | "p": "After editing the file, run `/mcp reload` in the session; no restart is needed. A server starts only when a turn needs one of its tools, unless you mark it `\"required\": true` to connect at startup." |
| 861 | } |
| 862 | ] |
| 863 | }, |
| 864 | { |
| 865 | "id": "tool-names", |
| 866 | "title": "Find the tools", |
| 867 | "blocks": [ |
| 868 | { |
| 869 | "p": "Each tool appears to the model as `mcp_<server>_<tool>`: a server named `git` with a `status` tool becomes `mcp_git_status`. `codewhale mcp tools <server>` lists what a server offers. A server that fails to connect or is disabled never shows up as an available tool." |
| 870 | }, |
| 871 | { |
| 872 | "p": "MCP tools follow your [approval setting](/docs/modes): listing and reading a server's resources and prompts can run without a prompt when policy allows, and tools with side effects ask first. Full Access does not override repository rules or managed policy." |
| 873 | } |
| 874 | ] |
| 875 | }, |
| 876 | { |
| 877 | "id": "serve", |
| 878 | "title": "Run Codewhale as an MCP server", |
| 879 | "blocks": [ |
| 880 | { |
| 881 | "p": "Other MCP clients — including another Codewhale session — can use Codewhale's tools. Register it once:" |
| 882 | }, |
| 883 | { |
| 884 | "code": "codewhale mcp add-self\ncodewhale mcp tools codewhale", |
| 885 | "lang": "Terminal" |
| 886 | }, |
| 887 | { |
| 888 | "p": "`add-self` writes an entry that runs `codewhale serve --mcp` over stdio. Each client starts its own process; no network port is opened. `codewhale serve --http` is a different thing — the [Runtime API](/docs/runtime-api) for apps." |
| 889 | } |
| 890 | ] |
| 891 | }, |
| 892 | { |
| 893 | "id": "code-mode", |
| 894 | "title": "Compose tool calls with code mode (experimental)", |
| 895 | "blocks": [ |
| 896 | { |
| 897 | "p": "Code mode lets the model write one short JavaScript program that calls several tools, loops, and filters results, instead of making each call as a separate step. Only the program's final value goes back to the model, which keeps long lookups compact. It is off by default. Try it for one session, or turn it on in config:" |
| 898 | }, |
| 899 | { |
| 900 | "code": "codewhale --enable code_mode\n\n# ~/.codewhale/config.toml\n[features]\ncode_mode = true", |
| 901 | "lang": "Terminal / config.toml" |
| 902 | }, |
| 903 | { |
| 904 | "list": [ |
| 905 | "Only read-only tools that need no approval can run inside a program. Anything that writes, runs a shell command, or would ask you stops the program and reports which call it refused.", |
| 906 | "MCP tools cannot be called from a program yet. Use them as ordinary tool calls.", |
| 907 | "Limits per program: 50 tool calls, 4 at a time, 30 seconds, and 16 KiB returned.", |
| 908 | "Code mode is not available in Plan mode." |
| 909 | ] |
| 910 | } |
| 911 | ] |
| 912 | } |
| 913 | ], |
| 914 | "next": [ |
| 915 | { |
| 916 | "href": "/docs/hooks", |
| 917 | "label": "Run commands on events", |
| 918 | "note": "Check or rewrite a tool call before it runs, including MCP tools." |
| 919 | }, |
| 920 | { |
| 921 | "href": "/docs/modes", |
| 922 | "label": "Set modes and approvals", |
| 923 | "note": "Decide which MCP calls stop for your approval." |
| 924 | }, |
| 925 | { |
| 926 | "href": "/docs/runtime-api", |
| 927 | "label": "Automate with the Runtime API", |
| 928 | "note": "Drive Codewhale from your own app or script over HTTP." |
| 929 | } |
| 930 | ], |
| 931 | "sourceNote": "Source documents: docs/MCP.md, crates/tui/src/tools/codemode.rs · Update docs-map.ts when changing." |
| 932 | }, |
| 933 | "docs-modes": { |
| 934 | "metaTitle": "Set modes and approvals · Codewhale Docs", |
| 935 | "metaDescription": "Choose Plan, Work, or Operate for the kind of work, and Ask, Auto-Review, or Full Access for how often Codewhale stops to ask you.", |
| 936 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 937 | "title": "Set modes and approvals", |
| 938 | "lede": "Two separate controls decide what Codewhale does on its own. The mode sets the kind of work — look, change, or coordinate. The approval setting decides when it stops to ask you. Change either one from the keyboard at any time between turns.", |
| 939 | "sections": [ |
| 940 | { |
| 941 | "id": "modes", |
| 942 | "title": "Pick a mode", |
| 943 | "blocks": [ |
| 944 | { |
| 945 | "rows": [ |
| 946 | [ |
| 947 | "Plan", |
| 948 | "Look and plan only. Codewhale can read the workspace and research, but it cannot edit files or run shell commands. Use it to understand a codebase or agree on an approach first." |
| 949 | ], |
| 950 | [ |
| 951 | "Work", |
| 952 | "Everyday coding. Codewhale reads, edits, and runs commands, within the approval setting you chose. This is the default." |
| 953 | ], |
| 954 | [ |
| 955 | "Operate", |
| 956 | "Larger goals. Same permissions as Work, but Codewhale plans named steps, hands independent steps to sub-agents in parallel, and checks each result before it reports done." |
| 957 | ] |
| 958 | ] |
| 959 | }, |
| 960 | { |
| 961 | "p": "Press Tab with an empty composer to cycle Plan → Work → Operate, or type `/mode` to open the picker. You can also switch directly:" |
| 962 | }, |
| 963 | { |
| 964 | "code": "/mode plan\n/mode work\n/mode operate", |
| 965 | "lang": "Codewhale" |
| 966 | }, |
| 967 | { |
| 968 | "p": "The mode you pick becomes the mode your next session starts in. Codewhale refuses mode changes while a turn is running; press Esc to stop the turn first." |
| 969 | } |
| 970 | ] |
| 971 | }, |
| 972 | { |
| 973 | "id": "approvals", |
| 974 | "title": "Choose when it asks", |
| 975 | "blocks": [ |
| 976 | { |
| 977 | "p": "Press Shift+Tab to cycle Ask → Auto-Review → Full Access. Plan is always read-only, whatever you pick here." |
| 978 | }, |
| 979 | { |
| 980 | "rows": [ |
| 981 | [ |
| 982 | "Ask", |
| 983 | "The default. File edits inside the workspace are applied and shown to you as a diff. Shell commands and other consequential tools stop for your approval." |
| 984 | ], |
| 985 | [ |
| 986 | "Auto-Review", |
| 987 | "Never stops to ask. Calls that are provably safe run. Publishing and destructive background actions are always blocked. Anything else gets one independent model review; high-risk calls and failed reviews are denied, not run." |
| 988 | ], |
| 989 | [ |
| 990 | "Full Access", |
| 991 | "No approval prompts. Repository rules and managed policy still block what they block. Use it only in a workspace you trust." |
| 992 | ] |
| 993 | ] |
| 994 | }, |
| 995 | { |
| 996 | "note": "Ask applies workspace file edits without asking. Commit or stash anything you care about before you start, and use [Review what changed](/docs/review) to check or roll back edits." |
| 997 | } |
| 998 | ] |
| 999 | }, |
| 1000 | { |
| 1001 | "id": "prompt", |
| 1002 | "title": "Answer an approval prompt", |
| 1003 | "blocks": [ |
| 1004 | { |
| 1005 | "p": "When Codewhale stops at an approval, it shows the exact command. Answer with one key:" |
| 1006 | }, |
| 1007 | { |
| 1008 | "rows": [ |
| 1009 | [ |
| 1010 | "y", |
| 1011 | "Allow this call once." |
| 1012 | ], |
| 1013 | [ |
| 1014 | "a", |
| 1015 | "Allow it for the rest of this session." |
| 1016 | ], |
| 1017 | [ |
| 1018 | "n", |
| 1019 | "Deny it. Codewhale is told the call was refused." |
| 1020 | ], |
| 1021 | [ |
| 1022 | "Esc", |
| 1023 | "Stop the whole turn." |
| 1024 | ] |
| 1025 | ], |
| 1026 | "codeTerms": true |
| 1027 | }, |
| 1028 | { |
| 1029 | "p": "The highlighted option on a new prompt is Deny, so pressing Enter without reading refuses the call. To change that, or to deny prompts that wait too long, set it in `~/.codewhale/config.toml`:" |
| 1030 | }, |
| 1031 | { |
| 1032 | "code": "[approval]\ndefault_selection = \"allow_once\" # default: \"deny\"\ntimeout_seconds = 300 # default: wait indefinitely", |
| 1033 | "lang": "config.toml" |
| 1034 | } |
| 1035 | ] |
| 1036 | } |
| 1037 | ], |
| 1038 | "next": [ |
| 1039 | { |
| 1040 | "href": "/docs/review", |
| 1041 | "label": "Review what changed", |
| 1042 | "note": "See the diff for a session and roll files back to an earlier turn." |
| 1043 | }, |
| 1044 | { |
| 1045 | "href": "/docs/sandbox", |
| 1046 | "label": "Limit what commands can touch", |
| 1047 | "note": "An approval is not a sandbox. See what the operating system enforces on each platform." |
| 1048 | }, |
| 1049 | { |
| 1050 | "href": "/docs/subagents", |
| 1051 | "label": "Run agents in parallel", |
| 1052 | "note": "What Operate does with independent steps, and how to watch it." |
| 1053 | } |
| 1054 | ], |
| 1055 | "sourceNote": "Source documents: docs/MODES.md, docs/INSTALL.md §10, docs/CONFIGURATION.md · Update docs-map.ts when changing." |
| 1056 | }, |
| 1057 | "docs-runtime-api": { |
| 1058 | "metaTitle": "Automate with the Runtime API · Codewhale Docs", |
| 1059 | "metaDescription": "Drive Codewhale from your own scripts and apps: run one-shot prompts in CI, or start the local HTTP API and send turns, stream events, and answer approvals.", |
| 1060 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 1061 | "title": "Automate with the Runtime API", |
| 1062 | "lede": "Scripts and apps can drive the same engine you use in the terminal. For a single job, use `codewhale exec`. For an app that needs threads, live events, and approvals, run the local Runtime API. Everything runs on your machine; there is no hosted relay.", |
| 1063 | "sections": [ |
| 1064 | { |
| 1065 | "id": "exec", |
| 1066 | "title": "Run one job from a script", |
| 1067 | "blocks": [ |
| 1068 | { |
| 1069 | "code": "codewhale exec \"Reply with exactly: pong\"\ncodewhale exec --auto \"fix the failing test and run it again\"\ncodewhale exec --auto --output-format stream-json \"update the changelog\"", |
| 1070 | "lang": "Terminal" |
| 1071 | }, |
| 1072 | { |
| 1073 | "p": "Plain `exec` answers once without tools. `--auto` lets it use tools and approves them automatically, so use it only in a repository or container you trust; it never widens the [sandbox](/docs/sandbox). `--output-format stream-json` prints one JSON event per line and saves the session so `--continue` can pick it up. `--max-turns` and `--allowed-tools` put limits on a run." |
| 1074 | } |
| 1075 | ] |
| 1076 | }, |
| 1077 | { |
| 1078 | "id": "start", |
| 1079 | "title": "Start the Runtime API", |
| 1080 | "blocks": [ |
| 1081 | { |
| 1082 | "code": "export CODEWHALE_RUNTIME_TOKEN=\"$(openssl rand -hex 32)\"\ncodewhale app-server --http # http://127.0.0.1:7878", |
| 1083 | "lang": "Terminal" |
| 1084 | }, |
| 1085 | { |
| 1086 | "p": "Set the token yourself before starting; if you do not, Codewhale generates one for the process and does not print it. Every `/v1/*` request must send it as `Authorization: Bearer <token>`. `--port` changes the port." |
| 1087 | } |
| 1088 | ] |
| 1089 | }, |
| 1090 | { |
| 1091 | "id": "turn", |
| 1092 | "title": "Send a turn and watch it", |
| 1093 | "blocks": [ |
| 1094 | { |
| 1095 | "code": "API=http://127.0.0.1:7878\nAUTH=\"Authorization: Bearer $CODEWHALE_RUNTIME_TOKEN\"\n\nTHREAD=$(curl -s -X POST \"$API/v1/threads\" -H \"$AUTH\" \\\n -H \"Content-Type: application/json\" -d '{}' | jq -r .id)\n\ncurl -s -X POST \"$API/v1/threads/$THREAD/turns\" -H \"$AUTH\" \\\n -H \"Content-Type: application/json\" -d '{\"prompt\": \"Summarize README.md\"}'\n\ncurl -N \"$API/v1/threads/$THREAD/events?since_seq=0\" -H \"$AUTH\"", |
| 1096 | "lang": "Terminal" |
| 1097 | }, |
| 1098 | { |
| 1099 | "p": "A thread is a conversation; a turn is one request and everything Codewhale does for it. The events stream replays from the sequence number you give and then stays open for new events, so a client that reconnects misses nothing." |
| 1100 | }, |
| 1101 | { |
| 1102 | "rows": [ |
| 1103 | [ |
| 1104 | "Stop a turn", |
| 1105 | "`POST /v1/threads/{id}/turns/{turn_id}/interrupt`" |
| 1106 | ], |
| 1107 | [ |
| 1108 | "Answer an approval", |
| 1109 | "`POST /v1/approvals/{approval_id}`" |
| 1110 | ], |
| 1111 | [ |
| 1112 | "Steer a running turn", |
| 1113 | "`POST /v1/threads/{id}/turns/{turn_id}/steer`" |
| 1114 | ], |
| 1115 | [ |
| 1116 | "List saved sessions", |
| 1117 | "`GET /v1/sessions`" |
| 1118 | ] |
| 1119 | ] |
| 1120 | }, |
| 1121 | { |
| 1122 | "p": "[docs/RUNTIME_API.md](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/RUNTIME_API.md) lists every route, request body, and event." |
| 1123 | } |
| 1124 | ] |
| 1125 | }, |
| 1126 | { |
| 1127 | "id": "other", |
| 1128 | "title": "Pick another connection", |
| 1129 | "blocks": [ |
| 1130 | { |
| 1131 | "rows": [ |
| 1132 | [ |
| 1133 | "codewhale app-server --stdio", |
| 1134 | "JSON-RPC over standard input and output, with no network listener. Good for an SDK or a local probe." |
| 1135 | ], |
| 1136 | [ |
| 1137 | "codewhale serve --acp", |
| 1138 | "Agent Client Protocol for editors such as Zed." |
| 1139 | ], |
| 1140 | [ |
| 1141 | "codewhale serve --mcp", |
| 1142 | "Offer Codewhale's tools to another MCP client. See [Connect tools with MCP](/docs/mcp)." |
| 1143 | ], |
| 1144 | [ |
| 1145 | "codewhale web", |
| 1146 | "The built-in [browser client](/docs/web), on the same API." |
| 1147 | ], |
| 1148 | [ |
| 1149 | "codewhale doctor --json", |
| 1150 | "Health and capabilities as JSON, with no secrets." |
| 1151 | ] |
| 1152 | ], |
| 1153 | "codeTerms": true |
| 1154 | } |
| 1155 | ] |
| 1156 | }, |
| 1157 | { |
| 1158 | "id": "security", |
| 1159 | "title": "Keep it private", |
| 1160 | "blocks": [ |
| 1161 | { |
| 1162 | "list": [ |
| 1163 | "The server listens on `127.0.0.1` by default. The token is a local guard, not a replacement for TLS or a VPN; do not expose the port to a network.", |
| 1164 | "`--insecure-no-auth` is accepted only on a loopback address.", |
| 1165 | "The API never returns your provider keys. Health and capability reports carry only metadata — no secrets, file contents, or messages." |
| 1166 | ] |
| 1167 | } |
| 1168 | ] |
| 1169 | } |
| 1170 | ], |
| 1171 | "next": [ |
| 1172 | { |
| 1173 | "href": "/docs/web", |
| 1174 | "label": "Open the browser client", |
| 1175 | "note": "A ready-made client for the same API." |
| 1176 | }, |
| 1177 | { |
| 1178 | "href": "/docs/hooks", |
| 1179 | "label": "Run commands on events", |
| 1180 | "note": "React to session events without writing a client." |
| 1181 | }, |
| 1182 | { |
| 1183 | "href": "/docs/fleet", |
| 1184 | "label": "Run a workflow", |
| 1185 | "note": "Durable, multi-step runs you can check from any terminal." |
| 1186 | } |
| 1187 | ], |
| 1188 | "sourceNote": "Source document: docs/RUNTIME_API.md · Update docs-map.ts when changing." |
| 1189 | }, |
| 1190 | "docs-sandbox": { |
| 1191 | "metaTitle": "Limit what commands can touch · Codewhale Docs", |
| 1192 | "metaDescription": "See which operating-system sandbox wraps shell commands on macOS, Linux, and Windows, turn it on where it is optional, and choose how much a command may write.", |
| 1193 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 1194 | "title": "Limit what commands can touch", |
| 1195 | "lede": "Approving a command decides whether it runs. A sandbox decides what it can reach once it does. Codewhale uses the operating system's sandbox where one is available and tells you plainly when there is none.", |
| 1196 | "sections": [ |
| 1197 | { |
| 1198 | "id": "platforms", |
| 1199 | "title": "Check what your platform provides", |
| 1200 | "blocks": [ |
| 1201 | { |
| 1202 | "rows": [ |
| 1203 | [ |
| 1204 | "macOS", |
| 1205 | "Seatbelt, automatically, when its startup check succeeds. Commands get broad read access, writes limited by the sandbox mode, and network only when the mode allows it." |
| 1206 | ], |
| 1207 | [ |
| 1208 | "Linux", |
| 1209 | "Bubblewrap, but only if you turn it on (below). Without it, commands run with no OS sandbox." |
| 1210 | ], |
| 1211 | [ |
| 1212 | "Windows", |
| 1213 | "No OS sandbox today. Your approval setting and Windows permissions still apply." |
| 1214 | ], |
| 1215 | [ |
| 1216 | "External service", |
| 1217 | "With `sandbox_backend = \"opensandbox\"`, shell commands run on an OpenSandbox-compatible service you configure; its isolation is that service's to guarantee." |
| 1218 | ] |
| 1219 | ] |
| 1220 | }, |
| 1221 | { |
| 1222 | "p": "Ask Codewhale which one it found:" |
| 1223 | }, |
| 1224 | { |
| 1225 | "code": "codewhale doctor\ncodewhale setup --status", |
| 1226 | "lang": "Terminal" |
| 1227 | }, |
| 1228 | { |
| 1229 | "p": "Both report the sandbox that is actually available after your settings are applied. Codewhale never counts source code that is not wired in as a sandbox." |
| 1230 | } |
| 1231 | ] |
| 1232 | }, |
| 1233 | { |
| 1234 | "id": "linux", |
| 1235 | "title": "Turn on the Linux sandbox", |
| 1236 | "blocks": [ |
| 1237 | { |
| 1238 | "p": "Install bubblewrap, then opt in with one line in `~/.codewhale/config.toml`:" |
| 1239 | }, |
| 1240 | { |
| 1241 | "code": "sudo apt install bubblewrap # Fedora: dnf install bubblewrap · Arch: pacman -S bubblewrap\n\n# ~/.codewhale/config.toml\nprefer_bwrap = true", |
| 1242 | "lang": "Terminal / config.toml" |
| 1243 | }, |
| 1244 | { |
| 1245 | "p": "Codewhale uses `/usr/bin/bwrap` only when that file exists and is executable. Commands then see a read-only view of the system, write only where the sandbox mode allows, and have no network unless the mode enables it." |
| 1246 | } |
| 1247 | ] |
| 1248 | }, |
| 1249 | { |
| 1250 | "id": "mode", |
| 1251 | "title": "Choose how much a command may write", |
| 1252 | "blocks": [ |
| 1253 | { |
| 1254 | "code": "sandbox_mode = \"workspace-write\"", |
| 1255 | "lang": "config.toml" |
| 1256 | }, |
| 1257 | { |
| 1258 | "rows": [ |
| 1259 | [ |
| 1260 | "read-only", |
| 1261 | "Commands can read but not write." |
| 1262 | ], |
| 1263 | [ |
| 1264 | "workspace-write", |
| 1265 | "Commands can write inside the workspace and temporary folders, and nowhere else." |
| 1266 | ], |
| 1267 | [ |
| 1268 | "danger-full-access", |
| 1269 | "No OS sandbox. Use only on a machine or container you are prepared to lose." |
| 1270 | ], |
| 1271 | [ |
| 1272 | "external-sandbox", |
| 1273 | "You are already running inside isolation, so Codewhale adds none of its own." |
| 1274 | ] |
| 1275 | ], |
| 1276 | "codeTerms": true |
| 1277 | }, |
| 1278 | { |
| 1279 | "p": "The first two are enforced only where a sandbox is available — on Linux without bubblewrap, and on Windows, they are settings without an OS wrapper behind them. A repository's own config can make the mode stricter, never looser. For one headless run, pass `--sandbox <mode>` to `codewhale exec`; `--auto` approves tools but never widens the sandbox." |
| 1280 | } |
| 1281 | ] |
| 1282 | }, |
| 1283 | { |
| 1284 | "id": "limits", |
| 1285 | "title": "Know the limits", |
| 1286 | "blocks": [ |
| 1287 | { |
| 1288 | "list": [ |
| 1289 | "Availability is checked before a command starts, but the sandbox can still fail at launch because of host policy or container restrictions.", |
| 1290 | "A “Permission denied” from a command is not proof that the sandbox blocked it. Codewhale labels a denial as the sandbox's only when the sandbox itself reported it.", |
| 1291 | "No sandbox protects against kernel vulnerabilities or every kind of resource exhaustion." |
| 1292 | ] |
| 1293 | } |
| 1294 | ] |
| 1295 | } |
| 1296 | ], |
| 1297 | "next": [ |
| 1298 | { |
| 1299 | "href": "/docs/modes", |
| 1300 | "label": "Set modes and approvals", |
| 1301 | "note": "Decide which commands stop for your approval." |
| 1302 | }, |
| 1303 | { |
| 1304 | "href": "/docs/trust", |
| 1305 | "label": "See what leaves your machine", |
| 1306 | "note": "What a provider receives, what stays local, and what telemetry sends." |
| 1307 | }, |
| 1308 | { |
| 1309 | "href": "/docs/configuration", |
| 1310 | "label": "Change settings", |
| 1311 | "note": "Where these keys live and what a repository may override." |
| 1312 | } |
| 1313 | ], |
| 1314 | "sourceNote": "Source documents: docs/SANDBOX.md, docs/CONFIGURATION.md · Update docs-map.ts when changing." |
| 1315 | }, |
| 1316 | "docs-subagents": { |
| 1317 | "metaTitle": "Run agents in parallel · Codewhale Docs", |
| 1318 | "metaDescription": "Let Codewhale hand independent parts of a task to sub-agents, choose their roles, keep their edits in separate worktrees, and watch them work.", |
| 1319 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 1320 | "title": "Run agents in parallel", |
| 1321 | "lede": "Codewhale can hand a focused piece of work to a sub-agent and keep going while it runs. Use this when a task splits into independent parts — mapping a codebase, reviewing a change, running tests — so they happen at the same time.", |
| 1322 | "sections": [ |
| 1323 | { |
| 1324 | "id": "ask", |
| 1325 | "title": "Ask for it", |
| 1326 | "blocks": [ |
| 1327 | { |
| 1328 | "p": "You do not start sub-agents with a command; you ask in plain words. In Operate, Codewhale does this on its own for independent steps. In Work, say what you want split up:" |
| 1329 | }, |
| 1330 | { |
| 1331 | "code": "Use three explore agents in parallel: one maps the auth code,\none maps the billing code, one lists the tests that cover both.\nThen summarize what would break if we changed the session format.", |
| 1332 | "lang": "Prompt" |
| 1333 | }, |
| 1334 | { |
| 1335 | "p": "Each sub-agent starts in the background and reports back when it finishes. Your composer stays free, and the parent turn picks up the results." |
| 1336 | } |
| 1337 | ] |
| 1338 | }, |
| 1339 | { |
| 1340 | "id": "roles", |
| 1341 | "title": "Pick a role", |
| 1342 | "blocks": [ |
| 1343 | { |
| 1344 | "p": "A role is the stance a sub-agent takes. Name one in your request, or let Codewhale choose. A sub-agent never gets more permission than your session has." |
| 1345 | }, |
| 1346 | { |
| 1347 | "rows": [ |
| 1348 | [ |
| 1349 | "general", |
| 1350 | "Does whatever the brief says; may edit and run commands. The default." |
| 1351 | ], |
| 1352 | [ |
| 1353 | "explore", |
| 1354 | "Read-only. Maps the relevant code fast — “find every caller of this function.”" |
| 1355 | ], |
| 1356 | [ |
| 1357 | "planner", |
| 1358 | "Designs an approach without changing anything." |
| 1359 | ], |
| 1360 | [ |
| 1361 | "reviewer", |
| 1362 | "Reads and grades a change, with a severity for each finding." |
| 1363 | ], |
| 1364 | [ |
| 1365 | "implement", |
| 1366 | "Lands one specific change with the smallest edit." |
| 1367 | ], |
| 1368 | [ |
| 1369 | "test", |
| 1370 | "Runs tests and checks, then reports pass or fail. Does not edit code." |
| 1371 | ], |
| 1372 | [ |
| 1373 | "advisor", |
| 1374 | "Short, careful second opinion on a judgment call. No commands." |
| 1375 | ], |
| 1376 | [ |
| 1377 | "custom", |
| 1378 | "Only the tools you list, for tightly limited jobs." |
| 1379 | ] |
| 1380 | ], |
| 1381 | "codeTerms": true |
| 1382 | }, |
| 1383 | { |
| 1384 | "p": "To give a role a specific model every time, save it with `/fleet setup` — see [Run a workflow](/docs/fleet)." |
| 1385 | } |
| 1386 | ] |
| 1387 | }, |
| 1388 | { |
| 1389 | "id": "worktrees", |
| 1390 | "title": "Keep parallel edits apart", |
| 1391 | "blocks": [ |
| 1392 | { |
| 1393 | "p": "When two sub-agents would edit the same repository, ask for each to work in its own worktree. Codewhale creates a fresh git worktree and branch for that agent beside your repository, under `.codewhale-worktrees/`, so your checkout stays clean until you merge." |
| 1394 | }, |
| 1395 | { |
| 1396 | "p": "A worktree is isolation, not permission: an agent that should write still needs a writing role and the paths it may change. Two agents that claim the same files are stopped before either one edits anything." |
| 1397 | } |
| 1398 | ] |
| 1399 | }, |
| 1400 | { |
| 1401 | "id": "watch", |
| 1402 | "title": "Watch and answer them", |
| 1403 | "blocks": [ |
| 1404 | { |
| 1405 | "code": "/subagents", |
| 1406 | "lang": "Codewhale" |
| 1407 | }, |
| 1408 | { |
| 1409 | "p": "`/subagents` (the same view as `/fleet workers`) lists the agents attached to this session and what each one is doing. Select one to read its transcript." |
| 1410 | }, |
| 1411 | { |
| 1412 | "p": "Sub-agents follow your [approval setting](/docs/modes). In Ask, a call that needs approval appears in your session as a normal prompt while the agent waits. In Auto-Review, each held call gets the same independent review, and nothing prompts you. Every decision you did not make yourself is written to the agent's transcript." |
| 1413 | } |
| 1414 | ] |
| 1415 | }, |
| 1416 | { |
| 1417 | "id": "limits", |
| 1418 | "title": "Know the limits", |
| 1419 | "blocks": [ |
| 1420 | { |
| 1421 | "rows": [ |
| 1422 | [ |
| 1423 | "Running at once", |
| 1424 | "64 by default. Set `max_subagents` (up to 128) in `~/.codewhale/config.toml`." |
| 1425 | ], |
| 1426 | [ |
| 1427 | "Queued plus running", |
| 1428 | "Up to 1,024; extra launches wait for a slot." |
| 1429 | ], |
| 1430 | [ |
| 1431 | "Nesting", |
| 1432 | "A sub-agent may start its own, three levels deep by default, never more than eight." |
| 1433 | ] |
| 1434 | ] |
| 1435 | }, |
| 1436 | { |
| 1437 | "p": "These are ceilings, not targets. A few well-scoped agents with one clear summary beat many overlapping ones. For work that must survive a restart or a sleeping laptop, use a [Fleet run](/docs/fleet) instead." |
| 1438 | } |
| 1439 | ] |
| 1440 | } |
| 1441 | ], |
| 1442 | "next": [ |
| 1443 | { |
| 1444 | "href": "/docs/fleet", |
| 1445 | "label": "Run a workflow", |
| 1446 | "note": "Turn a plan you repeat into a Workflow with phases and a record of each run." |
| 1447 | }, |
| 1448 | { |
| 1449 | "href": "/docs/work", |
| 1450 | "label": "Track progress", |
| 1451 | "note": "How the To-do list shows what is done, in progress, and left." |
| 1452 | }, |
| 1453 | { |
| 1454 | "href": "/docs/review", |
| 1455 | "label": "Review what changed", |
| 1456 | "note": "Check what the agents changed before you keep it." |
| 1457 | } |
| 1458 | ], |
| 1459 | "sourceNote": "Source documents: docs/SUBAGENTS.md, docs/FLEET.md, docs/MODES.md · Update docs-map.ts when changing." |
| 1460 | }, |
| 1461 | "docs-web": { |
| 1462 | "metaTitle": "Open the browser client · Codewhale Docs", |
| 1463 | "metaDescription": "Work with Codewhale in a browser tab on your own machine, or continue a running terminal session from the Codewhale web app with /rc.", |
| 1464 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 1465 | "title": "Open the browser client", |
| 1466 | "lede": "Prefer a browser window to a terminal? Codewhale can serve its own client on your machine. It is another view of the same local session — same approvals, same sandbox, no account.", |
| 1467 | "sections": [ |
| 1468 | { |
| 1469 | "id": "start", |
| 1470 | "title": "Start it", |
| 1471 | "blocks": [ |
| 1472 | { |
| 1473 | "p": "Run this from the folder you want Codewhale to work in:" |
| 1474 | }, |
| 1475 | { |
| 1476 | "code": "codewhale web\ncodewhale web --port 8788 # if 7878 is taken", |
| 1477 | "lang": "Terminal" |
| 1478 | }, |
| 1479 | { |
| 1480 | "p": "Codewhale starts a local server at `http://127.0.0.1:7878`, prints a one-time link, and opens it in your default browser. If the browser does not open, use the printed link within ten minutes. Press Ctrl+C in the terminal to stop; the browser session ends with it." |
| 1481 | } |
| 1482 | ] |
| 1483 | }, |
| 1484 | { |
| 1485 | "id": "use", |
| 1486 | "title": "Work in the browser", |
| 1487 | "blocks": [ |
| 1488 | { |
| 1489 | "p": "The browser client lists and searches your threads, shows the transcript with each tool's result, and has a composer. You can start, steer, or interrupt a turn, answer approvals, and rename or archive threads. Your provider keys stay in Codewhale; nothing is copied into browser storage." |
| 1490 | } |
| 1491 | ] |
| 1492 | }, |
| 1493 | { |
| 1494 | "id": "local", |
| 1495 | "title": "Keep it local", |
| 1496 | "blocks": [ |
| 1497 | { |
| 1498 | "list": [ |
| 1499 | "The server only listens on `127.0.0.1`. There is no option to open it to your network, and it cannot run without authentication.", |
| 1500 | "The link carries a single-use code, not your access token. Opening it swaps the code for a cookie tied to this process, and the code stops working.", |
| 1501 | "Do not forward the port through a router, a public proxy, or a tunnel. For a phone or another machine, see the [Runtime API](/docs/runtime-api) and read its authentication rules first." |
| 1502 | ] |
| 1503 | } |
| 1504 | ] |
| 1505 | }, |
| 1506 | { |
| 1507 | "id": "remote", |
| 1508 | "title": "Continue a session from the web app", |
| 1509 | "blocks": [ |
| 1510 | { |
| 1511 | "p": "This is different: it hands a session already running in your terminal to the signed-in Codewhale web app, so you can keep going from another device. It needs a [Codewhale account](/docs/auth#account)." |
| 1512 | }, |
| 1513 | { |
| 1514 | "code": "/rc # in the running session; approve the one-time code in your browser\n/rc status # who controls the session now\n/rc link # print the session link\n/rc stop # hand control back to the terminal", |
| 1515 | "lang": "Codewhale" |
| 1516 | }, |
| 1517 | { |
| 1518 | "p": "While the web app holds the session, new prompts and approvals come from the browser, and the terminal stays readable. Either side can interrupt. You can also start a session this way with `codewhale rc`." |
| 1519 | } |
| 1520 | ] |
| 1521 | }, |
| 1522 | { |
| 1523 | "id": "fix", |
| 1524 | "title": "If something goes wrong", |
| 1525 | "blocks": [ |
| 1526 | { |
| 1527 | "rows": [ |
| 1528 | [ |
| 1529 | "Port in use", |
| 1530 | "Pass a free port with `--port`." |
| 1531 | ], |
| 1532 | [ |
| 1533 | "Browser did not open", |
| 1534 | "Copy the printed link into a browser on the same machine within ten minutes." |
| 1535 | ], |
| 1536 | [ |
| 1537 | "Link expired or already used", |
| 1538 | "That is expected. Run `codewhale web` again for a new one." |
| 1539 | ], |
| 1540 | [ |
| 1541 | "No model answers", |
| 1542 | "The web command does not set up providers. Check `codewhale doctor` and `/provider`." |
| 1543 | ] |
| 1544 | ] |
| 1545 | } |
| 1546 | ] |
| 1547 | } |
| 1548 | ], |
| 1549 | "next": [ |
| 1550 | { |
| 1551 | "href": "/docs/runtime-api", |
| 1552 | "label": "Automate with the Runtime API", |
| 1553 | "note": "The local API the browser client is built on." |
| 1554 | }, |
| 1555 | { |
| 1556 | "href": "/docs/auth", |
| 1557 | "label": "Connect a provider", |
| 1558 | "note": "Give the browser client a model to talk to." |
| 1559 | }, |
| 1560 | { |
| 1561 | "href": "/docs/modes", |
| 1562 | "label": "Set modes and approvals", |
| 1563 | "note": "The same approvals apply in the browser." |
| 1564 | } |
| 1565 | ], |
| 1566 | "sourceNote": "Source document: docs/WEB.md · Update docs-map.ts when changing." |
| 1567 | }, |
| 1568 | "docs-computers": { |
| 1569 | "metaTitle": "Send a task to the cloud · Codewhale Docs", |
| 1570 | "metaDescription": "Hand a coding task to a Codewhale cloud agent that works on a branch and opens a pull request — proposed first, started only when you confirm.", |
| 1571 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 1572 | "title": "Send a task to the cloud", |
| 1573 | "lede": "A cloud agent takes a task off your machine: it works in a fresh cloud sandbox, pushes a branch, and opens a pull request while you keep working locally. Nothing starts, costs money, or pushes until you confirm it.", |
| 1574 | "sections": [ |
| 1575 | { |
| 1576 | "id": "status", |
| 1577 | "title": "Know what is ready", |
| 1578 | "blocks": [ |
| 1579 | { |
| 1580 | "note": "Cloud agents are a preview. The full lifecycle is covered by offline tests, but the live path — a real sandbox and a real pull request on each forge — has not been verified end to end yet. Private repositories are not supported yet." |
| 1581 | } |
| 1582 | ] |
| 1583 | }, |
| 1584 | { |
| 1585 | "id": "before", |
| 1586 | "title": "Before you start", |
| 1587 | "blocks": [ |
| 1588 | { |
| 1589 | "list": [ |
| 1590 | "Sign in to your Codewhale account with `codewhale login`. Without it, a task can be proposed but not confirmed.", |
| 1591 | "Make an account API key available as `CODEWHALE_API_KEY`, so the agent in the sandbox runs as your account. Without it, confirming is refused before anything is spent.", |
| 1592 | "For GitHub, be signed in to the `gh` command-line tool; Codewhale uses that login to open the pull request." |
| 1593 | ] |
| 1594 | }, |
| 1595 | { |
| 1596 | "code": "codewhale dispatch --status", |
| 1597 | "lang": "Terminal" |
| 1598 | }, |
| 1599 | { |
| 1600 | "p": "`--status` shows the forges found in your git remotes and whether the required credentials are present. It never prints a secret." |
| 1601 | } |
| 1602 | ] |
| 1603 | }, |
| 1604 | { |
| 1605 | "id": "send", |
| 1606 | "title": "Propose, then confirm", |
| 1607 | "blocks": [ |
| 1608 | { |
| 1609 | "code": "codewhale dispatch \"fix the flaky login test and open a PR\" --remote github\ncodewhale dispatch --confirm cloud_<id>", |
| 1610 | "lang": "Terminal" |
| 1611 | }, |
| 1612 | { |
| 1613 | "p": "The first command only writes a proposal and prints its id. The second starts it. Codewhale may propose a cloud task on its own, but it never confirms one. In a session, use `/dispatch <task>` and `/dispatch confirm <id>`." |
| 1614 | }, |
| 1615 | { |
| 1616 | "p": "Once confirmed, the agent clones the repository into a new sandbox, does the work, pushes a new branch (never a force-push), and opens the pull request. The sandbox is deleted when the job finishes, fails, or is cancelled." |
| 1617 | } |
| 1618 | ] |
| 1619 | }, |
| 1620 | { |
| 1621 | "id": "track", |
| 1622 | "title": "Track or cancel a job", |
| 1623 | "blocks": [ |
| 1624 | { |
| 1625 | "code": "codewhale dispatch --list\ncodewhale dispatch --show cloud_<id>\ncodewhale dispatch --cancel cloud_<id>", |
| 1626 | "lang": "Terminal" |
| 1627 | }, |
| 1628 | { |
| 1629 | "p": "Cloud jobs also appear in `/jobs`. A job shows its progress, the branch, the pull request link once one exists, and how many minutes it ran — a runtime figure, not a bill. Cancelling tears the sandbox down right away." |
| 1630 | } |
| 1631 | ] |
| 1632 | }, |
| 1633 | { |
| 1634 | "id": "forge", |
| 1635 | "title": "Choose where the pull request goes", |
| 1636 | "blocks": [ |
| 1637 | { |
| 1638 | "p": "Codewhale supports GitHub, CNB, and Gitee, and never assumes `origin` is GitHub. A remote named `github`, `cnb`, or `gitee` is that forge; any other remote is identified by its host. If your repository has more than one forge, pass `--remote`." |
| 1639 | }, |
| 1640 | { |
| 1641 | "p": "If a pull request cannot be opened — for example, a forge token is missing — the job is marked failed after the push and says that no pull request was opened. It never reports a link it does not have." |
| 1642 | } |
| 1643 | ] |
| 1644 | } |
| 1645 | ], |
| 1646 | "next": [ |
| 1647 | { |
| 1648 | "href": "/docs/auth", |
| 1649 | "label": "Connect a provider", |
| 1650 | "note": "Sign in to your Codewhale account and manage keys." |
| 1651 | }, |
| 1652 | { |
| 1653 | "href": "/docs/review", |
| 1654 | "label": "Review what changed", |
| 1655 | "note": "Review the agent's pull request before you merge it." |
| 1656 | }, |
| 1657 | { |
| 1658 | "href": "/docs/fleet", |
| 1659 | "label": "Run a workflow", |
| 1660 | "note": "Run longer, multi-step work on your own machine instead." |
| 1661 | } |
| 1662 | ], |
| 1663 | "sourceNote": "Source documents: docs/DAYTONA_CLOUD_DISPATCH.md, docs/CODEWHALE_AGENT.md · Update docs-map.ts when changing." |
| 1664 | }, |
| 1665 | "docs-auth": { |
| 1666 | "metaTitle": "Connect a provider · Codewhale Docs", |
| 1667 | "metaDescription": "Give Codewhale a model: save a provider key, check which key is in use, or run a local model with no key. A Codewhale account is optional.", |
| 1668 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 1669 | "title": "Connect a provider", |
| 1670 | "lede": "Codewhale needs a model to answer. Save a key for a hosted provider, or point Codewhale at a model running on your own machine. You pay the provider directly; no Codewhale account is involved.", |
| 1671 | "sections": [ |
| 1672 | { |
| 1673 | "id": "save-key", |
| 1674 | "title": "Save a provider key", |
| 1675 | "blocks": [ |
| 1676 | { |
| 1677 | "p": "Get an API key from your provider, then save it. Codewhale asks for the key and does not echo it. DeepSeek is the default provider, so it is the example here." |
| 1678 | }, |
| 1679 | { |
| 1680 | "code": "codewhale auth set --provider deepseek\ncodewhale auth status --provider deepseek", |
| 1681 | "lang": "Terminal" |
| 1682 | }, |
| 1683 | { |
| 1684 | "p": "`auth status` names the source in use — config file, secret store, or environment variable — and shows only the last four characters. In a script, pipe the key in with `--api-key-stdin` instead of typing it." |
| 1685 | }, |
| 1686 | { |
| 1687 | "p": "You can also connect from inside Codewhale: press F3 (or type `/provider`), choose a provider, paste the key, then pick a model." |
| 1688 | }, |
| 1689 | { |
| 1690 | "note": "In v0.10.0, `auth set --provider deepseek` also switches your default model to DeepSeek Pro. Run `/model` if you want the faster, cheaper model back. Connecting through F3 keeps your current model." |
| 1691 | } |
| 1692 | ] |
| 1693 | }, |
| 1694 | { |
| 1695 | "id": "which-key", |
| 1696 | "title": "Know which key is used", |
| 1697 | "blocks": [ |
| 1698 | { |
| 1699 | "p": "When a key is set in more than one place, the first match in this order wins:" |
| 1700 | }, |
| 1701 | { |
| 1702 | "steps": [ |
| 1703 | "`--api-key` on the command line, for one run.", |
| 1704 | "`api_key` in `~/.codewhale/config.toml`.", |
| 1705 | "The secret store written by `codewhale auth set`.", |
| 1706 | "The provider's environment variable, such as `DEEPSEEK_API_KEY`." |
| 1707 | ] |
| 1708 | }, |
| 1709 | { |
| 1710 | "p": "Exporting a new environment variable therefore does not replace a key you saved earlier. If a rotated key keeps failing, run `auth status` to see which source is active, then save the new key or clear the stored one:" |
| 1711 | }, |
| 1712 | { |
| 1713 | "code": "codewhale auth clear --provider deepseek", |
| 1714 | "lang": "Terminal" |
| 1715 | }, |
| 1716 | { |
| 1717 | "p": "On Linux the secret store is a private file (mode 0600) under `~/.codewhale/secrets/`, not an OS keyring. `codewhale doctor --probe-api` makes one test call to confirm that the key and the network both work." |
| 1718 | } |
| 1719 | ] |
| 1720 | }, |
| 1721 | { |
| 1722 | "id": "other-providers", |
| 1723 | "title": "Use another provider or a local model", |
| 1724 | "blocks": [ |
| 1725 | { |
| 1726 | "p": "`codewhale auth list` shows every provider Codewhale knows and whether each one has a key. The pattern is the same for all of them: `codewhale auth set --provider <name>`, or that provider's environment variable." |
| 1727 | }, |
| 1728 | { |
| 1729 | "p": "Local runners — Ollama, vLLM, and SGLang — need no key by default, and your prompts stay on your machine. Start the runner, then choose it:" |
| 1730 | }, |
| 1731 | { |
| 1732 | "code": "codewhale auth list\ncodewhale --provider ollama --model <model-tag>", |
| 1733 | "lang": "Terminal" |
| 1734 | }, |
| 1735 | { |
| 1736 | "p": "The [models page](/models) lists providers, local setups, and how to switch models mid-session." |
| 1737 | } |
| 1738 | ] |
| 1739 | }, |
| 1740 | { |
| 1741 | "id": "account", |
| 1742 | "title": "Sign in to a Codewhale account (optional)", |
| 1743 | "blocks": [ |
| 1744 | { |
| 1745 | "p": "A provider key and a Codewhale account are different things. The account is for account features only, such as cloud agents and continuing a session from the web app. Installing Codewhale and working locally never need one." |
| 1746 | }, |
| 1747 | { |
| 1748 | "rows": [ |
| 1749 | [ |
| 1750 | "codewhale login", |
| 1751 | "Sign in through your browser with a one-time code." |
| 1752 | ], |
| 1753 | [ |
| 1754 | "codewhale account status", |
| 1755 | "Show which account this profile is signed in to." |
| 1756 | ], |
| 1757 | [ |
| 1758 | "codewhale account logout", |
| 1759 | "Remove this profile's session." |
| 1760 | ], |
| 1761 | [ |
| 1762 | "codewhale account keys list", |
| 1763 | "List provider keys saved in your account. Values are never shown." |
| 1764 | ] |
| 1765 | ], |
| 1766 | "codeTerms": true |
| 1767 | }, |
| 1768 | { |
| 1769 | "p": "`codewhale login` does not accept provider keys; those always go through `codewhale auth set`. The session is kept in your operating system's credential manager when one is available, and in the private Codewhale secrets file otherwise — for example over SSH or in a container." |
| 1770 | } |
| 1771 | ] |
| 1772 | } |
| 1773 | ], |
| 1774 | "next": [ |
| 1775 | { |
| 1776 | "href": "/docs/guide", |
| 1777 | "label": "Start your first task", |
| 1778 | "note": "Open Codewhale in a project and give it something concrete to do." |
| 1779 | }, |
| 1780 | { |
| 1781 | "href": "/docs/modes", |
| 1782 | "label": "Set modes and approvals", |
| 1783 | "note": "Decide whether Codewhale asks before it runs commands." |
| 1784 | }, |
| 1785 | { |
| 1786 | "href": "/docs/trust", |
| 1787 | "label": "See what leaves your machine", |
| 1788 | "note": "What the provider receives, what stays local, and how to turn usage counting off." |
| 1789 | } |
| 1790 | ], |
| 1791 | "sourceNote": "Source documents: docs/INSTALL.md §8, docs/PROVIDERS.md, docs/CODEWHALE_AGENT.md · Update docs-map.ts when changing." |
| 1792 | }, |
| 1793 | "docs-trust": { |
| 1794 | "metaTitle": "See what leaves your machine · Codewhale Docs", |
| 1795 | "metaDescription": "What stays local, what a model provider receives, what usage counting sends and how to turn it off, where the audit log lives, and how to report a vulnerability.", |
| 1796 | "bodyClassName": "text-ink-soft leading-relaxed", |
| 1797 | "title": "See what leaves your machine", |
| 1798 | "lede": "Codewhale runs on your computer and talks to the model provider you choose. This page lists what goes where, what the anonymous usage count contains, and how to switch it off — as built today.", |
| 1799 | "sections": [ |
| 1800 | { |
| 1801 | "id": "boundaries", |
| 1802 | "title": "Where your work goes", |
| 1803 | "blocks": [ |
| 1804 | { |
| 1805 | "rows": [ |
| 1806 | [ |
| 1807 | "Stays on your machine", |
| 1808 | "The runtime, your workspace, session history, snapshots, and the audit log." |
| 1809 | ], |
| 1810 | [ |
| 1811 | "Goes to your provider", |
| 1812 | "The context each turn needs — your messages, the files and tool results Codewhale reads for that turn — goes directly to the provider you selected. There is no Codewhale relay in between." |
| 1813 | ], |
| 1814 | [ |
| 1815 | "Stays local entirely", |
| 1816 | "With a local model (Ollama, vLLM, SGLang), inference never leaves your machine." |
| 1817 | ], |
| 1818 | [ |
| 1819 | "Needs no account", |
| 1820 | "Installing and running Codewhale locally needs no Codewhale account." |
| 1821 | ], |
| 1822 | [ |
| 1823 | "Plan mode", |
| 1824 | "Cannot edit files or run shell commands. Research it is allowed to do may still contact outside services." |
| 1825 | ] |
| 1826 | ] |
| 1827 | }, |
| 1828 | { |
| 1829 | "p": "Tools you add can send data elsewhere: an MCP server, a web search, or a hook runs with your permissions and reaches whatever it reaches. Add only ones you trust." |
| 1830 | } |
| 1831 | ] |
| 1832 | }, |
| 1833 | { |
| 1834 | "id": "telemetry", |
| 1835 | "title": "Know what usage counting sends", |
| 1836 | "blocks": [ |
| 1837 | { |
| 1838 | "p": "Codewhale counts anonymous usage by default and says so the first time you launch it, naming Codewhale and PostHog. Here is exactly what it covers:" |
| 1839 | }, |
| 1840 | { |
| 1841 | "rows": [ |
| 1842 | [ |
| 1843 | "Never sent", |
| 1844 | "Prompts, responses, code, diffs, file contents, file or repository or branch names, paths, model ids, MCP server names, API keys or tokens, error message text, keystrokes, or any per-turn or per-tool timeline." |
| 1845 | ], |
| 1846 | [ |
| 1847 | "Sent while on", |
| 1848 | "Version and platform classes, session length and outcome, feature and error counts as fixed categories, and a random install id that changes every 90 days." |
| 1849 | ], |
| 1850 | [ |
| 1851 | "Where it goes", |
| 1852 | "`https://telemetry.codewhale.net/v1/telemetry`, a first-party service whose source is in the repository. It stores no IP address, country, or location, keeps no request logs, and holds data for three months." |
| 1853 | ], |
| 1854 | [ |
| 1855 | "PostHog", |
| 1856 | "Forwarding to PostHog happens only if the service operator configures it separately; it carries the same fields and nothing more." |
| 1857 | ] |
| 1858 | ] |
| 1859 | } |
| 1860 | ] |
| 1861 | }, |
| 1862 | { |
| 1863 | "id": "turn-off", |
| 1864 | "title": "Turn usage counting off", |
| 1865 | "blocks": [ |
| 1866 | { |
| 1867 | "code": "codewhale config set telemetry false # stop, and erase the local id and buffer\nCODEWHALE_TELEMETRY=0 codewhale # stop for this process, erase nothing", |
| 1868 | "lang": "Terminal" |
| 1869 | }, |
| 1870 | { |
| 1871 | "p": "The config setting is the lasting choice: later versions keep it, and a command-line flag or environment variable cannot turn it back on. You can also switch it in `/settings`. Turning it off deletes what was kept on your machine; rows already sent are keyed only to the random id you just erased, and expire with the three-month window." |
| 1872 | }, |
| 1873 | { |
| 1874 | "p": "To see exactly what would be sent without sending anything, set `telemetry_endpoint = \"\"` in `~/.codewhale/config.toml`. Each batch is then written to `$CODEWHALE_HOME/telemetry/dryrun.jsonl` on your machine, byte for byte, and no network connection is made." |
| 1875 | } |
| 1876 | ] |
| 1877 | }, |
| 1878 | { |
| 1879 | "id": "audit", |
| 1880 | "title": "Check the local audit log", |
| 1881 | "blocks": [ |
| 1882 | { |
| 1883 | "p": "Credential, approval, and elevation events are appended to `$CODEWHALE_HOME/audit.log` (by default `~/.codewhale/audit.log`). Writing is best-effort: if a write fails, the failure is logged rather than hidden. The log never leaves your machine." |
| 1884 | } |
| 1885 | ] |
| 1886 | }, |
| 1887 | { |
| 1888 | "id": "report", |
| 1889 | "title": "Report a vulnerability", |
| 1890 | "blocks": [ |
| 1891 | { |
| 1892 | "p": "Email security reports to the address below instead of opening a public issue. Include your Codewhale version (`codewhale --version`) and steps to reproduce if you have them." |
| 1893 | } |
| 1894 | ] |
| 1895 | } |
| 1896 | ], |
| 1897 | "next": [ |
| 1898 | { |
| 1899 | "href": "/docs/sandbox", |
| 1900 | "label": "Limit what commands can touch", |
| 1901 | "note": "What the operating-system sandbox enforces on each platform." |
| 1902 | }, |
| 1903 | { |
| 1904 | "href": "/docs/modes", |
| 1905 | "label": "Set modes and approvals", |
| 1906 | "note": "Decide what Codewhale may do without asking." |
| 1907 | }, |
| 1908 | { |
| 1909 | "href": "/docs/auth", |
| 1910 | "label": "Connect a provider", |
| 1911 | "note": "Choose who receives your turns — or keep them local with a local model." |
| 1912 | } |
| 1913 | ], |
| 1914 | "sourceNote": "Source documents: docs/public-surface-facts.json (trust), docs/TELEMETRY.md, docs/SANDBOX.md · Update docs-map.ts when changing." |
| 1915 | }, |
| 1916 | "states": { |
| 1917 | "loadingLabel": "Loading…", |
| 1918 | "emptyTitle": "Nothing here yet", |
| 1919 | "emptyBody": "There is no record to show. Nothing has been invented to fill the space.", |
| 1920 | "errorTitle": "This page did not finish loading", |
| 1921 | "errorBody": "Something failed on the way here. Nothing you did was lost; try again, and if it keeps failing, report it.", |
| 1922 | "retry": "Try again", |
| 1923 | "reload": "Reload the page", |
| 1924 | "homeLink": "Back to the home page", |
| 1925 | "docsIndexLink": "Open the documentation index", |
| 1926 | "notFoundTitle": "We all make typos.", |
| 1927 | "notFoundBody": "This page doesn’t exist yet.\nNeither does this game.", |
| 1928 | "notFoundHomeLink": "Return to base", |
| 1929 | "notFoundPosterAlt": "A blue whale in tactical gear on the fictional Codwhale: Modern Whalefare game poster.", |
| 1930 | "unavailableTitle": "The live record has not loaded", |
| 1931 | "unavailableBody": "The source did not answer the last refresh, or this page has not refreshed since it was built. Nothing is shown in its place.", |
| 1932 | "offlineTitle": "You are offline", |
| 1933 | "offlineBody": "Actions are paused until the connection returns. Nothing shown here is refreshing.", |
| 1934 | "reconnectingTitle": "Reconnecting…", |
| 1935 | "reconnectingBody": "Checking the connection (attempt {attempt}).", |
| 1936 | "degradedTitle": "The connection is unstable", |
| 1937 | "degradedBody": "The server did not answer the last check. What you see may be stale.", |
| 1938 | "onlineTitle": "Back online", |
| 1939 | "onlineBody": "The connection is restored.", |
| 1940 | "retryNow": "Retry now", |
| 1941 | "dismiss": "Dismiss", |
| 1942 | "lastChecked": "Last checked {time}" |
| 1943 | }, |
| 1944 | "changelog": { |
| 1945 | "metaTitle": "Changelog · Codewhale", |
| 1946 | "metaDescription": "Codewhale release record: the latest published release, the unreleased source candidate, and the notes for each version, drawn from CHANGELOG.md in the repository.", |
| 1947 | "kicker": "Release record", |
| 1948 | "title": "What changed, and in which version.", |
| 1949 | "lead": "Two facts sit at the top of this page: the newest published release, and the version the source tree currently declares. Everything below is the repository's own CHANGELOG.md, section by section.", |
| 1950 | "publishedLabel": "Latest published release", |
| 1951 | "publishedValue": "{tag} · published {date}", |
| 1952 | "candidateLabel": "Source candidate", |
| 1953 | "candidateValue": "{version} · unreleased", |
| 1954 | "candidateMatches": "{version} · matches the published release", |
| 1955 | "releasesLink": "GitHub Releases ↗", |
| 1956 | "unreleasedHeading": "Unreleased", |
| 1957 | "unreleasedNote": "Changes merged to the main branch since the last tag. They are part of the source candidate, not of any published package.", |
| 1958 | "compareLink": "Compare on GitHub ↗", |
| 1959 | "releasePageLink": "Release page ↗", |
| 1960 | "moreEntries": "{shown} of {total} entries shown", |
| 1961 | "fullNotes": "Full notes in CHANGELOG.md ↗", |
| 1962 | "releaseNotesLink": "Full notes for {version} ↗", |
| 1963 | "emptyTitle": "No release notes were derived", |
| 1964 | "emptyBody": "The build did not find a parsable CHANGELOG.md. The GitHub release list is still the record." |
| 1965 | }, |
| 1966 | "computer-use": { |
| 1967 | "metaTitle": "Computer Use for Mac · Codewhale", |
| 1968 | "metaDescription": "Download and set up Codewhale Computer Use for Mac. Background app control, permission setup, and human Pause and Stop controls.", |
| 1969 | "title": "Computer Use", |
| 1970 | "lead": "Let Codewhale work in your apps while you keep working. The Mac helper brings permissions, background app control, and a way to pause or stop input to your menu bar.", |
| 1971 | "publisher": "By Codewhale", |
| 1972 | "download": "Download for Mac", |
| 1973 | "downloadZip": "ZIP archive (used by the in-app updater)", |
| 1974 | "requirements": "macOS 13.5 or later · Apple silicon and Intel", |
| 1975 | "included": "One app download. No separate Node installation or compiler required.", |
| 1976 | "pendingTitle": "Mac download in preparation", |
| 1977 | "pendingBody": "The public installer will appear here after Apple notarization and release checks are complete.", |
| 1978 | "unavailableTitle": "Download availability could not be checked", |
| 1979 | "unavailableBody": "Refresh this page to try again, or check the published releases below.", |
| 1980 | "releases": "Published releases", |
| 1981 | "receipt": "Download verification details", |
| 1982 | "setup": "Set up your Mac", |
| 1983 | "steps": [ |
| 1984 | { |
| 1985 | "title": "Install the app", |
| 1986 | "body": "Open the disk image and drag Codewhale Computer Use into Applications. Open it from Applications, then choose Computer Use from the whale icon in your menu bar." |
| 1987 | }, |
| 1988 | { |
| 1989 | "title": "Review permissions", |
| 1990 | "body": "Use the setup buttons to open Accessibility and Screen Recording in System Settings. You choose which permissions to grant." |
| 1991 | }, |
| 1992 | { |
| 1993 | "title": "Run the background check", |
| 1994 | "body": "The helper opens a disposable practice window, enters text, and captures that window. It checks whether the pointer or active app changed during the run." |
| 1995 | }, |
| 1996 | { |
| 1997 | "title": "Connect it to Codewhale", |
| 1998 | "body": "Review, trust, and enable Computer Use in Codewhale’s plugin marketplace. Use plugin 0.3.1 or later so local actions go through the helper’s Pause and Stop controls." |
| 1999 | } |
| 2000 | ], |
| 2001 | "controlsTitle": "Keep working. Keep control.", |
| 2002 | "controlsBody": "Supported actions operate on the selected app in the background. Apps and gestures that need foreground control require your authorization. The menu shows the target and input mode; Pause suspends helper input, and Stop ends its existing sessions.", |
| 2003 | "updateTitle": "Updates when you choose", |
| 2004 | "updateBody": "Choose Check for updates from the app. Before installing an update, it checks the download, Codewhale signature, and Apple notarization, and keeps the previous app for recovery.", |
| 2005 | "help": "Setup and troubleshooting", |
| 2006 | "notes": "Release notes", |
| 2007 | "demo": "See the background check", |
| 2008 | "source": "Source and other platforms", |
| 2009 | "platforms": "This download is for Mac. Windows and Linux currently use the source plugin and host-side setup." |
| 2010 | } |
| 2011 | } |
| 2012 |