# Your first Crew run

> Define a bounded coding task for Crew, choose its engines and verification commands, and review workspace preparation, checkout mirroring, and budgets.

Source: https://kaitoi.io/docs/cli/crew/
Section: Kaitoi CLI / Subagents and Crew
Written for: Code users delegating a longer implementation task.
Prerequisites: Kaitoi CLI installed and signed in for Code's managed tools; A trusted workspace and any required external engine installed and authenticated
Last reviewed: 2026-10-24

---

Crew carries a bounded coding task through implementation and configured checks
in a durable run. It can keep working after the interactive conversation ends.
Start with a concrete outcome and a real verification command. This guide covers
CLI **0.9.0**.

## Write an acceptance brief

Describe the behavior to change, files or areas in scope, existing work to
preserve, and how success will be checked. For example:

> Add an empty state to the saved-search page. Keep the existing search behavior.
> Verify the component tests and production build. Report the changed files and
> any unresolved failures. Keep the candidate out of my checkout.

Choose commands that actually exist in your project. A run needs at least one
test, build, or smoke command. A named tester role also needs a verification
entrypoint; merely assigning a tester does not define what it should test.

## Configure the run in Code

```text
/run config
/crew Add the empty state described in the acceptance brief
```

The configuration editor sets roles, bounds, verification, and preparation.
Opening or saving it does not start a run or consume model tokens. Project
settings can include verification; global defaults cover roles, budgets, and
preparation. Review the resolved start proposal even when you have saved defaults.


A run brief names the outcome. Its admission sheet adds the repository,
implementer and optional reviewer or tester, verification commands, preparation
permissions, and bounded time or spending authority. Checkout mirroring is a
separate choice and is on by default. Review these values before starting. An
accepted run ID means work was admitted, not that the checks passed.

The fictional assignment changes an empty search-results area into a useful message. The work area shows implementer, review and verification boundaries; admission issues a run identity without claiming the intended interface has been delivered.

*Figure: A Crew start proposal turns an outcome into explicit authority and checks.*

The implementer can use Claude, Codex, or Penny. Optional planner, reviewer, and
tester roles use supported external engines. Configure their installed clients
and authentication first. External engines use their own account arrangements;
Kaitoi login alone does not authenticate them.

## Check the workspace and preparation

An existing Git repository normally needs a clean checkout and its canonical
repository root. An explicit `ignore_uncommitted` admission can exclude dirty
work; it does not copy those edits into the candidate. Crew refuses unsupported
nested-root and symlinked-Git arrangements.

Crew can also initialize an eligible missing or empty directory. The direct
CLI can admit a directory containing only the exact supplied task file; Code's
path without a task file needs an empty directory apart from allowed operating
system metadata. Initialization creates Git metadata, a main branch, and a base
commit, and appears in the approval proposal. A non-Git folder containing an
ordinary project is not treated as empty.

Preparation can be disabled or locked to approved dependency behavior. Package
registry access, lifecycle scripts, and lockfile repair are separate authority
choices. Do not widen them just to make a failing setup disappear.

Crew always uses a private worktree, but **checkout mirroring is enabled by
default**. Eligible changes can appear in your original checkout as unstaged
files. Disable mirroring in the proposal when you want a private candidate only.
See [results and mirroring](/docs/cli/crew-results/) before starting alongside
other work.

## Start directly from the terminal

For a Python project whose verification command is `python -m pytest -q`:

```bash
kaitoi crew run "Add the agreed empty state and verify it" \
  --repo /path/to/project \
  --implementer codex \
  --implementer-commands allowed \
  --test-command "python -m pytest -q" \
  --background --no-mirror
```

Replace the task, path, and check with your project's actual values. Supply a
task argument **or** `--task-file PATH`, not both. Command authority permits
implementation commands; it is a substantive choice. `--no-mirror` keeps this
run's changes out of the original checkout. `--background` returns an accepted
run ID before the task finishes.

## Keep the run bounded and inspect its result

Review time, dispatch, token, cost, and automatic-continuation allowances.
Provider usage may arrive after an activity, and unknown costs remain unknown;
a bound is not a guaranteed final bill. Start only the scope you intend.

Save the run ID. Use `/run status`, `/run progress`, `/run result`, and
`/run evidence` to inspect that same run. An interrupted or budget-limited run
may contain useful saved work without verified completion. A completed run and
its candidate still need integration and any separately intended release steps.