ReleaseLatest release v0.10.2 · 24 oct. 2026These pages describe v0.10.2, the published release.Changelog →

Run a workflow

In Work, ask Codewhale to plan a larger task and delegate independent steps to agents. Write a Workflow when you want to repeat an ordered plan with phases, parallel branches and a record of each run.

Save roles in a Fleet

Fleet keeps reusable roles and model choices. Connect a model first, then create a role profile inside a session:

Codewhale

/fleet setup
/fleet
/fleet saved

/fleet setup saves one role profile at a time. Choose its model or inherit the session route, then choose this project or your personal profiles. Review the exact file before saving. /fleet shows the selected team; /fleet saved switches among named teams that already exist. Ask for a task and use /fleet workers to watch its session agents.

A Fleet only chooses who does the work. What a worker may read, write, or run still comes from your workspace trust, approval setting, and sandbox.

Write a workflow

A saved Workflow describes a process the agents can repeat. Create a workflows/ folder and save this declarative example as workflows/docs_readiness.workflow.js. It reviews two areas in parallel, then combines the findings. Replace src and docs with directories that exist in your project:

workflows/docs_readiness.workflow.js

export default workflow({
  "id": "docs-readiness",
  "goal": "Review the docs and code for gaps, then summarize the next edit",
  "nodes": [
    {
      "branch": {
        "id": "parallel-review",
        "parallel": true,
        "children": [
          { "agent": { "id": "code-review", "prompt": "Inspect src/ for undocumented behavior.",
                       "agent_type": "review", "mode": "read_only", "file_scope": ["src"] } },
          { "agent": { "id": "docs-review", "prompt": "Inspect docs/ for stale or missing steps.",
                       "agent_type": "review", "mode": "read_only", "file_scope": ["docs"] } }
        ]
      }
    },
    {
      "reduce": {
        "id": "summary",
        "inputs": ["code-review", "docs-review"],
        "prompt": "Combine the findings into the safest next edit."
      }
    }
  ]
});

This declarative form supports agent, branch, sequence, reduce, loop_until, cond, expand, and teacher_review. It compiles to a validated plan and rejects constructs such as import, fetch, eval, and async. Advanced imperative JavaScript can use asynchronous task() and parallel() in a sandbox, still without direct filesystem, shell or network access. Workers perform those actions under the active policy.

Note: Workflow caps how many agents are live at once, and admitted work waits for a slot. There is no default cumulative child limit or structural depth limit. Set positive [workflow] max_children or max_depth values to limit them. Runtime agent admission and delegation limits apply separately. Loops must declare max_iterations.

Run it

Terminal

codewhale workflow run docs-readiness --runtime inline

This command finds workflows/docs_readiness.workflow.js, validates it and starts a model-backed run, so connect your provider first. --runtime inline waits in this terminal. The default backend requires tmux installed on the host and runs in a detached session. Add --verify to the launch command for the configured verifier gates after a successful finish. --fleet <name> selects an existing named Fleet.

To keep the work off your checkout, add --worktree-repo . --branch <name>: the run gets its own git worktree and branch.

Inside a session, /workflow <objective> drafts a proposal without executing it. To review this saved file, use /workflow run workflows/docs_readiness.workflow.js. Wait for the review, then run /workflow confirm to start the reviewed draft. /workflow status reads run state, /workflow cancel <run-id> cancels, and /workflows opens the session run dashboard.

Watch and stop a run

Each run is a Lane. Lanes are saved to disk, so you can check on them from any terminal:

Terminal

codewhale lane list
codewhale lane status <lane-id>
codewhale lane logs <lane-id>
codewhale lane attach <lane-id>
codewhale lane interrupt <lane-id>

lane list, lane status, and lane interrupt accept --json. Inside a session, use /lane list, /lane status <lane-id>, or /lane interrupt <lane-id>. Logs and tmux attachment use the shell commands above. Slash reads show the last recorded state; CLI list/status reconcile backend exits. Slash interrupt first returns a queued receipt, then its final result.

Run a batch of tasks

When you have a list of separate tasks rather than one plan, write them as a task file and run them as a Fleet run. Each task names its goal, its role, and the paths it may write. The tutorial has a complete tasks.json.

Terminal

codewhale fleet init
codewhale fleet run tasks.json --check
codewhale fleet run tasks.json --max-workers 4
codewhale fleet status
codewhale fleet logs <worker-id>
codewhale fleet resume <run-id>
codewhale fleet stop --all

fleet run --check validates without creating a run; omit --check to start the foreground manager. Use another terminal for status and controls while it runs. After an interruption, fleet resume <run-id> reconciles stale leases and reports their state; it does not restart the manager or launch queued work. To explicitly retry a worker, inspect it and use codewhale fleet restart <worker-id>, which runs the manager for that run. /fleet workers and /subagents show current-session agents, not these durable runs.

Next

Read the full Fleet tutorial

Validate a complete task file and inspect recovery behavior before starting workers.

Run agents in parallel

Hand independent pieces of one task to sub-agents without writing a workflow.

Review what changed

Check the diff a run produced and get a review before you push.

Product terms

Fleet, Workflow, Lane, and Runtime, each in one sentence.