Make the task reviewable
Run these commands in the original project on your computer, called the parent project below. The example fixes a flaky login test. Replace its paths, commands and requirements with a real issue you can review in one sitting.
In AGENTS.md, record the build and test commands, where changes belong, and when the agent must ask a question.
Choose the command that checks your project before you start. co:op calls this the gate. Add it to your existing .agent/project.yaml, keeping the other settings.
.agent/project.yaml · example addition
# Use your project's real verification command. gate: make check
The example uses make check. Use your project’s actual command, confirm that it works in the container, and put it in AGENTS.md so the agent knows to run it. co:op also runs it during fork review and merge. A COOP_GATE setting on the host overrides the project setting.
Host terminal · parent project root
coop tasks add "Fix the flaky login test" --tasks .agent/tasks
Open the generated task.md at the path printed by the command. Keep its metadata and fill in the brief before running the loop.
Example task brief · adapt before running
- Observed
tests/login.test.tsfails when another test leaves a signed-in user in shared test state.- Expected
- Each test starts with its own session state. Login succeeds with valid credentials and fails with invalid ones.
- Verify
- Reproduce the failure, run the focused login tests repeatedly, then run the project gate. In this example project:
make test-loginandmake check. - Reject
- Deleting or skipping the assertion, weakening the behavior check, or adding a sleep to conceal the race.
- Leave evidence
- Record the cause, changed files, commands and actual results in the task log. Stop and ask if the fix requires changing authentication behavior.
Before you continue
The task names a real failure, a verifiable result and an unacceptable shortcut. The check commands exist in your project and work in the box.
Choose exactly what may run
A fork starts from committed source. Review and commit the code, project configuration and instructions the run needs before creating it. Keep co:op’s local task queue uncommitted; the host manages its assignments separately.
Host terminal · parent project root
git status --shortcoop tasks ls --tasks .agent/tasks --todo --in-progresscoop fork ls
The commands in this guide select the root queue, .agent/tasks. Every eligible task in that queue may run, including tasks you added earlier. Check the list before continuing.
If you need a separate queue for this run, follow the queue configuration and selection options and use that path in every task, launch and resume command below. Choosing a queue does not limit the number of tasks, runtime or spending.
Choose an unused fork name. This guide uses overnight with --isolated, which gives the fork its own Git metadata and object storage. co:op checks the committed changes before bringing them into your original checkout.
If the fork already exists, or you use shared services
Choose a new name if overnight is already in use, and substitute it in every command below. An existing ordinary fork cannot be upgraded to isolated mode in place.
Shared caches, services and host tools still need your trust. Review the committed changes with coop fork review before opening the fork’s raw directory in an editor. Files the agent changed, including Git and editor settings, can run code on your computer. The isolated-fork reference explains these limits.
Before you continue
The source the fork needs is committed, you have checked which tasks may run, and your fork name is unused. You are still in the parent project.
Launch the fork in the background
Start Claude Code in the new isolated fork. If you signed in to Codex, substitute codex for claude in this command and the resume command below.
Host terminal · parent project root
coop fork overnight claude --isolated --loop --tasks .agent/tasks -d
-d runs the loop in the background so you can keep using your terminal. The loop edits and commits in the fork, while the host assigns work from the parent queue. It uses your provider allowance and your computer’s resources, so keep the computer awake and Docker running.
coop fork lscoop fork logs overnight
Check that the intended fork started and its logs show the expected task. If it stops with a question, answer it and resume the same fork as shown below. Final review can send work back for another pass if it falls short of the task’s requirements.
Before you continue
The fork name, agent and task in the status and logs match your intended run. Leave it unattended only after this first check.
Stay in control of the run
Run these commands from the parent project. The live views occupy their terminal; open another terminal if you want both at once.
Host terminal · parent project root
coop tasks watch --tasks .agent/taskscoop fork logs overnight --follow
Press Ctrl-C to leave a live view. Leaving the log view does not stop the background loop. To stop that loop and its running boxes while preserving the fork’s work:
coop fork stop overnight
To review pending questions, record your answer in the parent queue. This also unblocks the answered task:
coop tasks decisions -i --tasks .agent/tasks
After answering a question or stopping the run, use this command to resume the same fork. Repeat the queue path: co:op remembers that the fork is isolated, but it does not remember the previous --tasks filter.
coop fork overnight claude --isolated --loop --tasks .agent/tasks -d
A command exited successfully. Is the work finished?
Read the fork’s status and final-review result. A successful command exit can mean that the fork is waiting for your answer, or that it reached a task limit before final review. Check the result before treating the work as finished.
The commands in this walkthrough keep working in the named fork. A direct coop loop instead edits and commits in the current checkout; use the loop reference if that is the workflow you intend.
Before you continue
Check that the fork is ready and its final review is complete. The task in the parent queue may still be in progress, even when the fork is ready. It becomes complete when you merge the reviewed changes.
Review the result before landing it
When the fork is ready, inspect its committed changes. You will then run the project check on a temporary copy that includes the latest changes from your current branch.
Host terminal · parent project root
coop fork review overnight
Read the diff first, especially any changes to build scripts. Then run the configured project check:
coop fork review overnight --gate
Read the summary to confirm which check ran and what it reported. If no check is configured, --gate can exit successfully without testing the project.
The review includes only committed changes. If it warns about uncommitted or untracked fork files, resolve the warning and review again.
For the login-test example, look for
- An explanation of how tests shared session state, backed by a reproduced failure.
- A focused change that gives each test its own state and keeps the assertions.
- Tests that cover the original failure and the affected failure path.
- Commands and results from repeated login tests and the project gate.
- A completed final review, with all requested fixes addressed.
A passing gate verifies only the checks it ran. Check the changed behavior yourself as well.
Once the result meets the task’s acceptance criteria, and the parent checkout is clean, merge it from the branch where you want the work to land:
coop fork merge overnight
Confirm when co:op asks to bring the changes into your branch. It prepares the committed work for that branch, runs the configured check, and merges only if the check passes. It asks separately before removing the fork.
If review or merge stops with an error, fix the reported problem and review again. Pushing and deploying are separate actions.
Before you continue
The reviewed changes are on the branch you intended, you have saved the check result, and the matching tasks in the parent queue are complete. Try a larger run after you have checked this result.