atriumatrium

Task dispatch

Binding an agent to a task card and resuming interrupted runs.

Task dispatch is atrium's pattern for assigning work to an agent. It links a task card to a pane, creates a run that tracks the execution, and gives the agent the environment it needs to report progress and completion.

See Tasks & runs for the underlying data model.

Launching from the UI

Open the task detail pane (Cmd+Shift+J, or click a row in the tasks list pane) and press the Launch button at the top of the card.

The dispatch dialog asks for:

  • Target pane — pick an existing empty pane or create a new one right from the dialog.
  • Adapter — Claude Code, Codex, Gemini, or any installed adapter.
  • Review status — which workspace status to move the card to when the agent signals "ready for human review".
  • Completion status — which status to move the card to when the agent signals done.
  • Execution mode — either current branch (the agent works on the currently checked-out branch) or worktree (atrium creates a fresh git worktree, a sibling atrium workspace for it, and the bound agent room in one shot, so the work is isolated from your main checkout).
  • Merge target — the base branch the agent is working toward; can optionally reuse an existing branch instead of creating a fresh one.
  • Adapter flags — optional per-launch tuning (YOLO, CLI args, model choice if the adapter exposes one).
Press Launch and atrium:
  1. Creates a new run against the card.
  2. Sets the card's current_primary_run_id to the new run.
  3. Injects ATRIUM_TASK_ID (the task's UUID) and ATRIUM_TASK_RUN_ID (the run's UUID) into the pane's shell.
  4. Sends the task title and description to the agent as the first user prompt.
  5. Focuses the pane and opens its activity card in the sidebar.
  6. Renames the room to include the task number and title (for example ATR-42 - Fix the auth middleware) so you can recognize task rooms at a glance.
The task detail pane now shows a live Runs timeline at the bottom with the new run at the top. Inline status, log preview, Cancel (while active), and Replay (when complete).

Launching from the CLI

For scripting or for one-off headless use, the CLI exposes the same operation:

"$ATRIUM_CLI_PATH" task launch ATR-42 \
    --pane-id <pane-id> \
    --adapter claude-code \
    --source user:me

Optional flags mirror the dialog:

  • --review-status <status-id> and --completion-status <status-id>.
  • --merge-target <branch> — informational; the base branch the agent is working toward.
  • --execution-mode current_branch — skip worktree creation.
  • --adapter-flags <json> — per-launch adapter-specific flags.

What the agent sees

Inside the pane, the agent has the usual environment plus ATRIUM_TASK_ID and ATRIUM_TASK_RUN_ID. A typical agent loop uses the canonical skill's atrium CLI commands:

# Pull the full task details
"$ATRIUM_CLI_PATH" task show "$ATRIUM_TASK_ID" --json

The agent does work and periodically posts status comments back to the task:

"$ATRIUM_CLI_PATH" task comment "$ATRIUM_TASK_ID" \
    --body "Starting work on the auth middleware" \
    --source "adapter:claude-code" \
    --kind agent-update

Comments show up live in the task detail pane's comment thread. The --kind value (discussion / instruction / agent-update) affects how the comment is rendered.

When the agent decides the work is ready for human review:

"$ATRIUM_CLI_PATH" task set-in-review

This reads $ATRIUM_TASK_RUN_ID and transitions the card to the review status you picked in the dispatch dialog. The detail pane updates immediately; the sidebar card's status flips.

When the agent wants to close the task directly:

"$ATRIUM_CLI_PATH" task set-done

Both commands accept an explicit --run-id <id> if the caller is outside the pane.

Handling interrupted runs

If a pane is closed or crashes mid-work, its run becomes interrupted.

From the UI, the tasks list pane's Interrupted filter chip isolates them. Open a run and press Resume in the run row — atrium asks for a fresh pane and adapter, then attaches a new segment to the same run.

Equivalent CLI flow:

"$ATRIUM_CLI_PATH" run list --state interrupted
"$ATRIUM_CLI_PATH" run show <run-id>
"$ATRIUM_CLI_PATH" run segments <run-id>
"$ATRIUM_CLI_PATH" run resume <run-id> --pane-id <new-pane-id>

Or cancel:

"$ATRIUM_CLI_PATH" run cancel <run-id>

The resumed run gets a fresh segment. The new pane receives the same ATRIUM_TASK_ID / ATRIUM_TASK_RUN_ID environment, so the agent can pick up without losing the link.

Multiple runs per task

A task can have many runs over its lifetime — an agent might make a first attempt, get cancelled, then come back and try again. The detail pane shows every run in chronological order, with status and inline logs. Runs are never deleted; cancelled and completed runs remain for history.