Crew
Crew hands a coding task to cheap or local models in a private copy of your project, with two workflows: Supervised and Self-managed. KodaCode runs the checks itself and applies passing work uncommitted.
Crew has two workflows. Each workflow has its own command and its own settings.
| Workflow | Command | Who plans and judges | Who writes the code |
|---|---|---|---|
| Supervised | /crew-supervised <task> | A leader model that you choose, usually a frontier model | A cheap worker model |
| Self-managed | /crew-self-managed <task> | The worker model, as a manager | The same worker model |
Use Supervised when a strong model should plan the work and judge the results. Use Self-managed when no frontier model should run at all.
Set it up
Open Preferences → Crew Workflow. Each workflow has its own section. See Crew Workflow settings.
- Supervised needs a Leader model and a Worker model.
- Self-managed needs a Worker model.
- Without them, the command opens the settings page and runs nothing.
KodaCode refuses to start a crew, and says why, in these cases:
- The project is not inside a git repository.
- The repository has no commits.
- A merge, rebase, cherry-pick or revert is in progress.
- The working tree has unresolved conflicts.
The private copy
- Each job runs in a git worktree under
.koda/worktrees/crew-<id>/. The worktree starts from the current state of your project, uncommitted and untracked work included. - Your own files do not change while a job runs.
- KodaCode links the Dependency folders (for example
node_modules) into the copy. It does not copy them. - Each job also has a folder in
.koda/crew/<id>/for its record and logs. - When a job lands, or when you apply or discard it, KodaCode removes its worktree and its folder. A job that waits for your decision keeps both.
Supervised
Type the command and the task in any session:
/crew-supervised Retry outgoing webhooks on 5xx and timeouts with backoff, and stop at once on 410
The Leader model runs every turn of this conversation from then on, whatever model the session uses. Each message you send later is also a leader turn, and KodaCode adds it to the request that the worker checks its task against. Start a new conversation to leave Crew.
What the leader can do
The leader cannot read, search or edit code. It has four tools:
| Tool | What it does |
|---|---|
task | Sends one change to a worker and returns a short verdict. |
research | Asks a read-only worker a question about the code. The answer gives file:line references. |
crew_status | Lists, shows or stops the jobs of this conversation. |
crew_changes | Discards a job that waits for a decision. Only you can apply one. |
A task
| Field | What it holds |
|---|---|
description | What to change, which files, and what the result must show. |
done_when | The check commands, in backticks. KodaCode runs every backticked part as a command. Leave it out when the worker's own test covers the change. |
difficulty | easy, medium or hard. Sets the worker's call limit to 25, 50 or 75. |
brief | A research id, or text, for the worker to start from. |
files | The files or folders that the change touches. |
retry_of | The id of a failed task to send again. See Retries. |
steps, combined_check | Several changes at once. See Batches. |
A task holds one change. KodaCode counts each numbered or lettered item in a description as a separate change, and refuses a task with three or more.
How a job runs
- Copy. KodaCode makes the private copy.
- Work. The worker reads the code and makes the change. For a bug fix, it first writes a test that reproduces the problem and runs it with
reproduceto see it fail. When the task names a check, a fix with no reproduction test by call 12 stops. That limit doubles when the worker already edited code, and it grows with difficulty like the call limit. - Check. KodaCode runs the commands in
done_when. With no commands, it runs the worker's reproduction test. With neither, the work lands markedtests=none not-verified. - Fix. When a check fails, the worker gets two fixes. Then the Stronger model, when set, gets one attempt of up to 15 calls.
- Review. When a Review model is set, it reviews the task, the test and the diff. It can only turn an OK into PARTIAL.
- Proof. For a bug fix, KodaCode runs the reproduction test again on the fixed code. When the test does not pass, or it lost lines after it failed, the verdict shows
repro=unverifiedand a risk line. - Land. KodaCode applies the change to your working tree, uncommitted. When your tree changed the same lines, the worker redoes the change once. When the clash remains, the verdict is CONFLICT.
A job stops after 20 minutes (TIMEOUT), at the Budget per task (BUDGET), or when you press Stop (CANCELLED).
Retries
- After a FAIL, the leader can send the task again with
retry_ofand a narrower description. - The retry continues in the failed job's copy, with its changes in place, under the same id. You see one card.
- A FAIL with
check=envmeans that the check could not run. The leader retries it with a check that can run. - Retries after a failure (default 1) sets how many retries one task gets. With 0, the leader reports the failure at once.
- While a failure is open, the leader must retry it or stop and report. A new message from you lifts that block.
- If you discarded the failed job, a retry starts again from your working tree.
Batches
For several independent changes, the leader sends steps and a combined_check. Each step has an id, what to change, its files, its own done_when, and optional needs and difficulty.
- Steps run at the same time, unless their files overlap or
needsorders them. - Steps land in step order.
- When every step landed, or you discarded the rest, KodaCode runs the
combined_check. When it fails, one more worker job tries to make it pass. retry_ofdoes not work withsteps.
Research
researchruns a read-only worker in its own private copy, on the worker model.- The answer is 200 words at most by default, and up to 600 when the leader asks.
- For a question about a failure, the research worker runs the relevant test or command and reports what it showed.
- The leader passes the answer's id as a task's
brief. The answer is kept for the conversation, not on disk.
Self-managed
Type the command and the task in any session:
/crew-self-managed Add rate limiting to the login endpoint
Self-managed follows GVS5H (arXiv:2608.26480). It uses the same roles and limits. Two parts are different:
- The paper checks a solution against the public tests of the problem. KodaCode runs the check that each task names, for every task so far.
- The workers in the paper rewrite one solution file. KodaCode's workers edit a private copy of your project, and each worker writes a test for the criteria of its task.
In the paper, a model that managed itself got higher scores on LiveCodeBench than the same model alone. It used about three times the tokens.
No frontier model runs. The Worker model plays every role, each time in a fresh conversation:
- Plan. The manager writes a plan of 3–6 sentences and 3–6 tasks. Each task has criteria: what its test must show. The manager cannot read files or run commands.
- Ideation. A read-only worker reads the code and lists several different approaches, with the pitfalls of each. It writes no code.
- Rounds. Each round has the three steps below.
- Land. When the manager says done, the work has changes and every check passes, KodaCode applies the work to your working tree, uncommitted.
- Final worker. A final worker writes the definitive solution when the manager picks the same task twice in a row, or at the Worker rounds limit. KodaCode applies it without running the checks again.
Each round:
- The manager updates the task list. It adds, merges, drops or completes tasks, and picks the next one.
- A worker does that one task in the shared copy. It writes a test for the task's criteria, makes the change, and names the command that runs its test.
- KodaCode runs the check of every task so far. A failing check overrules a manager that says it is done.
- The plan holds up to 4,000 characters. The shared notes hold up to 8,000. The task list holds up to Open tasks (default 12).
- The crew card shows the plan and the task list.
- A message that you send during a run goes to the manager at its next decision.
- Self-managed has no budget and no time limit. It ends at the round limit, when you press Stop, or when the provider refuses a call for a rate or usage limit (BUDGET).
Verdicts
The first word of a job's report is its verdict:
| Verdict | Meaning | The copy |
|---|---|---|
| OK | The change is in your working tree, uncommitted. tests=none and not-verified mean that no check proved it. | Removed |
| PARTIAL | Supervised only. The worker stopped at its call limit with changes and no failing check, or the review model did not pass it. | Kept |
| FAIL | The work did not pass, or nothing changed. check=env means that the check could not run, for example because a tool is missing. The code may be fine. | Kept |
| CONFLICT | The change clashes with your working tree. | Kept |
| TIMEOUT, BUDGET, CANCELLED | A limit stopped the job, or you pressed Stop. | Kept |
A kept job shows Apply changes and Discard on its card. Only you can apply it.
Every kept job in the project also shows in the Changed Files panel, under Waiting crew jobs, whichever session started it. Each job lists its status, its reason and its files. Click a file to see its diff in the job's copy. Apply lands the changes in your working tree, uncommitted. Discard asks once, then removes the copy.
Approvals, questions and messages
- Crew edits follow the project's approval settings. With approvals on, each edit waits in the session that started the crew. The approval shows the file in the copy, for example
.koda/worktrees/crew-<id>/src/app.ts. The job's clock pauses while it waits. - A Supervised worker can ask you a question. The job pauses. With no answer in 60 minutes, the job stops and keeps its copy.
- A worker may install a package that its task needs. When the dependency folder is linked, the install writes into your project's folder.
What crew agents can use
| Agent | Tools |
|---|---|
| Supervised leader | task, research, crew_status, crew_changes |
| Supervised worker | read_file, query_code_graph, edit_file, write_file, shell, ask_user, finish, reproduce |
| Research | read_file, query_code_graph, shell |
| Self-managed manager | crew_decide |
| Ideation | read_file, query_code_graph |
| Self-managed worker | read_file, query_code_graph, edit_file, write_file, shell, finish |
- With Skills on (the default), the workers, research and ideation also get
read_skilland your skills list. - With Memory on (off by default), they also get the
memorytool and its rules for what to store. Memories go to your project's memory, not to the copy. - The leader and the manager never get skills or memory.
- Supervised agents cannot use any other tool. Their edits to
.git,.koda, lockfiles and linked dependency folders are refused. A package manager can still update a lockfile. - Shell commands follow your normal command approvals.
Cards
- Each job has a Crew card in the session. It shows the task, its status, calls and cost.
- Details shows the plan, the tasks, the checks and the final report.
- Stop stops a running job and keeps its copy.
- After a restart, KodaCode rebuilds every card from the conversation. A job that waits for your decision gets its Apply changes and Discard buttons back.
- The header's tool calls and tokens include the leader, research and every worker.