Codewhale
GitHub
CodewhaleMIT

An ocean of data and code

Dive into the deep
so you don't have to.

Codewhale gives ordinary people the leverage of LLMs to build things. In your terminal it reads the repo, edits files, runs checks, and leaves a receipt — without assuming you already speak code. It runs on your machine.

InstallDocsGitHub
npm install -g codewhale

Latest release v0.9.3 · Current source v0.9.3: 36 provider routes · MIT

Codewhale TUICurrent session
Current Codewhale terminal session showing Operate mode, the whale, composer, and footer
Current Codewhale session · Operate mode · Ask permission posture

An underwater terminal shell. Model-neutral. Local-first.

Bring the hosted, gateway, or local model you already use. Codewhale runs on your machine and treats the model as a selectable component—not the product. Plan / Act / Operate and explicit permission postures keep the deep dive under your control.

From task to verified change.

  1. 01

    Inspect

    Read the repository, its instructions, and the task.

  2. 02

    Act

    Edit files through explicit approval boundaries.

  3. 03

    Verify

    Run checks and inspect the result.

  4. 04

    Report

    Leave a concise, durable receipt.

$ codewhale exec "fix the failing test"inspect   repository and instructionsact       edit through the selected permission postureverify    cargo test --lockedreport    checks passed · receipt saved

New to Codewhale? Four steps end to end.

Install → a first keyless session → provider connection → a first Fleet workflow. The nouns are defined on the vocabulary page.

  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 →
Read the getting-started guide →See the product vocabulary →

Your model.
Your boundaries.

Choose the model, working mode, and permission posture explicitly. Unknown cost stays unknown, and preview surfaces stay labeled as such.

36 provider routes
Hosted, gateway, and local models
Plan · Act · Operate
Read-only planning through autonomous operation
Ask · Auto-Review · Full Access
Choose the permission posture for the work
TUI · exec · web · API
Interactive and headless runtime surfaces

Use the runtime where the work happens.

TUIInteractive terminal work
codewhale execScripts and CI
Web clientLoopback-only browser client
Runtime API + MCPLocal integrations
FleetDurable multi-agent work
See runtime surfaces and stability notes →

Start with one command.

npm install -g codewhale

Cargo · Binaries · Docker · Nix · Windows · Android / Termux · China mirrors

Read the install guide →

Built in public

MIT-licensed and shaped by contributors across runtimes, providers, platforms, documentation, and tests.