Install and use Codewhale
Find installation steps, model setup, tool configuration and troubleshooting. The guides include commands and examples you can run.
By task
27Start from what you are trying to do.
One command on macOS or Linux; npm, Cargo, release binaries, and the Homebrew tap on Linux also work.
Open Codewhale in a project, look around in Plan, then let it edit in Work.
Save a key for DeepSeek, Anthropic, OpenAI, Google or another provider, or run a model yourself with no key.
Sign in to an existing account from the web, the desktop app, or the terminal, and sign out again.
Supported providers, switching mid-session, and local runners.
Plan, Work, or Operate; Ask, Auto-Review, or Full Access; and how to answer a prompt.
See every edit, roll files back to an earlier turn, and get a code review before you push.
Read a redacted request manifest without sending or changing session state.
Return LSP errors after edits and configure custom servers by file extension.
Read rule sources, matchers and scope; understand allow, ask and deny precedence.
Find SKILL.md folders, import into owned roots and control invocation.
Keep compatible instructions and skills, and review a settings import plan.
Read a session receipt of commands, file changes, tools and approval decisions.
Turn on pet mode in each terminal to see which session is working, waiting for you, done, or failed.
Write a repeatable Workflow, run it as a Lane, and watch or stop it from any terminal.
Roles, separate worktrees for parallel edits, and how to watch sub-agents.
Add a local or remote MCP server, sign in with OAuth, or serve Codewhale over MCP.
Let the model compose several tool calls — MCP and plugin tools included — in one short program, under the same approvals as direct calls. Experimental, on by default.
Block a risky command, add context, or get notified when Codewhale waits for you.
See which OS sandbox your platform has and turn on bubblewrap on Linux.
Run one-shot jobs in CI, or drive threads and approvals over the local HTTP API.
Work in a local browser tab, or continue a session from the web app with /rc.
Diagnose in one command, then fix install, key, network, and stuck-turn problems.
What a provider receives, what usage counting sends, and how to turn it off.
Search the HTTP routes, request fields and event contracts in the repository's main branch.
Create a two-file skill bundle and check its explicit greeting marker after review and activation.
Follow the full task file tutorial and validate its structure and configured route before launching workers.
By topic
30Get started
8Open a terminal, install, pick the folder Codewhale works in, connect a model and finish a first task.
Details
docs/GUIDE.md, docs/INSTALL.md, docs/MODES.md, docs/SANDBOX.md, docs/KEYBINDINGS.md
The installer, npm, Homebrew tap, Cargo, and release binaries, with the output each step prints.
Details
docs/INSTALL.md
Install, connect a model, and give Codewhale a task in your project.
Details
docs/GUIDE.md, docs/INSTALL.md, docs/KEYBINDINGS.md
Save a provider key, check which key is used, or run a local model.
Details
docs/INSTALL.md, docs/PROVIDERS.md, docs/CODEWHALE_AGENT.md
Sign in to an existing account from the web, the desktop app, or the terminal, sign out, and find data export and deletion.
Details
docs/CONFIGURATION.md, docs/PROVIDERS.md
Supported providers, switching models, and running a model yourself.
Details
docs/PROVIDERS.md, docs/MODEL_LAB.md
Find the config file, change settings from the session or shell, and see what a repository may override.
Details
docs/CONFIGURATION.md, docs/LEGACY_PATHS.md
Keep compatible instructions and skills, and review settings and MCP imports without running other agents' plugin runtimes.
Details
docs/CLAUDE_PLUGIN_COMPAT.md, docs/CONFIGURATION.md
Work with Codewhale
8Choose Plan, Work or Operate, and choose when Codewhale asks for approval.
Details
docs/MODES.md
See every edit, roll files back to an earlier turn, get a code review, and keep a review receipt.
Details
docs/RECEIPTS.md, docs/CONFIGURATION.md
Follow the goal, To-do list, and sub-agents in the workbar, and hand work to a fresh session.
Details
docs/TOOL_SURFACE.md, docs/TOOL_LIFECYCLE.md
A whale view per terminal that shows working, waiting for you, done, or failed, with replies and agents one key away.
Details
docs/PET_MODE.md
Hand independent parts of a task to sub-agents, pick roles, and keep parallel edits in worktrees.
Details
docs/SUBAGENTS.md, docs/FLEET.md, docs/MODES.md
Save roles in a Fleet, write a repeatable Workflow, run it as a Lane, and run batches of tasks.
Details
docs/FLEET.md, docs/FLEET_WORKFLOW_TUTORIAL.md, docs/WORKFLOW_AUTHORING.md
The OS sandbox on macOS, Linux, and Windows, how to turn it on, and how much a command may write.
Details
docs/SANDBOX.md, docs/AUTHORIZATION_ORDER.md
What stays local, what a provider receives, what usage counting sends, and how to turn it off.
Details
docs/SANDBOX.md, docs/AUTHORIZATION_ORDER.md, docs/TELEMETRY.md, docs/public-surface-facts.json, docs/PREVIEW_REQUEST.md
Extend and automate
8Add a connector: a local (stdio) or remote (HTTP) MCP server. Sign in with OAuth, serve Codewhale over MCP, and try code mode.
Details
docs/MCP.md
Add a hook that runs your own script at session start, before a tool call, at turn end, or when Codewhale waits for you.
Details
docs/HOOKS.md, docs/CONFIGURATION.md
Install, find, trust, and load reusable instruction packages. A skill can come on its own or inside a plugin.
Details
docs/SKILLS.md, docs/CLAUDE_PLUGIN_COMPAT.md
Choose plugin formats, browse catalog examples, and review, trust and enable plugin bundles. A bundle can carry skills, connectors and hooks.
Details
docs/PLUGINS.md, docs/PLUGIN_BUNDLES.md, docs/PLUGIN_MARKETPLACE.md, docs/EXTENSIONS.md
Run one-shot jobs from scripts, or drive threads, events, and approvals over the local HTTP API.
Details
docs/RUNTIME_API.md
Work in a local browser tab, or continue a terminal session from the web app with /rc.
Details
docs/WEB.md
Follow the full task-specification tutorial, including validation, launch and recovery.
Details
docs/FLEET_WORKFLOW_TUTORIAL.md
Build, inspect and activate a two-file skill bundle with a visible greeting check.
Details
docs/PLUGIN_AUTHORING.md
Get help
2Diagnose in one command, then fix install, key, network, stuck-turn, session, and MCP problems.
Details
docs/INSTALL.md, docs/OPERATIONS_RUNBOOK.md, docs/DOCKER.md
The contributing guide, agent ethos, contributor credits, and release process.
Details
CONTRIBUTING.md, docs/AGENT_ETHOS.md, docs/CONTRIBUTORS.md, docs/RELEASE_CHECKLIST.md
Reference
4Read the HTTP routes, request fields and event contracts in the repository.
Details
docs/RUNTIME_API.md, docs/RUNTIME_ROUTES.md
Understand Fleet, Workflow, Lane and Runtime, plus the modes and permission postures.
Details
docs/FLEET.md, docs/MODES.md, docs/public-surface-facts.json
The rules the agent follows: built-in rules, your personal constitution, and a repository's own.
Details
docs/ARCHITECTURE.md
The small set of tools every session starts with, and how Codewhale finds the rest.
Details
docs/TOOL_SURFACE.md, docs/RUNTIME_SIMPLIFICATION_DESIGN.md, docs/LSP_PHP_CUSTOM.md
Web guides open on codewhale.net. Source docs open the full reference in the GitHub repository.