# Crew command reference

> Look up Crew commands, run flags, spending limits, continuation grants and recorded phases before starting or recovering a coding run.

Source: https://kaitoi.io/docs/cli/crew-reference/
Section: Kaitoi CLI / Subagents and Crew
Written for: Operators starting or recovering a Crew run.
Prerequisites: CLI 0.9.0 and a trusted repository
Last reviewed: 2026-10-26

---

> These guides describe CLI 0.9.0, which is not yet released. Check `kaitoi --version` before following them. In older releases, `code acp` and `code serve` can be interpreted as model prompts instead of commands. See [installation and release status](/docs/cli/install/).


Use `kaitoi crew COMMAND --help` to inspect a command without starting work.
Run IDs are positional on every run-specific command. Preserve `--repo` and
any custom `--state-dir` when returning to a run.

## Commands

| Command | Purpose |
| --- | --- |
| `run "TASK"` | Start a task with explicit engines, checks and limits |
| `status RUN_ID` | Read current phase, state version and recovery command |
| `progress RUN_ID` | Read progress |
| `result RUN_ID` | Read the final outcome |
| `evidence RUN_ID` | Locate the evidence JSON with check commands and findings |
| `steer RUN_ID` | Add an instruction for a later boundary |
| `pause RUN_ID` | Stop the running activity and hold the run |
| `resume RUN_ID` | Relaunch the paused activity with remaining authority |
| `interrupt RUN_ID` | Stop work and require operator intervention |
| `cancel RUN_ID` | End the run permanently; preserve its candidate branch |
| `continue RUN_ID` | Grant bounded additional capacity to eligible held work |
| `service start`, `service attach`, `service stop` | Manage the workspace service |

Mutations require `--expected-state-version N` from fresh status. Steer takes
`--instruction TEXT`. Continue with the exact command printed by status;
do not guess which grants a held run needs. Direct read commands have no
`--json` option. The service owns background work, not the terminal watching it.

## Run flags

Supply a task argument or `--task-file FILE`, never both. A new run requires
`--implementer` and `--implementer-commands allowed|denied`, plus at least one
test, build or smoke command. A Penny implementer cannot run commands.

| Flag | Meaning or default |
| --- | --- |
| `--repo DIRECTORY` | Canonical project root |
| `--task-file FILE` | UTF-8 task text |
| `--implementer BACKEND[:MODEL]` | Claude, Codex or Penny; Penny can include provider and model |
| `--implementer-commands allowed\|denied` | Command authority in the candidate, sandboxed without network |
| `--planner`, `--reviewer`, `--tester` | Optional Claude or Codex role, optionally with model |
| `--tester-entrypoint ID=COMMAND` | Repeatable offline command prefix for a tester |
| `--max-smoke-design-attempts N` | Default 2, range 1–4 |
| `--allow-tester-degradation` | Allow tests-only fallback if the configured tester fails |
| `--test-command`, `--test` | Repeatable exact test command |
| `--build-command`, `--build` | Repeatable exact build command |
| `--smoke-command` | Repeatable exact smoke command |
| `--verification-timeout N` | Per-command seconds, default 600 |
| `--verification-environment locked\|disabled` | Default locked dependency preparation |
| `--verification-network registry\|denied` | Default registry-only preparation access |
| `--allow-lifecycle-scripts` | Future admitted preparation recipe permission; current npm recipe still ignores scripts |
| `--allow-lockfile-repair` | Supported lockfile-only repair, with scripts disabled |
| `--branch NAME` | Candidate branch from current HEAD |
| `--state-dir DIRECTORY` | Durable state; relative paths resolve under the repo |
| `--operator-id TEXT` | Nonsecret audit identity, default local-cli-operator |
| `--max-seconds N` | Wall-clock limit, default 15,000 |
| `--max-plan-attempts N` | Default 2 |
| `--max-protocol-repairs N` | Default 1 |
| `--max-implementation-cycles N` | Default 3 |
| `--max-transient-retries N` | Default 1 |
| `--max-model-dispatches N` | All-role model launches, default 12 |
| `--max-role-dispatches N` | Launches for one role, default 6 |
| `--max-agent-seconds N` | One activity reservation, default 3,600 seconds |
| `--max-automatic-continuations N` | Consecutive automatic continuations, default 6; 0 disables |
| `--max-reported-tokens N` | Total reported token cap, unset by default |
| `--max-input-tokens N`, `--max-output-tokens N` | Separate caps, unset by default |
| `--max-cache-read-tokens N`, `--max-cache-write-tokens N` | Separate cache caps, unset by default |
| `--max-credits N` | Kaitoi credit cap for Penny, unset by default |
| `--max-known-cost AMOUNT` | Provider-reported cost cap, unset by default; unknown cost stays unknown |
| `--cost-currency CODE` | Default USD |
| `--reserved-output-tokens N` | Per-launch reservation, default 16,384 |
| `--max-session-tokens N` | Repair-session rotation threshold, default 250,000 |
| `--quiet` | Lifecycle, failures and summary only |
| `--background` | Return an accepted ID while the service continues |
| `--no-mirror` | Keep changes out of the original checkout; mirroring is otherwise on |
| `--service-terminal-grace N` | Service lifetime after terminal work, default 300 seconds |

Token and cost caps measure reported usage and reservations. Delayed or unknown
provider usage remains possible; read evidence before extending a paid run.

## Continue with explicit grants

`continue` requires the current state version. Capacity flags add to existing
allowances: `--grant-seconds`, `--grant-implementation-cycles`,
`--grant-plan-attempts`, `--grant-protocol-repairs`, `--grant-transient-retries`,
`--grant-model-dispatches`, `--grant-role-dispatches`, `--grant-reported-tokens`,
`--grant-input-tokens`, `--grant-output-tokens`, `--grant-cache-read-tokens`,
`--grant-cache-write-tokens`, `--grant-credits` and `--grant-known-cost`.

Preparation recovery may use `--grant-registry-network`,
`--allow-lifecycle-scripts` or `--allow-lockfile-repair`. `--instruction` adds
bounded direction; `--repair-candidate` requests repair of the preserved
candidate. These flags authorize work; they do not merely dismiss an error.

## Phases and outcomes

| Phase or outcome | Interpretation |
| --- | --- |
| `created`, `preflight`, `domain_context` | Prepare and inspect the task |
| `plan`, `plan_validate`, `plan_repair`, `plan_revise` | Construct and validate a plan |
| `implement`, `code_repair` | Change the isolated candidate |
| `verification_prepare`, `verification_plan_revise`, `verify`, `test_assess` | Prepare and exercise checks |
| `review`, `finalizing`, `complete` | Review and finish; inspect the final result |
| `pausing`, `paused` | Current activity stops; resume launches it again |
| `interrupting`, `awaiting_operator` | Operator action is needed |
| `blocked`, `awaiting_manual_verification` | Read the recorded reason and required evidence |
| `failed`, `cancelling`, `cancelled` | Failure or cancellation; inspect preserved work |

Final result status uses `completed`, `completed_with_waivers`,
`awaiting_manual_verification`, `blocked`, `paused`, `awaiting_operator`,
`failed` or `cancelled`. A phase and a final outcome identify different things.