Task management (CLI)

cockpit task lets an AI agent or person create Cockpit tasks, read their state, send the next instruction, and collect results. Use this flow to delegate one job to another task. Use Fleet when a reusable YAML workflow needs dependency order.

Choose create or run

Use run when the child result is required for the next decision. Use create when work can continue independently and you will inspect it later.

cockpit task run \
  --instruction "Investigate the change and report the cause and evidence" \
  --directory /path/to/repo \
  --agent-type codex

Pass long instructions, Markdown, quotes, backticks, or $ through --stdin or --instruction-file instead of embedding them in a shell argument.

cockpit task run --instruction-file instruction.md \
  --directory /path/to/repo \
  --agent-type codex

After create succeeds, it returns the new taskId and the account Cockpit actually selected. If run creates the task but times out or encounters a wait error before receiving the first report, it still returns ok: true with data.taskId. The task already exists in that case, so do not submit the same instruction again; continue with task get or task wait for the returned id. ok: false means task creation itself failed.

Create with Smart Routing

When Cockpit is signed in with an AGI Labo membership, add --smart-routing to create or run to choose the agent, model, and reasoning effort from the registered routing policy and instruction. If both --directory and --project are omitted, it also chooses a workspace from the same candidates as Auto on the new-task screen. Supplying either option fixes only the workspace while the runtime is chosen. A routed external-agent task uses Native UI and an Auto account.

cockpit task run \
  --instruction-file instruction.md \
  --smart-routing

cockpit task create \
  --instruction "Investigate the test failure in this repository" \
  --directory /path/to/repo \
  --smart-routing

Candidates are limited to agents that are installed and enabled on this device and to models Cockpit can discover. Terminal and Creative Studio are not selected. Because --smart-routing chooses the agent, model, and reasoning effort, it conflicts with options that fix those values, as well as account, UI mode, system prompt, branch source, and related runtime options. When using --worktree, first fix the workspace with --directory or --project. The routing policy and sign-in belong to this device, so --host is not supported.

Selection may wait up to 20 seconds for model discovery and up to 25 seconds for the routing service. On failure, the command returns a stable error code and creates no task. On success, inspect data.smartRouting and the task fields for the selected agent, model, reasoning effort, and workspace when one was selected. See the cockpit task reference for the exact conflicts and error codes.

When the creation response is lost

task create and task run send a unique create key with every creation. If the connection drops after sending the request, the CLI first looks up a task already created with that key. A match returns the same taskId with data.replayed: true, preventing a lost acknowledgement from creating a duplicate. The CLI retries creation with the same key only after Cockpit confirms that no task was created.

task_create_interrupted means Cockpit confirmed that no task exists, so the same command can be run again. task_create_outcome_unknown means the outcome could not be confirmed and the task may exist. Inspect cockpit task list before creating another task in that case. The running Cockpit retains create-key records for ten minutes; after the app restarts, the same key can no longer reconcile a surviving task.

The CLI normally generates a UUID. Use --create-key only when an external workflow needs a stable correlation value. It accepts 1–128 letters, digits, ., _, :, and -. Reusing the key from the same caller returns the same task.

cockpit task create \
  --instruction "Verify the publication state" \
  --directory /path/to/repo \
  --create-key deploy-2026-09-05-1

Set the project, working folder, and runtime

Use --project <id|name> to assign the task to a project. Without --directory, it starts in that project's primary folder; with --directory, the folder must belong to the project. If --project is omitted, Cockpit assigns the task from its working folder according to the project rules. If both are omitted, the task starts in an operating-system temporary folder outside every project. Use --worktree when the task needs an isolated Git Worktree.

The agent, UI mode, model, reasoning effort, account, approval mode, and Browser Identity are task runtime settings. For Claude Code, Codex, Antigravity, Cursor, Qoder, and Grok Build, choose the creation-time display with --ui-mode visual or --ui-mode terminal. Cockpit Agent and Terminal do not switch UI modes. Unsupported combinations fail instead of silently selecting a different setting. For work on an external site, explicitly assign the Browser Identity that holds the required sign-in state.

Codex Native UI accepts --service-tier standard|fast|ultrafast. fast and ultrafast are valid only when the selected model advertises that tier.

--approval-mode accepts supervised, accept-edits, auto, or full-access. It overrides the per-task default for Cockpit Agent and agents in Native UI. Terminal UI and Terminal tasks reject it.

auto (Auto) is available in Native UI for Claude, Codex, and Grok. The agent’s own reviewer evaluates commands and edits, allows routine actions, and blocks risky actions or sends them for human approval. It never answers questions or Asks. Other agents reject auto. Changes apply immediately for Claude and from the next turn for Codex. Grok restarts its idle session while preserving the conversation; changes are rejected while work or a pending request remains. If model, account, or organization restrictions prevent Claude or Codex from using Auto, Cockpit displays the effective mode and posts a chat notice. Grok’s runtime mode cannot be read back, so that check does not cover Grok. Cockpit never automatically falls back to full access.

cockpit task create \
  --instruction "Verify the publication state in the admin console" \
  --directory /path/to/repo \
  --agent-type codex \
  --ui-mode visual \
  --media ./expected-screen.png \
  --browser-identity work

--media copies local files into Cockpit-managed storage and attaches them to the first instruction. The limit is eight files, 512 MB per file, 25 MB for JSON, and 1 GB in total. Remote URLs and file types the selected agent cannot receive directly are rejected. Source files are neither moved nor deleted.

Create projects and move tasks

cockpit project create --name "Shop" --folder ~/repos/shop-web --folder ~/repos/shop-api
cockpit project update Shop --primary-folder ~/repos/shop-api
cockpit task project <task-id> Shop
cockpit task project <task-id>

cockpit project manages the same projects shown in Desktop and the PWA. The first folder is primary. A project created without --folder receives an empty Cockpit-managed folder. Updating can add, remove, replace, or reorder folders; deleting a project leaves its folders untouched and moves its tasks to No project.

cockpit task project <task-id> <id|name> moves the task and all of its child tasks. The new project's folders apply when their agent sessions next start. Master Agent and Creative Studio tasks cannot be moved. If several projects have the same name, use the ID reported by cockpit project list.

Create parent and child tasks

A task created from another task is a child of the caller by default. Use --parent-task-id to name another parent, or --top-level to create an independent task without a parent. Both task create and task run support --top-level; omitting it keeps the caller-as-parent default.

cockpit task create --top-level --instruction "Maintain the project backlog"
cockpit task run --top-level --instruction "Review the project independently"

Do not combine --top-level with --parent-task-id. Empty or whitespace-only parent IDs are rejected; use --top-level to request no parent. Creator attribution (createdByTaskId) is retained independently of the parent link (parentMasterId). Hooks also treat these independent tasks as top-level: --no-child matches them and --child does not. Use the existing task pin <task-id> command to pin one after creation; creation does not pin it automatically.

The hierarchy groups work in the task list and child tasks panel, but it is not a report-delivery contract.

When a child reaches a stopping point, the parent does not necessarily receive every artifact automatically. The parent must read the return from task run, call task wait or task get, and verify requested evidence such as diffs, tests, or URLs.

Delete child tasks from the task menu

On Desktop and the PWA, a task with children has a Delete all child tasks action in its menu. Confirming removes every descendant, including nested children, while keeping the parent task. Cancel to leave them unchanged. Review the entire child hierarchy before confirming.

Read state and waiting reasons

cockpit task list
cockpit task list --status waiting_confirmation
cockpit task list --parent <task-id>
cockpit task list --parent <task-id> --recursive --all
cockpit task list --summary
cockpit task get <task-id> --turns 3 --max-lines 500

--parent returns the named parent and its direct children; add --recursive for every descendant. Completed tasks are excluded by default. Add --all to include them, or --status completed to select only completed tasks. --directory and --name further filter the result. Recursive traversal still passes through a parent hidden by a filter. An unknown parent returns task_not_found, and --recursive without --parent is invalid.

A parent query always uses the lightweight summary form. Add --summary to an ordinary list for the same fields: id, name, status, stopReason, hasPendingAsk, parentMasterId, directory, projectId, agentType, and creation and update times. projectId is null outside every project. The response-level generatedAt gives the snapshot time. Instructions, conversation, reports, model settings, and device data are omitted; use task get only for tasks that need those details.

If waitingReason is permission or question, an agent-side confirmation is still active. Do not layer another instruction while readyForNextPrompt is false. For usage_limit, inspect available accounts and the reset time.

Full and summary task list, task get, and the task snapshot in task wait return the same stopReason: approval, turn_ended, usage_limit, question, terminal_prompt, runtime_error, or unknown. It is null while running or after completion. turn_ended means one turn ended, not that the whole task completed. Without reliable evidence the value is unknown; a session ID alone is insufficient. hasPendingAsk is independent of approvals.

Retry a task that failed to start

For a task with startFailed: true, use retry-start instead of creating another task. By default it reuses the saved initial instruction or Terminal command. Supply new text only when replacing that input.

cockpit task retry-start <task-id>
cockpit task retry-start <task-id> --instruction-file retry.md
cockpit task retry-start <task-id> --directory /path/to/folder

--directory changes an unstarted standalone task to another existing working folder before retry. It is unavailable for child tasks, Master Agent tasks, branches, worktrees, Creative Studio tasks, and tasks with an existing session. Cockpit does not create a missing folder, reassigns the task to the project containing the new folder, and preserves the saved instruction and attachments.

retry-start is only for startup failures. Use resume for a stopped task and reconnect to reconnect an existing visual session. Completed, running, and other non-startup-failure states cannot be retried.

Respond to pending approvals and questions

turnRequests in task get contains only the tool approvals and structured questions that the runtime still holds. Before deciding, inspect the requestId, kind, requestType, and the operation in detail. Questions also include their IDs, choices, and whether they accept multiple selections or custom input.

cockpit task get <task-id>
cockpit task approve <task-id>
cockpit task approve <task-id> --scope always
cockpit task deny <task-id>
cockpit task answer <task-id> --text "Option A"

approve allows only this request by default. --scope always remembers the decision for later requests of the same kind, so use it only when you understand that scope. If several requests are pending, target one with --request <request-id>. deny accepts neither a scope nor a reason; if the task also needs an explanation, send one with task send after denying.

For several questions, pass one --text in question order. To name each question or answer a multi-select question, use --question <question-id> with one or more --choice values. Cockpit validates the answer count, question IDs, single- or multi-select contract, and offered choices before sending anything.

cockpit task answer <task-id> --text "Yes" --text "Staging"
cockpit task answer <task-id> \
  --question checks --choice lint --choice tests \
  --question deploy --choice staging

task answer responds to the running agent's own question. It is separate from cockpit ask answer, which answers a Cockpit Ask on a person's behalf.

Receive reports in order

report.seq increases per task in results from task run and task wait. Pass the last processed sequence through --since to wait for the next report without processing the same one twice.

cockpit task wait <task-id> --since <last-seq> --timeout 110

timeout: true does not mean the task failed. Inspect current state when needed, then continue from the same --since. Use task wait for continued monitoring instead of repeatedly polling task get at short intervals.

A child entering or leaving approval waiting also appends a report with approvalEvent: approval_waiting or approval_resolved and queues a notification for its parent. A busy parent receives it when ready for another turn; completed or missing parents are not resumed. Repeated writes of the same state do not duplicate the notification. Ordinary result reports still need to be collected by the parent.

approval_resolved means the wait ended, not that approval was granted or work succeeded. It also covers interruption, errors, usage limits, and completion. Multiple approval requests keep the child waiting until the last one is resolved. Notifications never approve a request or change permissions, model selection, or the parent's pending agent switch.

After an approvalEvent, keep waiting for the result with task wait --since <seq> using that notice's sequence. An exit notice into error or completion retains the previous nonterminal status; the ordinary result report carries the actual error or completion output. Use task get for current state. Fleet automatically skips approval notices and continues waiting for results.

Send a follow-up

Use task send after the task can accept another instruction. Add --wait when the next report is required in the same control flow.

cockpit task send <task-id> --text "Fix only the failing test and run it again" \
  --media ./failure.png \
  --wait

Use --stdin or --text-file for multiline content. --media on task send follows the same count, size, local-file, and agent-support limits as creation. To send only Enter to an agent confirmation, run cockpit task send <task-id> with no text. Read waitingReason first so you know whether you are answering a question, approving a tool, or sending an ordinary follow-up.

Manage the turn and conversation from the CLI

cockpit task cancel <task-id>
cockpit task compact <task-id>
cockpit task clear <task-id> --confirm
cockpit task approval-mode <task-id>
cockpit task approval-mode <task-id> accept-edits

cancel stops only the running turn and keeps the task and conversation. compact compacts the conversation. Because clear discards the conversation and original instruction before starting a new conversation, it requires --confirm. The reset updates every Desktop and PWA view with that task open. Other views preserve their draft text, attachments, and queue.

compact and clear return task_turn_in_flight while a turn is running or waiting for a tool approval or question. Finish the turn, answer the pending request, or run cancel first. Without a mode, approval-mode reads the current value; with one, it changes only that task. If an active Cockpit Agent session is changed to a stricter mode than it started with, full enforcement requires a new conversation or task, and the CLI result includes a warning.

Support depends on the agent and UI mode:

• Claude Code, Codex, and Grok Build Native UI: every turn-lifecycle command
• Cursor and Qoder Native UI: every command except answer
• Antigravity Native UI: cancel, compact, clear, and approval-mode
• Cockpit Agent: approve, deny, answer, cancel, and approval-mode
• every Terminal UI and Terminal task: unsupported

An unsupported combination exits 1, an action that does not match the current state exits 3, and an unreachable Cockpit exits 7. Automation should inspect the JSON code and current state as well as the exit code.

Start an agent Goal

When a visual runtime reports goalCommandAvailable: true, the CLI can start a new Goal. Cockpit sends it to the running agent as a real turn. It is unavailable for Cockpit Agent, Terminal UI, Terminal tasks, and runtimes without Goal support.

cockpit task goal start <task-id> --objective "Complete the release verification"
cockpit task goal start <task-id> --objective-file goal.md

The CLI does not stop or clear Goals. After starting one, supervise it through task get, task wait, and the usual turn controls.

Switch the account or Browser Identity

Supported agents can switch a running task to another signed-in account after a usage limit. Send the appropriate continuation after the switch.

cockpit task account <task-id> work

Changing Browser Identity selects the persistent browser partition for the task's next browser session. It does not copy cookies or localStorage between Identities.

cockpit task browser-identity <task-id> work

Distinguish completion, resume, and removal

Complete or remove a task only when the user explicitly requests it. Save required diffs, artifacts, reports, and publication URLs, then verify the target id before acting.

Determine completion

Task management is complete only after confirming that:

• Requested results and evidence were collected from the report or actual files.
• No confirmation, usage limit, error, or timeout remains unresolved.
• The parent integrated child results in the required order.
• External publication or deletion stayed within the approved target.
• Needed changes were saved before a workspace was removed.

See the cockpit task reference for every option, and Task list plus Task details for the corresponding UI.