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.