cockpit task

This reference is generated from the same canonical source distributed as cockpit CLI help. See Cockpit CLI for concepts and safe operating guidance.

Local task commands authenticate the task API over loopback first and automatically use file IPC when a sandbox blocks loopback or process visibility. The same transport-aware preflight is shared by task, talk, HTML, side-panel, and current-task context resolution. Do not request broader sandbox permissions; use cockpit doctor to inspect pidVisibility, both transport results, and effectiveTransport if the command exits 7.

When the task listener is recovering without an advertised port, the first command waits for recovery and authenticates within one 20-second deadline, using the same PID, token, and IPC directory. Loopback unavailability switches to file IPC quickly; JSON mutations keep the same content type through either transport. Older runtime files without listener diagnostics may publish their final token with the first port; the CLI authenticates that pair from the same PID and IPC directory. Token changes during later recovery fail closed.

Usage: cockpit task <command> [options] [--host <host|alias>] [--port <sync-port>] [--https true|false]

Create, monitor, respond to, and finish Cockpit tasks.

Inspect

cockpit task list                               # List active tasks (excludes completed)
cockpit task list --status waiting_confirmation # Only tasks waiting for a response
cockpit task list --pinned                      # Pinned incomplete tasks, including Master Agent tasks
cockpit task list --all                         # All tasks in every status
cockpit task list --directory /path/to/repo     # Filter by directory (partial match)
cockpit task list --name "keyword"              # Filter by task name (partial match, case-insensitive)
cockpit task list --parent <id>                 # Lightweight parent and direct children
cockpit task list --parent <id> --recursive --all # Include every descendant and completed tasks
cockpit task list --summary                     # Lightweight active tasks
cockpit task current                            # Resolve the current task from this session
cockpit task get <id>                           # Latest 1 conversation turn
cockpit task get <id> --turns 3 --max-lines 500 # More history / larger terminal output
cockpit task goto <id>                          # Open Cockpit and select the task
cockpit task pin <id>                           # Pin a task in focus lists
cockpit task unpin <id>                         # Unpin a task
cockpit task project <id>                       # The project the task belongs to

--parent <id> selects the parent itself and its direct children on the server, across all directories. Add --recursive for all descendants; it requires --parent. An unknown parent returns HTTP 404 with code task_not_found.

Parent lists use the same filters as ordinary lists: completed tasks are excluded by default; --status completed selects completed tasks; --all includes every status and takes precedence over --status. --pinned takes precedence over both and selects pinned incomplete tasks. --directory (case-sensitive substring) and --name (case-insensitive substring) further narrow the result. Filters apply to the parent as well as its descendants, so a filtered-out parent does not appear. Recursive traversal still passes through ancestors excluded by these filters. No directory filter is implied by the caller's working directory.

--parent always returns lightweight summaries. Use --summary for the same format on a plain list. Each entry contains only id, name, status, stopReason, hasPendingAsk, parentMasterId (null for a root), directory, projectId (null for a task outside every project), agentType, createdAt, and updatedAt. hasPendingAsk reflects an unanswered Ask, independently of task status. A task resumed after completion reports its current running or waiting_confirmation status; there is no separate resumed status. updatedAt is the latest recorded creation, activity, or completion timestamp, not a timestamp for every metadata edit.

Summary responses retain the data array and add a response-level ISO 8601 generatedAt: {"ok":true,"data":[...],"generatedAt":"2026-09-15T12:00:00.000Z"}. Use it to compare snapshot age; the task store has no live snapshot revision (its persistence journal sequence does not track every in-memory change). Summaries exclude instructions, conversation, reports, model settings, and device details. Ordinary lists without --parent or --summary keep their existing format.

Full task list entries, task get, and the Hooks task payload carry projectId when the task belongs to a project (see cockpit help project).

cockpit task get <id> includes:

• model, effort, and serviceTier: the effective model, reasoning effort, and Codex speed tier selected for the task, or null when the task runtime does not expose them. The same stable fields are returned by full task list responses, task create, and under task in task run / task wait. Read or change this selection with task model <id> [<model>]
• agentSessions: one entry per agent session (segment) the task has used, oldest first: agentType, sessionId, accountProfileId, model, the number of turns that agent ran itself in that segment, origin (start, restart for a new session of the same agent, or switch), and, for a segment that received carried-over history, transplant with its method and counts
• pendingAgentSwitch: the agent switch scheduled for the next send (agentType, model, effort, serviceTier), or absent. See Switch Task Agent below
• conversation: normalized task history limited to the latest N turns. Each item has role, text, kind, and source; kind: "message" is a user/agent message and kind: "terminal_output" is raw terminal fallback. Cockpit agent and visual-mode message turns also carry the id used by cockpit pinned-answers, and pinned answers older than the window stay in the list (capped to a few lines). Cockpit switch dividers carry agentSwitch metadata, including the transplant method and omission counts, even when text is empty.
• terminalOutput: raw terminal output, useful for understanding live state while the task is waiting
• readyForNextPrompt: when status is waiting_confirmation, send a new prompt only when this is true; handle permission or question reasons as in-progress user confirmations
• waitingReason and optional waitingReasonSource (hook, status_file, pty_idle, pty_pattern, permission_queue, question_queue, sessionid_fallback, runtime_event, runtime_fallback)
• usageLimitAttribution: for a Codex provider limit, the exhausted accountProfileId (null for default), accountName, provider, and window (5h, 7d, credits, another Usage window label, or unknown when unspecified). source is provider_error or usage; explicit provider errors take precedence over cached Usage data. usageLimitResetAt belongs to that restriction. These fields clear when the restriction clears.
• statusSources: optional status source hints mirroring waitingReasonSource when available
• latestReportSeq: sequence number of the newest report. Use it as the --since cursor for cockpit task wait
• progress: whether the agent is still working, measured from its runtime events. lastRuntimeEventAt is when Cockpit last received any event from the agent runtime (streamed text, tool calls, status changes, or terminal output), whether or not anyone has the task open. turnStartedAt and turnElapsedMs describe the turn in progress and are null when no turn is running. turnToolCallCount counts the distinct tool calls of the turn in progress, or of the last turn when none is running. All fields are null (0 for the count) until the runtime emits its first event since Cockpit started. Judge a long turn by lastRuntimeEventAt, not by lastActivityAt, which drives unread badges and does not move while the task is on screen, and not by the agent's CPU usage, which stays near zero while it waits for the model
• turnRequests: the tool approvals and structured questions the task is waiting on, with the command or change being approved. See Turn Lifecycle below
• goal and goalCommandAvailable: the current Agent Goal (objective, state, and progress fields), absent or null when there is none, and whether the running agent accepts cockpit task goal start <id> right now. See Agent Goal below

turn_complete means one response turn completed and the task can accept another prompt. It does not mean the whole task is completed.

Full and summary task list, task get, and the task snapshot in task wait include the same derived stopReason: approval (waiting for a person's approval), turn_ended (one turn ended, task remains open), usage_limit, question, terminal_prompt, runtime_error, or unknown when no reliable cause was recorded. It is null while running or after completion. A session ID alone is not evidence that a turn ended. Desktop and mobile task lists and child panels use these same meanings. Resuming or answering the last approval clears the approval reason; other pending requests remain visible. hasPendingAsk remains independent of approvals.

Approval waits and their resolution also append child reports with approvalEvent: approval_waiting or approval_resolved. Resolution means the approval wait ended, not that approval was granted: it also covers interruption, errors, usage limits, and completion. These notices are not task-result reports. On an exit into error or completed, the notice retains the previous nonterminal status; the normal result report owns the terminal status and its error or completion payload. When consuming results, keep waiting after an approvalEvent using task wait --since <seq>; Fleet does this automatically, including for older saved notices with terminal statuses. Inspect task get for the current task state. Multiple pending permissions keep the child in approval-waiting until the last permission is resolved, even if a question also opens. A parent task receives the same transition through its existing persistent message queue, even after the child's first report was consumed. Busy parents receive it when ready for their next turn; completed or missing parents are not resumed. Duplicate state updates do not add another notification. This never approves a request or changes permissions, model selection, or the parent's pending agent switch.

Statuses

• needsResume: true -> the process stopped but the task is not completed (for example after an app restart). Resume with cockpit task resume <id>. A Terminal task resumes with a fresh shell in the same directory because its previous shell process cannot be restored.
• sessionUnrecoverable: true -> the visual conversation was rejected by its server after consecutive identical turn.completed failures. errorMessage / sessionUnrecoverableError hold the last error. Resume the same conversation will fail the same way; start a new conversation in this task with cockpit task resume <id> --fresh-session.
• startFailed: true -> the agent process never started, so there is no session to resume. launch holds the recorded command and prompt. Launch it again with cockpit task retry-start <id>; cockpit task resume <id> refuses this state and names retry-start
• isPinned: true -> the task is pinned in focus lists

Create

Use --directory /path/to/repo when working in an existing repository. If omitted, the task starts in a temporary folder. Use --project <id|name> to start in a project: without --directory the task starts in the project's primary folder, and a --directory outside the project fails with folder_not_in_project. A task created without --project joins a project by the rules in cockpit help project.

Use task model <id> <model> [--effort <effort>] [--service-tier standard|fast|ultrafast] to update an existing task’s creation-time model selection.

cockpit task create --instruction "Instruction text" --directory /path/to/repo
cockpit task create --instruction "Instruction text" --directory /path/to/repo --agent-type codex
cockpit task create --instruction "Check the work account" --directory /path/to/repo --browser-identity work
cockpit task create --instruction "Investigate the failure" --directory /path/to/repo --agent-type codex --model gpt-5.5 --effort high --service-tier fast
cockpit task create --instruction "Investigate deeply" --directory /path/to/repo --agent-type codex --effort high
cockpit task create --instruction "Review this repository" --directory /path/to/repo --agent-type qoder --system-prompt cockpit
cockpit task create --instruction "Instruction text" --directory /path/to/repo --agent-type codex --approval-mode full-access
cockpit task create --instruction "Review this screenshot" --directory /path/to/repo --agent-type claude --ui-mode visual --media shot.png
cockpit task create --instruction "Run in the terminal UI" --directory /path/to/repo --agent-type codex --ui-mode terminal
cockpit task create --instruction "Summarize the repository" --agent-type cockpit --model openrouter/openai/gpt-5.4 --effort medium
cockpit task create --instruction "npm test" --directory /path/to/repo --agent-type terminal --command "npm test"
cockpit task create --instruction "Instruction text" --directory /path/to/repo --worktree feature/my-branch
cockpit task create --instruction "Instruction text" --project Shop                  # Start in the project's primary folder
cockpit task create --instruction "Instruction text" --project Shop --directory ~/repos/shop-api --worktree fix/api
cat instruction.md | cockpit task create --stdin --directory /path/to/repo         # Long instruction, no shell quoting
cockpit task create --instruction-file instruction.md --directory /path/to/repo    # Same, from a file

Pass any instruction that is longer than one line, or that contains backticks, quotes, $, or a code fence, with --stdin or --instruction-file. Inside a double-quoted shell argument the shell runs backticks as command substitution and rewrites $..., so the instruction is already damaged before cockpit sees it — sometimes silently, sometimes as unmatched quote with nothing sent at all. --stdin and --instruction-file deliver the bytes unchanged, including the trailing newline.

Smart Routing

cockpit task create --instruction "Fix the flaky login test" --smart-routing
cockpit task run --instruction-file task.md --directory /path/to/repo --smart-routing

--smart-routing lets Smart Routing choose the agent, model, and reasoning effort the same way the new-task screen does when Smart routing is on. It uses the routing policy registered for the AGI account signed in to Cockpit — the one edited on the new-task screen and through cockpit settings get|set smartRouting.policy (see cockpit help settings) — and offers only installed agents that are turned on. Without --directory and --project it also chooses the workspace, from the same candidates as the screen's Auto workspace: recent and project folders, the Master Agent folder, a new temporary workspace, or a new persistent workspace. With --directory or --project the workspace stays as given and --worktree can be added. The flag does not depend on smartRouting.enabled, which only controls the switch on the new-task screen. A routed task starts in the visual UI mode with automatic account selection, and a model with no effort levels starts without one, even if an effort was saved for it before. A create key is reserved before routing starts, so a retry with the same --create-key waits for and returns the same routed task instead of routing again. Choosing adds time before the task is created: model discovery waits up to 20 seconds and the routing service up to 25 seconds.

Both task create and task run add data.smartRouting with the choice: agentType, model, effort (null when the model has no effort levels), and workspace with kind (project, master, temporary, or persistent), name, and directory. workspace is null when --directory or --project fixed it. The task's own agentType, model, effort, and directory fields show the same choice.

Because Smart Routing chooses them, --smart-routing cannot be combined with --agent-type, --model, --effort, --service-tier, --system-prompt, --ui-mode, --command, --account, --claude-profile, --codex-profile, --studio, or --branch-from; these, and --worktree without --directory or --project, fail with option_conflict. With --host it fails with host_not_supported, because the routing policy and sign-in belong to this device.

When Smart Routing cannot choose, the command returns ok: false with one of these codes and creates no task:

Calls without --smart-routing behave exactly as before.

Branch With History

cockpit task create --branch-from <source-id> --agent-type codex --ui-mode visual --instruction "Review the design from another perspective"
cockpit task create --branch-from <source-id> --agent-type claude --instruction-file follow-up.md --confirm-stop

--branch-from is available on task create and task run in both launchers. It uses the source task as parent by default and defaults to its directory when --directory is omitted. Choose the target with --agent-type. A different agent receives the conversation through the full-history transplant engine in a new session. The source conversation and native session remain unchanged. Same-agent Claude branching uses the native fork; agents without native fork support keep the existing explicitly labeled summary handoff.

If the source is running or waiting for a tool approval, the request fails until you explicitly add --confirm-stop. This stops the source and waits for execution to end before launching the branch. Tasks sharing a branch directory cannot run concurrently; stop the active task before resuming the source or another task there. A separate directory can be supplied for comparisons.

Cross-agent branches require a visual source task and do not support Fleet, Autorun, master, or terminal tasks. No shortened conversation handoff is substituted if full-history transfer fails. The target receives messages, tool calls and results, file changes, and supported images through the existing transplant engine. For embedded-resource targets, long tool outputs are reduced first when necessary, then middle exchanges; the first request and latest exchanges are retained. No extra summarization call is made. The desktop and mobile preview and the chat divider report omissions. The CLI result includes the branch origin; review the divider for delivery details.

The desktop and mobile usage-limit notice also offers Continue with … for signed-in agents with known available quota. Unknown quota, expired credentials, and exhausted accounts are excluded. Availability is checked again on tap, the same task switches agent, and a continuation of the last request is sent after transplant. The notice explains that the history is sent to the selected provider.

Parent And Creator

task create and task run use the same parent contract. Omit both options to keep the caller task as parent (or no parent when there is no eligible caller). Use --parent-task-id <id> to select an explicit parent, or --top-level to create an independent task with no parentMasterId. A top-level task appears in the normal top-level list; pass --pin to pin it at creation, or pin it later with task pin <id>.

The name --top-level describes the resulting hierarchy directly. The task control API represents it as boolean topLevel: true; omitted or false preserves the existing default. topLevel must be a boolean. Combining topLevel: true with any supplied parentTaskId is rejected. A supplied parentTaskId must be a non-empty string after trimming; empty strings, whitespace-only strings, null, and other types are rejected rather than falling back to the caller. Both CLI launchers reject --top-level together with --parent-task-id (including a blank value), and reject blank parent IDs with invalid_option before creating a task. Missing parent option values are rejected with option_required.

Creator attribution is retained: createdByTaskId records the resolved calling agent task independently of parentMasterId, including for top-level creation and when an explicit different parent is selected. It remains in persisted task data and task API responses. Hooks use the parent link too: task.isChild and COCKPIT_TASK_IS_CHILD are false for a top-level task, so --no-child matches it and --child does not, even when createdByTaskId is retained. No creator is invented when the caller cannot be resolved. These options only affect creation; they do not change an existing task's parent.

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

--approval-mode sets the task's own approval mode at creation, overriding the global defaultApprovalModes setting for that task alone. It applies to Cockpit Agent tasks and to Claude, Codex, Antigravity, Cursor, Qoder, Grok, and Muse Code tasks running in visual UI mode; terminal UI modes and the terminal agent reject it instead of ignoring it. Change it later with task approval-mode <id> <mode>. Muse Code accepts only accept-edits (the default) and full-access: Muse Code never asks before editing files in the workspace, so Cockpit does not offer supervised for it and rejects that value with approval_mode errors instead of pretending to enforce it. task approval-mode <id> returns supportedApprovalModes for the task's agent.

Model selection is limited to runtimes that consume the existing model settings: cockpit, Claude visual, Codex visual, Antigravity visual, Cursor visual, Qoder visual, Grok visual, and Muse Code visual. Antigravity visual model ids come from agy models, plus auto-gemini-3 which lets the CLI pick. Terminal UI modes and unsupported agents reject the option instead of ignoring it. --effort remains limited to Cockpit, Claude visual, Codex visual, Antigravity visual, Cursor visual, Grok visual, Qoder visual, and Muse Code visual. --service-tier is limited to Codex visual tasks. --system-prompt accepts built-in presets or names from cockpit system-prompt list; --system-prompt-preset remains a compatibility alias. Pass --ui-mode visual to create a visual-runtime task without changing the agent's Settings default; --ui-mode terminal does the same for the terminal UI. terminal and cockpit reject --ui-mode because they are not switchable. A missing path, a directory, an empty or oversized file, an unsupported type, or a kind the chosen agent cannot attach natively is rejected before the task is created.

cockpit effort values are none, minimal, low, medium, high, and xhigh. Claude visual accepts low, medium, high, xhigh, max, and ultracode. ultracode is Claude Code's ultracode mode: xhigh effort plus multi-agent workflows on every substantial task. It is available on models that support xhigh, and it runs as plain xhigh when Claude Code has dynamic workflows turned off. The ultracode keyword opts a single Claude turn into multi-agent workflows only when the user types it in the Cockpit app; text sent through task create or task send does not trigger it, so use --effort ultracode there. Codex visual accepts low, medium, high, xhigh, max, and ultra; minimal is not accepted because the visual runtime normalizes it to low. Antigravity visual accepts low, medium, and high; auto-gemini-3 rejects a separate effort because the CLI chooses it. Grok visual accepts low, medium, high, and xhigh, and only when the selected model advertises reasoning effort. Qoder visual accepts none, low, medium, high, xhigh, and max, and only when the selected model advertises reasoning effort. Cursor visual accepts minimal, low, medium, high, xhigh, and max, per model — the levels mirror the thought level in Cursor's model picker (Cursor's extra-high maps to xhigh), a model with no thought level (composer-2.5, auto) rejects the option, and a model id that encodes a level (claude-sonnet-5-thinking-high) applies it without --effort. Cursor's cursor-grok-4.6-low, cursor-grok-4.6-medium, cursor-grok-4.6-high, and cursor-grok-4.6-xhigh CLI ids resolve to the ACP model grok-4.6 with the encoded effort. Muse Code visual takes its models and their efforts from Muse Code itself (model/list); there is no built-in list, and Muse Code lists no models until you sign in. Muse Code's list comes from a cached catalog that muse serve only reads; the terminal app (muse) refreshes it when it starts. Cockpit keeps it current itself: when Muse Code answers with its built-in list, when the cached catalog is more than 12 hours old, after a sign-in, or when the model list is reloaded, Cockpit starts the terminal app hidden in an empty temporary folder for a few seconds (no prompt is sent, so no model is called) and lists again. If that fails, the list stays Muse Code's built-in one and Cockpit tries again after 10 minutes. task create and task model accept any Muse Code model id, and the effort names of Muse Code's protocol (none, minimal, low, medium, high, xhigh, max, and ultra), without checking them against that list. A model Muse Code does not list is sent to Muse Code as entered, and the conversation gets a one-line note where it takes effect; if Muse Code cannot serve it, the next message fails with Muse Code's own error. For a listed model, an effort the model does not advertise is replaced by that model's default level, and a model advertised without levels runs without an effort. An unlisted model always runs at Muse Code's default level: Cockpit sends no effort for it, and task model rejects --effort with one. Without a chosen model, a new session starts on the default model of Muse Code's list (when that default is a contributor model, its non-contributor variant or the first non-contributor model). Muse Code's own default setting, which can name a contributor model, applies only while the list offers no non-contributor model, for example before sign-in. An explicitly chosen contributor model (an id ending in -contributor) gets a one-line note where a session starts on one or switches to one. agents.museContributorModelsEnabled (default false) shows Contributor models from the active Muse Code catalog in the model menus. Turning it on does not select one. Cockpit enables Contributor mode only for an explicitly selected Contributor model and disables it for standard models. The note scrolls away with the conversation; it is not repeated while the same model stays in use, including when the session is resumed. Known Claude, Codex, Cursor, Grok, and Qoder models are validated against their model-specific capabilities. Unknown dynamic models use the agent's effort enum so newly available models are not rejected only because the local catalog has not caught up.

When an LM Studio task has no configured model, Cockpit selects the first loaded usable model at the first prompt. The immediate create response may return model and effort as null; after runtime resolution, task settings and subsequent list/get/run/wait responses contain the selected lmstudio/<id> and its effective effort.

Creative Studio examples (model requires the modeling toolchain set up in the app first):

cockpit task create --instruction "A toy car that rolls when printed" --studio model
cockpit task create --instruction "A picture book for 4-year-olds about a lost fox cub finding its way home" --studio picturebook

Delegate And Wait (Preferred)

Prefer cockpit task run when delegating work. It creates the task and blocks until the first report, then returns report with status (waiting_confirmation, error, completed), waitingReason, seq, and the task's latest message in report.message — no polling needed.

Creation and waiting are separate operations. After creation succeeds, task run always returns ok: true with data.taskId, even if the first report cannot be retrieved. A normal deadline sets data.timeout: true; another wait failure sets data.waitError with code and message. Do not retry the instruction after either result because the task already exists. data.account, when present, identifies the account profile actually selected, including an Auto fallback. task create also adds data.taskId and data.account to its existing task fields.

Creation failures return ok: false, and no task is created. This is deliberately different from the app's own UI: the desktop screen and the PWA never discard a prompt, so when a task cannot be started there they keep the task, mark it status: "error" with startFailed: true and the reason in errorMessage, and show that reason inside the task so the person can edit the prompt and run it again. A task in that state has never run; task list and task get report it like any other errored task, with startFailed: true and the recorded command and prompt under launch. Launch it again with cockpit task retry-start <id> instead of creating a new task. The CLI keeps the stricter contract for its own creations because agents branch on it. Stable creation error codes include no_signed_in_account when the target has no usable signed-in account for the requested agent, authentication_failed when remote credentials are rejected, and host_unreachable when the remote host cannot be reached. The local transport equivalent is task_server_unreachable. Only local reachability errors advise checking whether AGI Cockpit is running; remote reachability errors advise checking the host, port, and network.

Create Keys And Lost Acknowledgements

Every task create and task run sends a create key (createKey in the request body): a UUID generated by the CLI, or the value of --create-key. Cockpit remembers the task created for each key for ten minutes, scoped to the calling task and device, so a replayed create with the same key from the same caller returns the already-created task with data.replayed: true instead of creating a second one; a different caller using the same key gets its own task. GET /tasks/created?createKey=<key> (remote: /api/task-cli/tasks/created) returns the same record, or 404 with code task_create_not_found when nothing was created for that key.

When the connection drops after the create request was sent but before the response arrives (connection reset, empty reply, or a send/receive timeout), the CLI does not report a blind failure. It first queries the key; if the task exists it is returned with data.replayed: true, so a lost acknowledgement still yields exactly one task and its id. Only when the target answers task_create_not_found does the CLI replay the create with the same key — a target that does not answer the key lookup (an older Cockpit) is never replayed against, so a lost acknowledgement never produces more than one task there. A replay that is rejected by the target is reported only after the key lookup has confirmed again that nothing was created. Only when Cockpit confirms that nothing was created does it return ok: false with code task_create_interrupted; the same command can then be run again safely. When the outcome cannot be confirmed at all (the target stopped answering, or it does not support create keys), it returns ok: false with code task_create_outcome_unknown and the key in createKey. In that case check cockpit task list for the task before creating again: the key registry lives in the running app, so after the app quit or restarted a rerun with the same --create-key creates a new task rather than returning the surviving one. Errors whose request never reached Cockpit (connection refused, unknown host) keep task_server_unreachable / host_unreachable.

cockpit task create --instruction "Instruction text" --directory /path/to/repo --create-key deploy-2026-09-05-1
cockpit task create --instruction "Instruction text" --directory /path/to/repo --create-key deploy-2026-09-05-1   # Same task, data.replayed: true

cockpit task run --instruction "Instruction text" --directory /path/to/repo --agent-type codex
cockpit task run --instruction "Review this change" --directory /path/to/repo --agent-type codex --model gpt-5.5 --effort high --service-tier fast
cockpit task run --instruction "Instruction text" --directory /path/to/repo --timeout 300
cat instruction.md | cockpit task run --stdin --directory /path/to/repo --agent-type codex
cockpit task run --instruction-file instruction.md --directory /path/to/repo --agent-type codex
cockpit task wait <id>                            # Return the latest report, or block until the next one
cockpit task wait <id> --since <seq> --timeout 110
cockpit task send <id> --text "continue" --wait   # Send a prompt and block until that turn's report
cat message.md | cockpit task send <id> --stdin --wait

Every task keeps a persistent report log. A report is appended when a turn completes, the runtime errors (status: error with the error message — including startup failures), or the task completes. report.seq increases per task. task wait is level-triggered: without --since it returns the latest report immediately when the task is at rest; pass --since <last seq you processed> to block until the next new report. A {"timeout": true} result is normal — re-run task wait to keep waiting, or run it in the background with a larger --timeout for long tasks.

Ordinary turn-result reports do not inject a prompt into another task or resume a parent task. Approval-waiting and approval-resolved reports are the exception: they also queue a status notification for the existing parent, delivered when it is ready for another turn. Nesting via --parent-task-id identifies that parent and controls the task hierarchy shown in Cockpit. Use task run, task wait <id>, or task send <id> --wait whenever an agent needs a child result.

Respond

cockpit task send <id>              # Send Enter for approval or continue
cockpit task send <id> --text "yes" # Send text
cockpit task send <id> --text "2"   # Send a choice number
cockpit task send <id> --text "See this screenshot" --media shot.png
cat message.md | cockpit task send <id> --stdin   # Long or Markdown message, no shell quoting
cockpit task send <id> --text-file message.md     # Same, from a file

Use --stdin or --text-file for anything longer than one line and for anything containing backticks, quotes, $, or a code fence. A message embedded in a double-quoted shell argument is rewritten by the shell before it reaches cockpit: backticked spans run as commands and disappear, and an unbalanced quote aborts the command so nothing is sent.

Turn Lifecycle

The turn lifecycle is everything that happens between sending a prompt and the task coming back to rest: a tool-approval prompt, a structured question, the running turn itself, and the thread the turn accumulates. Every one of these is operable from the CLI, through the same main-process implementation the desktop screen uses.

cockpit task get <id>                           # turnRequests: what is waiting, before you decide
cockpit task approve <id>                       # Allow the pending tool approval, this time only
cockpit task approve <id> --scope always        # Allow it and remember the decision
cockpit task deny <id>                          # Reject the pending tool approval
cockpit task answer <id> --text "Option A"      # Answer the pending structured question
cockpit task cancel <id>                        # Stop the running turn; the task survives
cockpit task compact <id>                       # Compact the thread
cockpit task clear <id> --confirm               # Reset the thread (destructive)
cockpit task approval-mode <id>                 # Read the task's approval mode
cockpit task approval-mode <id> full-access     # Change it for this task only

Read turnRequests in cockpit task get <id> before approving. Each entry has requestId, kind (approval or question), requestType (for example command_execution_approval), detail (the command or change being approved, when the runtime supplies it), openedAt, and for questions questions with each question's id, options, multiSelect, allowCustom, and required (when supplied). An empty answer group is accepted only when required is false. It is populated for Cockpit Agent tasks and for visual-runtime tasks, and lists only the requests the runtime still holds, so what you see is what approve and answer can act on.

approval-mode returns data.approvalMode, the mode in effect, and data.supportedApprovalModes for the task's agent. auto hands approval to the agent's native reviewer: Claude's auto permission mode, Codex's auto_review approvals reviewer, or Grok's auto permission mode. The reviewer allows routine actions, blocks risky ones, and still sends an action to the task's approval queue when it needs a person; it never answers questions or Asks. A Claude change applies at once. A Codex change applies from the next turn. A Grok change into or out of auto restarts the idle session and keeps the conversation; while Grok is still working (a turn, a pending request, or background work), the change fails with an error and the current mode stays. In every other mode Grok is started with its prompting default permission mode, so Cockpit's approval mode applies whatever the Grok config sets. When Claude or Codex cannot run in auto (for example its model, account, or organization does not allow it), Cockpit switches the task to the mode actually in effect and posts a notice in the chat. Cockpit cannot read back the mode Grok runs in, so this check does not cover Grok. Cockpit never falls back to full-access.

Every command answers ok: true with data.runtime (visual-runtime or cockpit-agent) and data.agentType; the request commands add the data.request that was acted on and data.remaining pending requests. deny selects only approval requests. MCP form elicitations are questions: fill them with answer, or decline them in the desktop or PWA question card. deny takes no --scope and no message: neither runtime accepts a scoped rejection or a rejection reason, so explain a refusal with cockpit task send <id> --text "..." after denying.

compact and clear refuse a task whose turn is still in flight — running, or parked on an approval or a question (task_turn_in_flight, exit 3) — exactly as the desktop screen does, because both would interrupt that work. Wait for the turn, answer the prompt, or cancel it first. clear also resets the conversation in every open desktop and mobile view of the task and hides the original instruction from then on, including in task get; a message someone is still typing in another window is kept.

When the caller is itself a Cockpit task, the decision is attributed to that agent (lastSentBy: "agent"), not to the human operator.

Which Tasks Have A Turn Lifecycle

• Claude, Codex, Grok, and Muse Code in visual UI mode: all seven commands. For Muse Code, approve --scope always uses the narrowest persistent rule Muse Code offers for that request (a session-scoped rule when no persistent one is offered), and deny rejects the call; Muse Code reports the rejected call to the model and the turn continues. Muse Code asks about each stage of a shell command (a | b, a && b, a; b) separately; one approve covers every stage of the command shown in detail, and deny rejects the whole command.
• Cursor and Qoder in visual UI mode: every command except answer, which is refused.
• Antigravity in visual UI mode: cancel, compact, clear, and approval-mode; approve, deny, and answer are refused because its headless CLI never raises approval or question prompts.
• Cockpit Agent: every command except compact and clear, which are refused.
• Any agent in terminal UI mode, and the terminal agent: none; all seven are refused.

A refused command answers turn_lifecycle_action_unsupported, or turn_lifecycle_unsupported for a terminal-mode task, and exits 1. Cursor and Qoder have no structured-question channel, Antigravity has no prompts at all, and a terminal-mode task has no approval prompt, no cancellable turn, and no thread: its agent runs inside a pty and is driven with cockpit task send. No combination answers a silent success.

Exit Codes

• 0: the operation was applied, for example the approval was released.
• 1: the command cannot apply as written, for example a missing --confirm, an unknown task, an invalid mode, or a refused combination.
• 3: the task is not in that state right now, for example nothing is pending, no turn is in flight, a turn is still running, or the runtime could not be queried.
• 7: AGI Cockpit could not be reached.

A 3 can succeed if you run it again later; a 1 cannot. Exit 3 codes: task_no_pending_approval, task_no_pending_question, task_no_active_turn, task_turn_in_flight, task_request_not_found (including a request the runtime no longer holds), task_request_kind_mismatch, and task_requests_unavailable (the runtime could not be queried, so the task's state is unknown). Exit 1 codes: turn_lifecycle_unsupported, turn_lifecycle_action_unsupported, task_not_found, task_clear_confirmation_required, task_approval_mode_invalid, task_answer_required, task_answer_count_mismatch, task_answer_question_not_found, task_answer_multiple_not_allowed, task_answer_choice_invalid, and task_answer_unsupported_request. Errors about pending requests carry details.pending with each request's id, kind, type, and detail.

Answering Questions

Answer every question the request asks. For single-answer questions, pass one --text per question in the order they were asked. For a multi-select question, or to name questions explicitly, give each question its own --question <questionId> group with one or more --choice values. --text and --question cannot be combined.

cockpit task answer <id> --text "Yes"
cockpit task answer <id> --text "Yes" --text "Use the staging database"
cockpit task answer <id> --question env --choice staging --choice production --question confirm --choice Yes
cockpit task answer <id> --request req_8f21 --text "Yes"

Answers are validated against the question before anything is sent: a single-answer question rejects several values (task_answer_multiple_not_allowed), and a question that does not allow custom input rejects a value that is not one of its option labels (task_answer_choice_invalid, with details.choices). A wrong count fails with task_answer_count_mismatch and details.questions, so one extra call tells you what to send. task answer answers the runtime's own structured question; a question raised with cockpit ask is answered with cockpit ask answer.

Agent Goal

An Agent Goal is a persistent objective the agent keeps working toward across turns. The desktop screen starts one with /goal; the CLI starts the same goal through the same main-process implementation.

cockpit task goal start <id> --objective "Make the test suite pass"   # Short objective
cockpit task goal start <id> --objective-file goal.md                 # Long objective from a file
cat goal.md | cockpit task goal start <id> --stdin                     # Long objective from standard input
cockpit task get <id>                                                 # Read the current goal: `goal` and `goalCommandAvailable`

Starting a goal sends the agent's goal command with the objective as a user message, so the task moves to running like any other prompt. There is no stop or clear command, on the CLI or in the app: a goal ends when the agent completes it or the thread is cleared. task get and task list report the current goal as goal (absent or null when none) and goalCommandAvailable.

Finish And Clean Up

cockpit task complete <id>                 # Stop the process and move the task to completed. Worktrees are deleted automatically
cockpit task complete <id> --keep-worktree # Complete but keep the worktree
cockpit task remove <id>                   # Remove from Cockpit (complete + delete)
cockpit task resume <id>                   # Resume the session for a stopped task
cockpit task resume <id> --fresh-session   # Start a new conversation in this task, seeded with a summary of the previous visual history
cockpit task retry-start <id> --directory /path/to/folder # Choose a different working folder before retrying
cockpit task retry-start <id>              # Launch a task whose agent process never started (`startFailed: true`), with its saved prompt
cockpit task retry-start <id> --instruction-file prompt.md   # Same, replacing the saved prompt (or `--stdin`; a terminal task replaces its command)
cockpit task reconnect <id>                # Restart the agent process of a visual task in place, keeping its conversation (after signing the account in)
cockpit task rename <id> --name "New name" # Rename the task

resume and retry-start are different operations. resume restarts the stopped session of a task that has already run at least once (needsResume: true). retry-start launches a task that never ran because its agent process failed to start (startFailed: true), reusing the same task and its saved prompt exactly as the desktop retry does; a retry that fails again keeps the task retryable. Each command refuses the other's state with exit 3 and an error naming the command to use (task_launch_failed -> use retry-start; task_not_launch_failed -> use resume), and both refuse a completed task (task_completed, exit 3). task_start_retry_unavailable (exit 3) means there is nothing to retry: the task did not fail to launch and has no stopped session to resume (normally because it is live). A retry-start whose launch fails again answers task_start_failed (exit 1) with details.retryable: true; when the failure is reported later by the runtime, the command succeeds and task get shows startFailed: true again. Either way the task keeps its prompt and can be retried.

retry-start --directory changes the working folder only for an unstarted standalone task. The folder must already exist. Existing sessions, branches, child tasks, master tasks, and worktrees cannot change folders through retry. The prompt and attachments are retained; the task is reassigned to the project containing the new folder, if any. Missing folders are never created automatically.

A failed branch whose source is running (including an approval or question wait) requires fresh confirmation on every retry. After confirming with the user, pass cockpit task retry-start <id> --confirm-stop to stop the source before starting the child. Without the flag it returns branch_stop_confirmation_required (exit 3) and leaves both tasks unchanged. Desktop and PWA ask for this confirmation when needed. Stop consent is never saved in the task's launch settings.

reconnect is the third, separate operation: the desktop's sign-in retry. A visual task whose agent reports an authentication error mid-session keeps its process alive, so needsResume stays false and resume reports alreadyResumed: true without restarting anything. After signing the account in, cockpit task reconnect <id> restarts that agent process in place through the same per-agent retry the desktop uses, resuming the existing session (sessionId) for every visual agent so the conversation continues; a task that never got a session starts from its saved prompt. It only applies to a task running in visual UI mode (task_reconnect_unsupported, exit 1, otherwise), refuses a task that never started (task_launch_failed -> use retry-start) and a completed task (task_completed), both exit 3, and, like compact and clear, refuses to interrupt a turn that is running or parked on an approval or question (task_turn_in_flight, exit 3, with details.pending) — a sign-in error finishes its turn, so the legitimate case is never in flight. A reconnect whose process cannot start again fails with exit 1 and the runtime's own message; resume --fresh-session remains the way to start over without the previous conversation.

Do not complete or remove tasks unless the user explicitly instructs you to do so.

complete interrupts a turn that is still running or waiting on an approval or a question. When the task is an active Fleet node, Fleet records that as a user interrupt: the node becomes interrupted with failureReason: user_interrupt, the Run pauses, and no output_contract correction turn is sent. Output the node had already submitted with cockpit fleet output is kept and the node completes. Completing a task whose turn has already finished is an ordinary completion.

A visual Grok, Cursor, or Qoder turn whose agent sends nothing at all for 18 minutes ends as a failed turn with waitingReason: runtime_error; its report carries errorReason: "stalled", and Cockpit stops the unresponsive agent process so the next message starts it again on the same conversation. This applies to turns the agent starts on its own as well. Waiting on an approval, a question, a background task, or a tool call that is still running, such as a long test command, does not count as silence. Separately, a Grok, Cursor, or Qoder turn always ends after 12 hours, even while it waits on one of those; that report has no errorReason and Fleet does not retry it. An Antigravity visual turn whose scheduled or background continuation tracking times out without a final response also ends as a failed turn with waitingReason: runtime_error and errorReason: "continuation_timeout"; Cockpit stops waiting and accepts new input without resending the prompt automatically. A turn that Cockpit itself stops, for example with task complete, is recorded as interrupted, not failed.

Task Project

cockpit task project <id>                          # Read the task's project
cockpit task project <id> <id|name>                # Move the task and its child tasks to another project
cockpit task project <id> --project <id|name>      # Same, with an explicit option

Returns id, projectId, and the full project; both are null for a task outside every project. Moving also moves the task's child tasks and lists every moved task in movedTaskIds. The agents use the new project's folders from their next session. Master Agent and Creative Studio tasks do not belong to projects and fail with task_not_movable. Project names are matched as in cockpit help project, including ambiguous_project and project_not_found.

Switch Task Account

cockpit task account <id>           # Show the account the task runs on
cockpit task account <id> work      # Switch to the account named "work" (name or profile id from `cockpit accounts`)
cockpit task account <id> default   # Switch back to the default account

Switching works mid-task for Claude, Codex, Grok, Antigravity, Cursor, and Qoder tasks: the running session stops, its transcript moves to the target account, and the same session resumes there. The target account must be signed in. If the previous turn stopped with waitingReason: "usage_limit", send a prompt after switching to continue the work on the new account.

Switch Task Model

cockpit task model <id>
cockpit task model <id> <model> [--effort <effort>] [--service-tier standard|fast|ultrafast]

The GET form reports the effective model, effort, and serviceTier, using the same fields as task get. Use this command to change the --model, --effort, and --service-tier selection after task create.

A switch preserves the conversation and runtime. It takes effect when the next turn is sent; an in-flight turn keeps its current model. No restart or --fresh-session is needed. A successful switch clears the task's usage-limit waiting state so you can send another prompt or retry a Fleet message node.

Claude, Codex, Antigravity, Cursor, Qoder, Grok, and Cockpit support model selection in their visual runtime. Terminal tasks and terminal agent runtimes reject this command. Resume completed tasks before switching. Models are validated against the agent's available catalog; invalid choices return the valid options. To move a visual task to another supported agent, add --agent-type (see Switch Task Agent).

--effort and --service-tier use the same validation as task creation. Without --effort, an effort encoded in a model alias takes precedence, then a supported current effort is retained; otherwise the new model's default is selected and reported in effortFallback: { previous, selected } alongside the effective selection. selected is null for models without effort controls. Service tier is Codex-only: an explicit fast or ultrafast tier that the new model does not offer is rejected, and an omitted tier falls back to standard when the new model does not offer the current tier.

Claude effort changes (including automatic fallback) are saved for the next session start. Its current SDK query keeps the effort chosen when it started; task model returns effortAppliesOn: "session_restart" to distinguish the saved effort from the running effort. The model itself still changes on the next turn without restarting.

Switch Task Agent

cockpit task model <id> gpt-5.5 --agent-type codex             # Claude Code task -> Codex on the next send
cockpit task model <id> claude-opus-4-8 --agent-type claude    # Codex task -> Claude Code on the next send
cockpit task model <id> <current-agent-model>                   # Cancel a scheduled switch

--agent-type claude|codex|grok|cursor|qoder|antigravity|cockpit with a model of another agent schedules an agent switch in the visual UI. The response keeps the current agentType, model, effort, and serviceTier and adds pendingAgentSwitch; --effort and --service-tier apply to the new agent's model and use the same validation as task create. Choosing a model of the current agent, with or without --agent-type, cancels the scheduled switch. Fleet, Autorun, and Master Agent tasks, terminal-UI tasks, and tasks that are running or waiting on an approval or a question reject the switch and name the reason. As with other model changes, resume a completed task before scheduling a switch; on a completed task, a model of the current agent only cancels a scheduled switch and leaves the model unchanged.

The switch runs on the next task send (or desktop/mobile send), before the message is delivered:

• The conversation is carried over: messages, every tool call with its input, output, exit code, and status, file changes, images, and the agent's own compaction summaries. A note before the carried-over part names the agent and model that produced it. Thinking and encrypted reasoning are not carried over.
• Returning to an agent the task used before resumes that agent's own session (a Claude Code session is duplicated first, so the original transcript stays untouched) and adds only what happened while it was away. An agent used for the first time receives the history since the task's conversation last restarted. If the earlier session cannot be resumed, a new session receives the full history instead of starting empty.
• Codex receives the history through thread/inject_items. Claude Code receives a synthesized session transcript that is checked with the Claude Agent SDK before it is resumed; when Cockpit's startup self-test cannot read such a transcript for the installed Claude Code version, the history is passed as one context message instead. agentSessions[].transplant.method records codex_inject, claude_session_file, or claude_message.
• Grok, Cursor, and Qoder receive an embedded history resource on the next prompt when supported, otherwise plain text; images require advertised image support and an unsupported image rolls back the switch before delivery, leaving the previous agent active and the switch cancelable; Antigravity receives the same history in its prompt with image attachments. Their native sessions are resumed on return. Qoder JSONL and Grok multi-file session synthesis are not used because a compatible, consistent native import cannot be verified through their supported interfaces. The method is embedded_resource.
• Cockpit reads all OpenCode message pages and appends the history with session.prompt({ noReply: true }), preserving images without generating a reply. The method is opencode_message. These targets receive one history message, which the preview explains.
• ACP/Antigravity history is reduced deterministically when necessary: shorten long tool outputs first, keeping every conversation message; then retain the first request, initial exchanges, and recent exchanges, replacing the middle with an explicit omitted-item count. No model summarizes it. The preview and divider report shortened outputs and omitted messages, tool calls, images, and summaries. A conservative UTF-8 byte estimate plus image allowance reserves 30% of the model context for instructions and the new turn; existing context is deducted on resume. If the reduced history cannot fit in the earlier session’s remaining allowance, a new session receives the full history and the preview/divider explain that decision. Known model context metadata is used when discovery is unavailable. If the first and latest exchanges cannot fit, the switch fails with an explanation.
• Claude Code and Codex still receive the full history and use their own compaction before the new message is sent.
• The conversation, including earlier turns, is sent to the new agent's provider (OpenAI for Codex, Anthropic for Claude Code).

If the switch fails, the message is not sent, the task stays on its previous agent, and pendingAgentSwitch remains so the next send retries; cancel it with a model of the current agent. When an earlier part of the conversation cannot be read (for example a transcript removed by the agent's retention cleanup), the rest is carried over, a note tells the new agent that part is missing, and agentSessions[].transplant.omittedParts counts it. When the conversation being left, or all of it, cannot be read, the switch fails with an error; the new agent never starts without it. Pending first-prompt history is retained after a rejected submission and is confirmed only by a prompt response or a conversation update. Older Antigravity tasks reuse available display history and disclose gaps; unreadable images or torn log entries do not discard readable messages. If ACP replay changes its saved boundary, all available history is carried over with an overlap/missing-history note. Confirmed history is not deliberately delivered twice.

Browser Identities

cockpit task browser-identity <id>                   # Show the task's assigned Browser Identities
cockpit task browser-identity <id> work              # Replace the assignment with this one Identity (name or id)
cockpit task browser-identity <id> default           # Return to only the Default Identity
cockpit task browser-identity                        # Show the calling task's assignment
cockpit task browser-identity work                   # Replace the calling task's assignment
cockpit task browser-identity --add work             # Also assign work to the calling task
cockpit task browser-identity <id> --add work        # Also assign work to another task
cockpit task browser-identity --primary work         # Use work when a browser command names no Identity
cockpit task browser-identity --remove work          # Unassign work
cockpit task browser-identity --task-id <id>         # Explicitly inspect another task from task context

A task can use several Browser Identities at once. Each Identity keeps its own browser sessions and tabs, so cockpit browser open <url> --browser-identity work and cockpit browser open <url> --browser-identity personal work side by side without changing the assignment. The primary Identity is used by browser commands that do not pass --browser-identity; tasks created without --browser-identity start with only the Default Identity as primary. Use at most one of --identity, --add, --remove, and --primary per command, once: combining them fails with option_conflict, and repeating one fails with option_repeated. --add and --remove do nothing when the Identity is already assigned or unassigned; --primary also assigns the Identity when needed; the primary Identity cannot be removed until another one is made primary. The JSON result reports identity (the primary Identity), identities (every assigned Identity, primary first), previousIdentity (the primary before the change), and changed. The task's browserIdentityId field holds the primary Identity id (absent for Default), and browserIdentityIds lists every assigned id when more than one is assigned.

Removing an Identity, or replacing the assignment, detaches the browser side panel only when it shows a session of an Identity that is no longer assigned; the panel then shows the primary Identity. Existing sessions stay with their original Identity and become available again when the Identity is assigned again. No operation copies or deletes cookies, cache, localStorage, or other browser data between Identities. Use cockpit browser identity list --json to discover names and ids.

Remote Devices

Task commands support --host; configure aliases with cockpit devices first, then target a remote Cockpit. --host can be placed before or after the subcommand, following the command family. The same remote options are available for autorun, accounts, fleet, hooks, and ask list/answer/close.

cockpit task list --host build-host
cockpit fleet list --runs --host build-host

Guidance

• Prefer delegating implementation work to Cockpit tasks when the user asks for orchestration or parallel work.
• Create tasks sequentially unless there is a clear reason to fan out.
• Inspect task output before responding to a waiting task; increase --turns or --max-lines when context is insufficient.
• Keep user-facing summaries concise and report unverified work plainly.