Run a workflow

Save roles in a Fleet

Your Fleet is the list of roles Codewhale can hand work to, and the model each role uses. Set it up once inside a session:

/fleet setup
/fleet
/fleet saved

/fleet setup walks you through a role, its model (or “use the session's model”), and where to save it: this project, or your personal profile for every repository. You review the exact file before it is written. /fleet shows the members of the selected Fleet, and /fleet saved switches between named Fleets.

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 Workflow is a JavaScript file in your repository's workflows/ folder. It describes steps; it does not do the work itself. This one reviews two areas in parallel, then combines the findings. Save it as 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."
      }
    }
  ]
});

Steps can be agent, branch, sequence, reduce, loop_until, cond, expand, and teacher_review. A workflow file has no file, shell, or network access of its own, and import, fetch, eval, and async are rejected. The agents it starts do the real work, under your normal permissions.

Note: One run can start up to 1,000 agents, with at most 16 working at once; the rest wait for a slot. Loops must declare max_iterations.

Run it

codewhale workflow run docs-readiness --runtime inline
codewhale workflow run docs-readiness --goal "prepare the 1.2 release" --verify

Codewhale finds workflows/docs_readiness.workflow.js from the name, checks it, and starts it. --runtime inline runs it in this terminal. The default, tmux, runs it in a detached tmux session that keeps going after you close the terminal. --verify runs the verification gates after a successful finish, and --fleet <name> uses a named Fleet instead of the built-in roles.

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 starts a workflow and /workflows lists or cancels the runs in that session.

Watch and stop a run

Each run is a Lane. Lanes are saved to disk, so you can check on them from any 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 and print a machine-readable receipt. In a session, /lane offers the same controls with the same results.

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.

codewhale fleet init
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 status counts queued, running, finished, and failed work from this workspace's run record. fleet resume picks a run back up after the laptop slept or the manager exited, without starting a new one. For the agents attached to your current session only, use /fleet workers (or /subagents).

Next