How to use Codewhale: install, run tasks and review changes

Install Codewhale on macOS, Linux or Windows

On macOS and Linux, run the install script from the README. It places the codewhale command and its short alias codew in ~/.local/bin. If your shell then reports command not found, run the PATH line the installer prints. Codewhale can be updated later with codewhale update.

On Windows, the README lists winget, Scoop and the installer from GitHub Releases. npm and Cargo work on any platform that has them. Use only one install method per machine, because two copies on PATH cause confusion.

• Prerequisite: Git, since the agent is meant to run from a git repository.
• Prerequisite: an API key for a provider you choose, or a local runtime such as Ollama.

Connect a model provider

Start Codewhale from the root of a git repository with the codewhale command. Then run /provider, or press F3, pick a provider, paste its API key and choose a model. DeepSeek is the default provider. If you want to use a local model instead, pick a local runtime.

If no provider is configured and Ollama is already serving a chat model, Codewhale uses it automatically. From version 0.10.2 it offers Ollama when you send your first message. Codewhale supports more than 40 built-in providers, and any OpenAI-compatible endpoint works.

• Use /model to switch models between turns.
• Use /model auto to pick a model for each turn.

Run your first task

Commit or stash your work first. Codewhale applies file edits in your repository without asking by default and shows you the diff. Describe the task in plain language in the message box.

Read-only commands run straight away. For any other shell command, Codewhale asks first. Answer y to run it once, a to allow similar commands for the rest of the conversation, or n to refuse. Use /undo to take back your last request and its file changes, and /help to list commands and keys.

Choose a mode and permission level

A fresh install starts in Work mode with the Ask permission. Press Tab when the input is empty, or use /mode, to change mode. Plan mode reads and searches but changes nothing. Work mode edits files and runs commands. Operate mode has the same access as Work and keeps going until the goal is verified or it needs your input.

Press Shift+Tab to change permission. Ask applies edits in your repository and asks before non-read-only shell commands. Auto-Review lets rules and a reviewer model approve routine calls. Full Access never asks and turns off Codewhale's sandbox, so use it with care. The modes and permissions guide in the docs has the details.

• Plan: reads and searches only.
• Work: edits files and runs commands.
• Operate: works toward a goal until verified or blocked.
• Ask: the default permission, with approval for shell commands.
• Full Access: no prompts and no sandbox.

Review what the agent changed with /receipts

The /receipts command lists the files changed, the commands run, the web and MCP calls made, the agents started, approvals and who gave them, and any failures. After you quit, run codewhale receipts --last to see the same record.

Use /undo to revert your last request and its file changes in one step. /restore rolls the whole workspace back to an earlier snapshot, but it overwrites later edits, so it needs /trust on or Full Access.

Run a task in scripts or CI with codewhale exec

codewhale exec runs one task without the interface, which suits scripts and CI. By default, --auto uses Full Access: tools run without asking, shell commands have no Codewhale sandbox, and trust mode lets file tools write outside the workspace. To keep the shell sandbox and workspace restrictions, add --sandbox workspace-write, which also keeps trust mode off.

• Answer-only and --json runs are saved to receipts only when resuming or when conversation compaction starts. Use --output-format stream-json to always save them.