Your first Crew run.

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

/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.

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 before starting alongside other work.

#Start directly from the terminal

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

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.