wularcoderBeta

task

run, follow and steer coding tasks

task run [prompt] [--output-schema <output-schema>] [--name <name>] [--agent <agent>] [--append-system <append-system>] [--wait] [--model <model>] [--access <access>] [--mcp <mcp>] [--connections <connections>] [--add-dir <add-dir>] [--server <server>] [--workspace <workspace>] [--yes] [--repo <repo>] [--runner <runner>] [--json] [--cwd <cwd>]

run a task (background; --wait blocks)

Dispatch a coding task to the configured engine. Backgrounds by default and prints a task id locally or with --server; --wait follows it to the answer. Shortcut: coder run "<text>".

Writing a task: one task per focused goal, independent goals as parallel runs. The worker starts with nothing but the text, so include the goal, file paths, constraints and any context only you have. Delegate rather than doing the work yourself first, however small it looks.

Waiting: run coder task result <task-id> --wait in its own background shell, one per task. Never wait on several tasks in one call, or their approvals and answers never reach you one by one.

Recommended, unless the user prefers otherwise or a model is unavailable:

  • sol or opus by default

  • luna or sonnet for mechanical work

  • opus for public APIs, SDKs and UI design

  • astra or fable for the hardest work; they cost the most

  • <prompt> the task text

  • --output-schema <output-schema> JSON Schema for the task answer

  • --name <name> label the task (shown in list/result)

  • --agent <agent> run as that agent: its system.md, engine settings, MCP servers and flows; flags override them

  • --append-system <append-system> standing instructions appended to Coder's system prompt (kept out of prompt previews)

  • --wait follow the task until the answer is ready

  • --model <model> model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high)

  • --access <access> read-only also restricts platforms and connections; auto lets the engine review what leaves the sandbox (default: auto)

  • --mcp <mcp> attach MCP servers from mcp in .coder/config.json by name (or all), or an inline JSON array [{"name","command","args","env","tools"}]; none by default, all adds your engine's own MCP servers

  • --connections <connections> use only these connections (coder connection list), within the agent's

  • --add-dir <add-dir> give the task another directory beyond --cwd (repeatable); read-only can only read it, auto can also write

  • --server <server> run the task on your Coder server and print its id (--wait follows it)

  • --workspace <workspace> with --server: the workspace to run in (default: the saved one)

  • --yes with --server: connect to a server used for the first time without asking

  • --repo <repo> with --server: check out a repo from the workspace's installs

  • --runner <runner> with --server: where it runs (a runner kind or a registered runner)

  • --json JSON output

  • --cwd <cwd> workspace directory; default current

Exit codes:

  • 0 The task started, or --wait printed a successful answer.
  • 1 Dispatch or the task failed.
  • 3 No engine could start; follow fallback.instructions in the JSON payload.
  • 4 An approval is pending; answer it, then run result --wait again.
  • 130 The foreground wait was detached and the task is still running.
coder run "add a /health endpoint"  # dispatch in the background, print a task id
coder result <task-id> --wait  # then block until it finishes and print the answer
coder run --wait "fix the failing test"  # or block on the run itself
coder task run --model luna --append-system "tests live in test/, don't touch anything outside of it" "rename foo to bar"  # pick an engine via its model alias; --append-system adds standing instructions
coder task run --agent reviewer "review the last commit"  # run a repo agent from .coder/agents/reviewer
coder run --add-dir ../api --add-dir ../shared "update the client for the new endpoint"  # let the task reach sibling repos too

task list [--running] [--stopped] [--archived] [--limit <limit>] [--cursor <cursor>] [--dir <dir>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

list recent tasks (by default running + just stopped)

List recent tasks across all workspaces, most recent first: running tasks plus ones stopped within the last 30 minutes. Older stopped tasks auto-archive and move to --archived. Shortcut: coder list.

  • --running show only running tasks
  • --stopped show only recently stopped tasks (not yet archived)
  • --archived show only archived tasks (auto-archived or via task archive)
  • --limit <limit> tasks per page (default: 50; all for every task)
  • --cursor <cursor> continue from the previous page cursor
  • --dir <dir> only tasks launched in that workspace
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current

task result [task-id] [--wait] [--turns] [--tail <tail>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

status + final answer (--wait blocks)

Show a task's status and its final answer (result pending while it runs), plus any pending approvals. --wait blocks until it finishes, then prints. --tail includes the last n progress-log steps (--tail all for the whole transcript). Defaults to the most recent task. Shortcut: coder result.

JSON and MCP return a summary and the complete answer, without engine diagnostics or raw diffs. Use --tail for progress; answers are never truncated.

Run each --wait in its own background shell, one per task. Never wait on several tasks in one call, or their approvals and answers never reach you one by one.

  • <task-id> the task (default: the most recent)
  • --wait block until the task finishes or needs an approval, then print
  • --turns every turn's answer (a steered task accretes turns)
  • --tail <tail> include the last n progress-log steps (default: 0, final result only)
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current

Exit codes:

  • 0 The task completed successfully.
  • 1 The task failed or was cancelled.
  • 4 An approval is pending; answer it, then run --wait again.
coder result <task-id> --wait  # block until the task finishes, print the answer
coder result <task-id> --turns  # every turn's answer for a steered task

task watch [task-id] [--tail <tail>] [--trim <trim>] [--from <from>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

stream a task's live transcript

Stream a running task's transcript live (for you/debugging), then print its final answer. Replays the last line first so the current step is visible; --tail replays the last n lines (--tail all for the whole transcript). Blocks until it finishes; exits 0 on success, 1 otherwise. For the answer alone, prefer coder result. Alias: stream.

With --from , or as a tool, it returns the log from event n on without following, and next: the command that continues it while the task runs.

  • <task-id> the task (default: the most recent)
  • --tail <tail> replay the last n log lines first (default: 1)
  • --trim <trim> budget for tool output and thinking (default: 1200 chars, 12 lines)
  • --from <from> return the log from event n on instead of following it
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current
coder task watch  # follow the most recent task to completion
coder task watch <task-id> --from 0 --json  # the log so far, and the command that continues it

task steer [task-id] [text] [--wait] [--model <model>] [--access <access>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

continue a task's thread

Continue a task's thread with new instructions. They are injected into a live Codex or Claude turn at its next tool boundary and queued across a startup or completion race. A stopped, finished, or archived task resumes on the same task id. It reuses the task's engine, model, and access unless overridden.

  • <task-id> the task to continue
  • <text> the follow-up instructions
  • --wait run in the foreground and block until the answer is ready
  • --model <model> model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high) for this follow-up
  • --access <access> lower the task's access for this follow-up
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current
coder task steer task-abc "now add tests"  # continue that task with a follow-up

task ask [task-id] [question] [--model <model>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

ask about a task without interrupting it

Answer a question ABOUT a task without touching it: a read-only sidecar reads the task's progress log, result, and workspace and answers; the task never sees the question and its thread is not steered. Works whether the task is running or stopped. To change what the task does, use coder task steer.

  • <task-id> the task to ask about
  • <question> the question
  • --model <model> model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high) for the sidecar (default: the task's own)
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current
coder task ask task-abc "what approach did you take and why?"  # probe a decision without derailing the task

task stop [task-id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

interrupt a running task

Interrupt a running task and mark it cancelled.

  • <task-id> the task to stop
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current

task archive [task-id] [--all-stopped] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

archive a session (or --all-stopped)

Archive a task session so it drops out of the default list (see it again with coder task list --archived [--limit N]). Pass --all-stopped to archive every finished task. A running task keeps running; steering an archived task brings it back.

  • <task-id> the task to archive
  • --all-stopped archive every stopped (finished) task
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current

task delete [task-id] [--all-archived] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

delete a session (or --all-archived)

Delete a task's session from disk. This is permanent. Pass --all-archived to delete every archived task at once. A running task must be stopped first.

  • <task-id> the task to delete
  • --all-archived delete every archived task
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current

task approvals [task-id] [--denied] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

pending approvals (all tasks, or one)

List pending approvals across all tasks, --denied the denied ones (still answerable), or every approval of one task.

  • <task-id> one task (default: approvals of every task)
  • --denied denied approvals instead of pending ones
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current

task approve [task-id] [approval-id] [--deny] [--reason <reason>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

answer an escalation

Answer an escalation the task raised. Accepts by default; --deny rejects it, --reason says why. Works any time, also after a deny: the task gets the decision as a message. Approval ids are unique, so the task id is optional.

  • <task-id> the task, or the approval id alone
  • <approval-id> the approval to answer
  • --deny reject the request instead of accepting
  • --reason <reason> why it is denied; the task reads it
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current