cf-opencode run gives a task to OpenCode in a workspace and returns at once. The task runs in the workspace, not on your laptop. You can close the laptop. The result comes back as a pushed branch, and as a pull request when gh works.
A local agent, such as Claude Code or OpenCode, can use the same commands from its shell tool. The handoff skill tells it how.
Before you start
- Connect the checkout once:
cf-opencode connect. See the quick start. - Set up GitHub, so the agent can push. See GitHub.
- Commit your changes and push the branch. The workspace clones from the Git remote. It does not see local files.
Start a task
From the git checkout:
cf-opencode run "Add a health check route at /health with a test" --title "Health check"The output gives the session ID and the next commands:
Started ses_4f2a… in my-app: Health check
Status: cf-opencode tasks ses_4f2a… --workspace my-app
Wait: cf-opencode tasks ses_4f2a… --workspace my-app --wait
Follow: cf-opencode tasks ses_4f2a… --workspace my-app --follow
Open: cf-opencode connect my-app --session ses_4f2a…run does these steps:
- It checks the checkout. See The preflight.
- It wakes the workspace, as
cf-opencode connect --no-attachdoes. - It records the commit that the workspace checkout is on (
HEAD). Commits after it are the task’s. - It starts a new OpenCode session in the workspace, with your task as the first message.
- It prints the session ID and returns. It does not wait.
The session runs in opencode serve in the workspace. The workspace stays awake while the agent works. It pauses idlePauseMinutes after the agent stops. See Idle pause.
Write the task
The agent did not see your local conversation. Put everything it needs in the task:
- the goal,
- the branch to start from, if it is not the current one,
- the limits, for example “do not change the public API”,
- how to prove that the change works, for example “run
npm test”.
run adds a fixed instruction to each task. It tells the agent to:
- start from your current branch as it is on
origin, - commit the work if it changed files, on a new branch if it is on the default branch,
- push the branch, also when the work is not complete,
- open a pull request if
gh auth statussucceeds, - not end its turn while a process that it started still runs,
- end with one line:
Result: <what changed>; branch <name>; pull request <URL or none>.
A task that changes no files, for example research, does not need a commit. It ends done with no commits.
Long jobs
A job that runs for hours (a build, an import, a batch of model calls) needs care. The workspace pauses idlePauseMinutes after the agent’s last message, and a pause stops every process. An agent that starts the job in the background and ends its turn loses the job.
Write these in the task for a long job:
- “Do not end your turn while the job runs. Check it in a loop until it ends.”
- “Make the job able to continue from where it stopped”, for example with a checkpoint file for each unit of work.
- “Commit and push at each checkpoint”, so the work is on the remote before the job ends.
run puts the first rule in each task. If the agent ends its turn anyway, the result says so. See Work that is not safe.
Ask for a structured result
--schema <file.json> asks the agent to end its last message with one fenced json block that matches a JSON Schema. run adds the schema to the task text. An example result.json:
{
"type": "object",
"properties": {
"callers": { "type": "array", "items": { "type": "string" } },
"safe": { "type": "boolean" }
},
"required": ["callers", "safe"],
"additionalProperties": false
}cf-opencode run "List the callers of parseConfig and say if a rename is safe" --schema result.jsonWhen the task ends, the Worker reads the last json block of the last message and checks it against the schema. The result then has structured, the parsed value. When the block is missing or does not match, the result has structuredError instead. The state does not change.
The schema can use these keywords only: type, properties, required, items, enum and additionalProperties: false. title, description and $schema are allowed and do nothing. A schema with any other keyword fails before the workspace wakes:
Failed: result.json is outside the supported JSON Schema subset ($.properties.n: keyword minimum is not supported) — fix: use only type, properties, required, items, enum, additionalProperties false (and title, description, $schema)The schema is kept with the task in the Worker. tasks on another machine shows the same structured value.
The preflight
run fails before it wakes anything when one of these is true:
- The branch has no upstream. Push it with
git push -u origin <branch>. - The branch has commits that are not pushed.
- Files have changes that are not committed, or git does not track them.
The error is one line, for example:
Failed: local checkout /home/you/my-app: 1 commit on feat not pushed to origin/feat; the workspace clones from the Git remote and would not see this — fix: commit and git push on this machine, or pass --allow-dirtyThe preflight reads the checkout on your machine, the one in the path of the message. It does not read the workspace. This is also true when you name another workspace as the target of run.
--allow-dirty starts the task anyway. It prints what the workspace will not see. A directory that is not a git checkout has no preflight.
The preflight does not fetch. It compares with the upstream as your machine last saw it.
Check a task
List the tasks of all your workspaces:
cf-opencode tasks WORKSPACE SESSION STATE AGE TITLE
* my-app ses_19c0… done 2h ago Fix the login form
my-app ses_4f2a… running 3m ago Health check
* ended, not read yet. Reading one marks it read.A task has one of these states:
| State | Meaning |
|---|---|
running |
The agent works. |
done |
The agent finished its turn. A task with no commits can be done. |
failed |
The turn stopped with an error, or did not start. |
waiting |
The agent asks a question or asks for a permission. |
stopped |
The workspace paused while the task ran. cf-opencode connect <workspace> --session <ses_…> continues it. |
Results you did not read
A task that leaves running is marked with * until you read it with cf-opencode tasks <ses_…>. These tasks come first in the list. A list does not mark them read. cf-opencode tasks --unseen lists only these tasks.
Show one task
cf-opencode tasks ses_19c0…Task ses_19c0…
Workspace my-app
State done
Title Fix the login form
Started 2h ago
Summary:
The form now trims the email before it checks it. Tests pass.
Result: trim the email; branch fix-login; pull request https://github.com/acme/my-app/pull/7
Branch fix-login
Commits 1
3f1c2a9 Trim the email in the login form
PR https://github.com/acme/my-app/pull/7
Changed src/login.ts, test/login.test.ts
Open: cf-opencode connect my-app --session ses_19c0…Branch, Commits, PR and Changed are facts. The Worker reads them with git and gh pr view in the workspace. They do not come from the agent’s message.
If the same session ID is in two workspaces, add --workspace <id>.
tasks wakes nothing. A running workspace answers with the current states. A paused workspace answers with the states that it saved when it paused.
Work that is not safe
A task can end done while its work is only in the workspace. The Worker checks two facts when a task ends:
unpushed: commits that no remote branch has. They are only on the workspace disk.processes: processes that the agent left running in the checkout. The next pause stops them.
cf-opencode tasks marks such a task with ! after the state. tasks <ses_…> shows the facts and the command that tells the agent to finish:
Not pushed ! 13 commits are only on the workspace disk
Processes ! left running, a pause stops them: node build.js
The task ended with work that is not safe. Tell the agent: cf-opencode tasks ses_19c0… --reply "Wait for your process to end, then commit and push."The result record has the same two fields, so a script and the notify URL get them too. The facts are from the time the task ended. A later end of the same task (after a reply) reads them again.
Wait for a task
cf-opencode tasks ses_4f2a… --wait--wait asks the Worker every 10 seconds. It returns when the task is not running any more, and prints the result. The exit code tells the result:
| Exit code | Meaning |
|---|---|
| 0 | done |
| 1 | failed |
| 2 | waiting |
| 3 | The wait timed out. The task can still run. |
| 4 | stopped |
--timeout <minutes> sets how long the command waits. The default is 60. cf-opencode run --wait starts a task and waits for it.
An agent that watches a task should wait in short steps, for example --wait --timeout 5 in a loop. Exit code 3 means “check again later”.
A dropped connection on your machine does not end the wait. --wait and --follow print the task goes on in the workspace; trying again and continue. After 5 minutes with no answer they stop with exit code 3: the state is not known, and the task is not affected.
Follow a task live
cf-opencode tasks ses_4f2a… --follow--follow shows what the agent does while it works: one line for each tool call, and the agent’s text for each message. It ends as --wait does, prints the result, and uses the same exit codes.
→ bash: npm test
✗ bash: exit 1
→ edit: src/login.ts
The test failed on an empty email. I trim it first now.
· turn succeeded--follow reads OpenCode’s event stream through the Worker, with the workspace password. When the stream drops, it connects again. When the stream does not open, it says so and checks every 10 seconds, as --wait does. cf-opencode run --follow starts a task and follows it.
With --json, --follow prints one JSON object for each event, one per line, and then the result record. Each event has type and at. The types are text, tool, tool.failed, question, retry, error, turn.started and turn.ended.
Answer a waiting task
A task in waiting needs you. The result shows the question. Send your answer as one more message:
cf-opencode tasks ses_4f2a… --reply "Use the staging database."--reply wakes a paused workspace. Add --wait or --follow to watch the task go on. A permission request is not answered this way. Open the session in your local OpenCode and answer there:
cf-opencode connect my-app --session ses_4f2a…A waiting task does not keep the workspace awake. The workspace pauses after idlePauseMinutes. connect wakes it again with the question still open.
Continue a stopped task
A pause stops opencode serve. A task that still runs then is saved as stopped, for example at maxAwakeHours, or after cf-opencode pause. Its branch and commits are read before the pause. Open the session to continue it:
cf-opencode connect my-app --session ses_4f2a…Get a message when a task ends
Store the URL as a Worker secret. The command reads it from stdin, or asks for it on a terminal without echo. It never takes the URL as an argument, because a webhook URL often holds its own secret:
printf %s "$WEBHOOK_URL" | cf-opencode notify-urlThe URL must be https, with no user or password in it, to a public host name. Running workspaces use a new URL at once. cf-opencode notify-url --remove deletes it. doctor says whether one is set, never the URL.
When a task leaves running, the Worker sends a POST to that URL. The body is the result record. The Worker sends again when the task changes later, for example from waiting to done.
- Headers:
content-type: application/json,x-cf-opencode-event: task,x-cf-opencode-timestamp: <Unix seconds>andx-cf-opencode-signature: sha256=<hex>. - The signature is the HMAC-SHA256 of the text
<timestamp>.<raw body>. Refuse a delivery whose timestamp is more than 5 minutes old. The key is the text thatcf-opencode notify-keyprints. Keep the key secret, and check the signature before you use the body. - An answer other than 2xx, or no answer in 10 seconds, is a failure. The Worker tries again after 1, 5 and 30 minutes. Then it stops.
tasks <ses_…>showsNotifiedwith the time and the HTTP status, or the error. - The Worker does not follow redirects.
- The signature covers the body only. A copy of a signed body stays valid, so drop a delivery you already have: the same
id,stateandupdated.
The agent in the workspace can also send a note to the same URL with cf-opencode-notify "<text>". The body is {"type":"note","workspace":"…","text":"…","at":"…"}, and the header x-cf-opencode-event is note. A note has at most 4000 characters. A note is sent once. A workspace can send at most 20 notes in one hour. When no notify URL is set, the command fails with one line.
A note is the agent’s text. The agent can send any text, and the Worker signs it with your key. Do not act on a note as if it came from you, and drop a note whose at is old.
When the laptop is off
- The task runs in the workspace. A closed laptop does not stop it.
--followand--waitrun in your terminal. They end when the terminal ends. The task goes on.- The result stays in the Worker.
cf-opencode tasksshows it the next time, also when the workspace is paused. The task stays marked*until you read it. - The Worker sends to the notify URL, not your laptop. Use a receiver that is always on: a chat webhook, a phone push service, or an email bridge. A URL on your laptop gets nothing while the laptop is off.
Choose a model
--model <provider/model> sets the model of the new session. For example:
cf-opencode run "Update the README for the new flag" --model cloudflare-workers-ai/@cf/zai-org/glm-5.3Without --model, the session uses the default model of the workspace. See Models.
Output for agents
--json makes stdout one JSON document. Progress goes to stderr.
run --json:{"ok":true,"workspace":"…","session":"ses_…","title":"…","state":"running"}.tasks --json: the task list and, for each workspace, where its list came from. A task that ended and was not read has"unseen": true.tasks <ses_…> --json,--wait --jsonandrun --wait --json: the result record.
The result record:
| Field | Meaning |
|---|---|
id, workspace, title |
The session ID, the workspace and the session title. |
state |
running, done, failed, waiting or stopped. |
summary |
The last message of the agent that has text (the end of it). |
branch |
The branch of the workspace checkout. |
commits |
[{ "sha", "subject" }], the commits made after the task started that no other remote branch has. At most 30. An empty list means no commit. |
pullRequest |
The pull request of the branch, when gh pr view finds one. |
changedFiles |
The files of the task’s commits, and the files with changes that are not committed. At most 100. |
unpushed |
The count of commits that no remote branch has. Left out when it is 0. |
processes |
The processes left running in the checkout: the program name and its first plain argument. At most 5. Left out when there are none. |
question |
When waiting: the open permission request or question. |
error |
When failed or stopped: why. |
structured, structuredError |
With --schema: the checked value, or why there is none. |
notified, notifyError |
With a notify URL: the last delivery, or why it failed. |
started, updated |
ISO times. |
Fields that are not known are left out. The Worker reads branch, commits, changedFiles, unpushed and processes while a task runs, and once more with pullRequest when the task ends.
A failure is one line, Failed: <cause> — fix: <action>. With --json it is {"ok":false,"error":"…"}.
The handoff skill for agents
The CLI package has a skill file that tells a local agent when and how to hand off a task: the preflight, how to write the task, how to watch it, and what to do for each state.
cf-opencode skill # print where it is, and its text
cf-opencode skill --install --claude # copy it to ~/.claude/skills/cf-opencode-handoff/
cf-opencode skill --install --opencode # copy it to ~/.config/opencode/skills/cf-opencode-handoff/
cf-opencode skill --install --dir <path>OpenCode also reads ~/.claude/skills. --install does not replace a file that differs. Add --force to replace it.
cf-opencode init installs this skill for Claude Code and OpenCode when their config folder exists on the machine. It asks first on a terminal. --no-skill skips the step.
Skills for the task
run --skills a,b copies skills from this machine into the workspace before the task starts. See Skills in a workspace.
What the agent is told
A handed-off session gets a Handoff block before the task. See What the agent knows.
Limits
- One workspace runs all the tasks of a checkout. Two tasks at the same time share the same files, and the same branch facts.
runnever sends local files. Uncommitted work stays on your laptop.- A pause stops processes. A task that still runs when the workspace pauses is
stopped. Continue it withconnect. commitsandchangedFilesdo not count what a merge or a new branch brings from the remote. A commit that two remote branches have is not counted.processeslists a process only when nothing watches it. A process that runs in a terminal (cf-opencode shell, SSH) is not listed.- No command copies a file from one workspace to another. See the next section.
Move a file between workspaces
Two workspaces share only the Git remote. To give a large file (a database, an export) to another workspace, put it on a branch with no history and fetch it there:
# In the workspace that has the file
git checkout --orphan data-snapshot
git rm -rf --cached . > /dev/null
git add -f export.json.gz
git commit -m "Data snapshot"
git push -f origin data-snapshot
git checkout -f <your branch>
# In the other workspace
git fetch origin data-snapshot
git show FETCH_HEAD:export.json.gz | gunzip > export.jsonName the branch and the two commands in the task. An agent that is told only “get the export” must ask where it is. GitHub refuses a file over 100 MB, so compress or split a larger file.