A task is a session with a task contract: a goal, a start commit and a closing instruction. skyworker run makes one. The task runs in a workspace, so it goes on when you close the laptop.
Hand off a task
Run run in a git checkout:
skyworker run "Fix the flaky test in auth" --title "Flaky auth test"The workspace clones from the Git remote. run never sends local files. Before it wakes anything, it checks your checkout. It fails when the branch is not pushed, when commits are not pushed, when files have changes that are not committed, when files are not tracked, or when HEAD is not on a branch. The error says what the workspace would not see. --allow-dirty starts the task anyway.
run adds a closing instruction to the prompt. The agent commits, pushes the branch to origin of its checkout, opens a pull request when gh works, and ends with a result line.
To name the workspace, add it as the second argument: skyworker run "<task>" <workspace>.
Flags of run
| Flag | Meaning |
|---|---|
--harness <name> |
The agent: opencode (default), claude-code or codex. See Harnesses. |
--model <provider/model> |
The model. With another harness, a model name of that harness. |
--title <text> |
The session title. The default comes from the task. |
--branch <name> |
Start from this branch as it is on origin. The default is the branch of this checkout. |
--auto |
OpenCode runs with no permission prompts. A deny rule still applies. Claude Code and Codex always run with no prompts. |
--new |
Start the task in a new workspace. |
--worktree |
Start the task in a new git worktree in the workspace. |
--no-push |
The agent commits and does not push. |
--allow-dirty |
Start although the workspace will not see some changes. |
--skills <a,b|all> |
Copy these skills from this machine into the workspace first. |
--schema <file.json> |
The last message must end with a json block that matches this JSON Schema. |
--wait |
Wait until the task leaves working, then print its result. |
--follow |
Wait, and show the progress of the agent live. |
--timeout <minutes> |
How long --wait and --follow wait. The default is 60. |
--continues <n> |
Automatic continues after a pause. See Long tasks. |
--max-hours <n> |
Time budget in hours of work. |
--max-cost <dollars> |
Cost budget. |
--wait and --follow are two ways to do the same wait. Use one of them.
The schema subset is: type, properties, required, items, enum and additionalProperties set to false. The result then holds the block as structured.
Run two tasks at once
One agent at a time works in the checkout of a workspace. A second run there fails while a task is working or waiting. Give the second task its own checkout:
--worktreestarts it in a new git worktree in the same workspace.--newstarts it in a new workspace, named<checkout>-<short id>. It pauses when idle, like any other workspace. It counts towardmaxRunning.
Use one of the two. --new does not take a workspace argument. Remove a workspace that you do not need: skyworker delete <workspace>.
Keep a commit local
--no-push tells the agent to commit and not to push. The commit stays on the workspace disk. Skyworker sends no automatic reply that asks for the push.
List tasks
skyworker tasksThe list shows the newest task first. It reads the saved state and wakes nothing. A running workspace answers live. A paused workspace answers with the states saved at its last refresh.
| State | Meaning |
|---|---|
working |
The agent works. |
done |
The agent ended the task. |
failed |
The task failed. |
waiting |
The agent asks a question or a permission. |
stopped |
The workspace paused under the task, or a budget ended it. |
A task that ended shows * until you read it with skyworker tasks <session>. --unseen lists only those tasks.
A session of Claude Code or Codex is named <workspace>:<id>, as tasks prints it. You can also pass --workspace <id>.
Read the result
skyworker tasks <session> --workspace <workspace>The result record has the state, a summary, the branch, the commits since the start, the changed files and the pull request. The workspace reads these with git and gh. They do not come from the words of the agent. --json prints the record as JSON.
--pull fetches the branch of the task from origin into your checkout. It makes or fast-forwards a local branch that tracks it. Your files and your checked-out branch do not change, except a fast-forward of that branch when it has no changes.
Wait for a task
--wait and --follow also work on tasks <session>. They return when the task leaves working. The exit code says how it ended:
| Exit code | Meaning |
|---|---|
| 0 | done |
| 1 | failed |
| 2 | waiting |
| 3 | The wait timed out |
| 4 | stopped |
Reply, continue and cancel
skyworker tasks <session> --workspace <workspace> --reply "Use the staging database."
skyworker tasks <session> --workspace <workspace> --continue
skyworker tasks <session> --workspace <workspace> --cancel--replysends one more message to the session. It starts the next turn. A paused workspace wakes for it.--continueis a reply for a task that stopped. It goes on from where the task stopped.--cancelinterrupts the turn that runs. It wakes nothing.
A reply or a continue is refused while another task works in the same checkout.
A permission request of OpenCode is answered in OpenCode or on the phone. Run skyworker connect <workspace> --session <session>. See Harnesses for what is not built for Claude Code and Codex.
Long tasks and budgets
A workspace pauses at maxAwakeHours (default 12), also under a working task. For a longer task:
- After that pause, Skyworker wakes the workspace and continues the task by itself. It does this up to 3 times by default. Set another number with
run --continues <n>. Zero turns it off. The setting isautoContinue. - Each task has a time budget:
--max-hours <n>. The default is 24, from the settingmaxTaskHours. - A task can have a cost budget:
--max-cost <dollars>. The default is off, from the settingmaxTaskCost. - At a limit, the turn is interrupted and the task is
stopped.
Raise the budget and go on:
skyworker tasks <session> --workspace <workspace> --continue --max-hours 48The cost is an estimate. It is the container estimate plus the model cost that the harness reports. A harness that reports no model cost adds none. See Costs.
A task that is working with no change for 30 minutes gives one stall notice. Every 6 hours of work it gives one progress note. The settings are stallMinutes and progressNoteHours. Both go where results go: the notify URL and the web client.
Get a message when a task ends
Set a notify URL. The Worker then sends a signed POST with the result record when a task leaves working. The Worker sends it, so it works with the laptop closed.
printf %s "$WEBHOOK_URL" | skyworker notify-url
skyworker notify-keyThe URL must use https, hold no user or password, and name a public host. It is a Worker secret. It is never an argument, because a webhook URL often holds its own secret. skyworker notify-url --remove deletes it. notify-key prints the key that signs the POSTs. Give it only to the receiver.
Hand off from an agent
skyworker mcp serves run and tasks to a local agent as MCP tools over stdio. The tools are handoff_task, get_task, wait_task, list_tasks and pull_task.
claude mcp add skyworker -- skyworker mcpskyworker skill --install --claude installs a skill that tells a local agent when and how to hand off a task. Use --opencode for OpenCode, or --dir <path> for another folder.
The MCP server acts with your control token. Give it only to an agent that you would let run skyworker run.