Codewhale
GitHub
Codewhale documentation

Find the guidance you need.

Start with the getting-started guide and installation, or go straight to vocabulary, modes, permissions, tools, providers, Fleet, hooks, MCP, and the Runtime API. These pages are the product documentation; each one cites the source documents in the repository for full detail.

Install CodewhaleBrowse source docs ↗

Getting started

Four steps from one install command to a first Fleet workflow. Every step states only what the current candidate actually does; anything unreleased or unrecorded is labeled as such.

  1. Install Codewhale

    One npm command installs the dispatcher and the terminal runtime. Cargo, prebuilt archives, Docker, Nix, and China mirrors are documented alternatives; every channel serves published releases only.

    npm install -g codewhale
codewhale doctor
    Full install guide →

  2. Open a first session — no key needed

    The runtime launches without any API key: a short constitution-first setup (language, provider readiness, runtime posture, your constitution), then the full interface. Explore in Plan mode — it is always read-only. Model replies need a provider; that is the next step.

    codewhale
    Learn the product nouns first →

  3. Connect a provider

    Pick any supported route — a hosted key, a gateway, or a keyless local runtime such as Ollama, vLLM, or SGLang for fully local inference. Provider and model stay explicit; requested and effective reasoning plus routing source are separate provenance fields, and unavailable values stay unavailable.

    codewhale auth set --provider deepseek
    Providers and models →

  4. Run a first Fleet workflow

    When work needs durable workers, ordered phases, or receipts, author a reusable agent-team profile and launch a run. Fleet state lives in the workspace ledger and survives restarts; ordinary single tasks need none of this.

    codewhale fleet init
codewhale fleet run tasks.json --max-workers 4
    Fleet and Workflow docs →

Watch a real session

Below is the real-session media slot. It is deliberately in the pending state: until the v0.9.2 candidate dogfood recording exists, this site shows no placeholder or staged footage.

Recording pending release candidate

No placeholder or staged footage is shown here. When the recording exists, the real session ships with a poster frame, bilingual captions, a transcript, and an optional GIF fallback download.

A real Codewhale session, end to endWill be recorded from the v0.9.2 release candidate during dogfood: install, first offline session, provider connection, and one Fleet workflow on a sealed local route. Until that recording exists, no footage is shown here — the manifest and budgets above are the contract it must satisfy.Recording plan and acceptance checklist ↗

Where next

Hooks

React to lifecycle events — before and after tool calls, on turn end, on session events — with project-local trust rules.

Modes and permission postures

Plan / Act / Operate and Ask / Auto-Review / Full Access, exactly as the runtime enforces them.

Documentation hub

Every topic, searchable, each page citing 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.