Issue 2026-08-23
v0.9.11
Codewhaleany model, on your machine
★ GitHub
Codewhale documentation

Find the guidance you need.

Start with the guide and install pages, or go straight to vocabulary, modes, permissions, tools, providers, Fleet, hooks, MCP, and the Runtime API. Each page links to its source document in the repository.

Install CodewhaleBrowse source docs ↗

Getting started

Four steps from one install command to a fleet set up for your work.

  1. Install Codewhale

    One npm command installs the terminal runtime. Cargo, prebuilt archives, Docker, Nix, and China mirrors also work. All of them install published releases.

    npm install -g codewhale
codewhale doctor
    Full install guide →

  2. Open a first session — no key needed

    Starts without any API key. A short setup, then the full interface. Look around in Plan mode, which is read-only. Model replies need a provider — that's the next step.

    codewhale
    Learn the product nouns first →

  3. Connect a provider

    Use a hosted API key, a gateway, or a local runtime with no key (Ollama, vLLM, SGLang). You pick the provider and the model. A model name never switches the provider for you.

    codewhale auth set --provider deepseek
    Providers and models →

  4. Set up your ideal fleet

    Add each provider you use with one auth set (local runtimes need none). Then run /fleet setup. It goes one member at a time — a semantic role, a model from any configured provider, a thinking tier, then an exact identity/route review — and saves the roster profile for this repo or for every repo on this machine. Runtime permissions stay separate. A single task needs none of this.

    /fleet setup
codewhale fleet status
    Fleet and Workflow docs →

Watch a real session

A recording of a real session will go here. There is no recording yet, so nothing is shown.

Recording pending release candidate

There is no recording yet. When there is, it goes here with captions, a transcript, and an optional GIF download.

A real Codewhale session, end to endInstall, a first session with no key, connecting a provider, and one Fleet workflow on a local model. To be recorded from a release build.Recording plan and acceptance checklist ↗

Where next

Hooks

Run your own commands before and after tool calls, at turn end, and on session events, with per-project trust rules.

Modes and permissions

Plan / Work / Operate and Ask / Auto-Review / Full Access: what each one allows.

Documentation hub

Every topic, searchable. Each page links to its source document in the repository.

Source documents: docs/GUIDE.md, docs/KEYBINDINGS.md · Step copy lives in web/lib/content/getting-started.ts; update docs-map.ts when changing.