---
title: "Tasks — Robion user manual"
description: "A task’s life: new task or terminal, permissions and questions, states, splits, options, parking and resuming, ending, timeline, cost."
url: "https://robion.app/docs/tasks/"
lang: en
---

# Tasks

A task's life on the desktop: starting it, what its tab and the rail say, permissions and
questions, splits, parking, resuming, ending, its timeline, statistics and cost.

## Starting a task

- **+ new task** (⌘T, Task → New Task): "starts Claude Code in the project root; the name is
  filled in from the session" (the agent titles it). Next to it, on a git project, the **main
  checkout** / **own worktree** segment picks where it runs ([checkouts.md](https://robion.app/docs/checkouts/)); ⋯ opens the options.
- **NEW TASK OPTIONS** (⋯): a task name ("what the agent should do (task name)"), the first
  prompt ("first prompt for the agent (optional) — ⌘⏎ creates the task"; "handed to Claude Code
  at start-up as the task prompt"), the note "the task starts in the main checkout / its own
  worktree", **Claude Code sandbox** ("failIfUnavailable, no unsandboxed commands, ~/.ssh and
  ~/.aws denied"; caveats: gh, gcloud and terraform run outside the sandbox, jest needs
  --no-watchman, docker does not run inside, browser automation is heavily restricted, and since
  Claude Code 2.1.282 a project’s own `sandbox.excludedCommands` in `.claude/settings.json` /
  `settings.local.json` are ignored under Robion’s `allowUnsandboxedCommands: false` — such
  exceptions belong in `~/.claude/settings.json`), **add
  related projects (--add-dir)** (greyed without related projects), **create task**. "defaults
  come from the project settings": **⚙ → project → New task defaults**.
- No model or effort choice per task on the desktop. A workshop project's sessions get their
  own settings in **⚙ → application → Agent in workshop projects** (lower effort, plain output
  style, optionally another model; your saved Claude Code defaults are never changed). Tasks an
  automation starts run with the rule's **Model** (since 0.20.14, the AUTOMATIONS drawer, see
  [automations.md](https://robion.app/docs/automations/)).
- **+ terminal** (⇧⌘T, Task → New Terminal): "just a shell, without Claude Code".
- Other starts: an example card on **home**, ⌘K **new task**, **start a task** on a board card,
  **+ task** on a checkout row, an automation or the Steward, the phone.
- **⚙ → project → Port range**: "each task gets two ports (PORT, ROBION_PORTS)"; the top bar then
  shows **preview :port** (the same panel as Window → Browser, ⇧⌘B).
- **A task an agent started** (since 0.20.12): an agent may start a task of its own project
  from its session (the MCP tool `start_task`: a long rewrite beside it, a second opinion on its
  diff, variants to compare) and wait for the result (`wait_task`). The new task is an ordinary
  task — its own tab, dot, timeline, worktree by the project's **Tasks of the Steward and
  automations: own worktree** setting — and both timelines say so ("the agent started task
  …" / "started by the agent of task …"); in the TASKS section its worktree is tagged
  **agent**. One level only (a task started this way cannot start tasks), at most
  `agentTaskLimit` open per task (`config.json`, default 3; 0 switches it off). The agent
  cannot answer the new task's permissions or questions: those reach you as with any task.

## What the tab, the rail and the status line show

- A Claude Code tab: a state dot, the title, "CC" (a shell: "SHELL"), a stripe in the project
  colour; tooltip "right button: rename / end task", "own worktree · <branch>" for a worktree
  task, "· parked" when parked, "· restarting…" while its session restarts. Right button:
  **rename…** ("New task name"), maximize / restore, **activity…**, **restart session…**,
  **close panel (task keeps running)**, **close all tabs**, **end task**.
- States: working (the dot breathes slowly), waiting for you (amber, still — "asking for
  permission", "waiting for an answer", a choice in a dialog), error, done ("agent finished its
  turn — the result is waiting to be read"; clears once the pane is viewed), waiting for a
  prompt (idle), session ended. Amber is used only where a human is needed.
- Still working when the agent paused on something running in the background (since
  0.20.27): a shell started with run_in_background (a CI poll loop, a build), a workflow, a
  teammate, a cloud session — the status line and the hover card read "⏳ shell still running:
  <command>" and the task stays blue until the finished task wakes the agent up (its
  notification continues the turn) and that turn ends. Running subagents do the same ("⟲ n
  subagents working"). The one exception is a monitor Claude Code arms by itself (live updates
  of a published artifact): it outlives every turn, so it leaves the task done. A dev server
  left in the background keeps the task working until it is stopped (Ctrl-C it in the
  terminal, or end the task) — the status line names the command.
- The state follows a session another Claude client forked from the task's conversation as
  well (the Claude app, Remote Control — `claude --fork-session --resume`): the dot breathes
  while that fork works, its question or permission dialog shows as waiting for you (answer
  it in that client — no cards here), and the terminal keeps its own session. A fork ending
  does not end the task; the task ends with its terminal session. **restart session…** and a
  restart of Robion resume the newest of the task's conversations that no Claude Code process
  still runs (a fork the app drives keeps running in Claude Code's daemon, so the terminal
  keeps its own session until that fork has ended).
- The rail row's cell strip and hover card, the **OVERVIEW** groups and the status line ("n
  waiting for you", "n done") show the same states; the Dock badge counts agents needing you.
- Notifications (**⚙ → notifications → Notifications on this Mac**): "<task>: agent is asking for
  permission" / "agent is waiting for an answer" / "agent ended with an error" / "turn finished"
  — only while the Robion window is not active; clicking opens the task. The phone gets Web
  Push ([phone.md](https://robion.app/docs/phone/)).
- Prerequisite: Claude Code 2.1.287 or newer — Robion's hooks module loads into every session
  it starts ([settings.md](https://robion.app/docs/settings/), "How Robion sees a session"); a task whose session did not load it
  says so and its state stays unknown.

## Permissions, questions and permission modes

- A bar at the bottom of the terminal: "agent is asking for permission" / "agent is waiting for
  an answer in the terminal" / "agent is waiting for a choice in a dialog", the detail, a clock
  "waiting 00:41". A held permission has **allow** / **deny** ("the server is holding the hook —
  the answer goes straight to Claude Code"); otherwise "answer in the terminal". When subagents
  ask in parallel the bar shows the oldest request — the one on top in the terminal — with
  "1 of N"; **allow** / **deny** answer that one and the next moves up.
- The same allow / deny sits on the rail hover card and the overview tile; once the prompt is
  already in the terminal "the answer is sent as keystrokes".
- **⚙ → agents → Hold permission requests**: "how long the server holds the PermissionRequest
  hook when nobody is watching the panel (answer from the rail / phone); 0 = do not hold";
  **⚙ → remote access → Hold permissions for remote access** (max. 55 s) for the phone.
- The agent's question (AskUserQuestion) and plan approval are answered in the terminal on the
  desktop (a workshop project answers them in the design panel); the phone shows them as cards
  and the deck puts approvals on keys — [phone.md](https://robion.app/docs/phone/), [deck.md](https://robion.app/docs/deck/).
- Esc or "No" on Claude Code's own dialog: the task goes idle at once.
- Permission modes (manual / accept edits / plan / auto) are Claude Code's own: Shift+Tab in the
  terminal cycles them; the phone has a mode chip on the task screen.
- The mode a new task starts in is Claude Code's choice too, Robion does not set one:
  `permissions.defaultMode` in `~/.claude/settings.json` when it is set; otherwise, since Claude
  Code 2.1.284, every new task starts in **auto** and asks less (2.1.283 did that only with
  telemetry off or on a third-party provider; before that the default was manual). Set
  `permissions.defaultMode` to `default` to get manual back everywhere, or Shift+Tab per task.
- A session that comes back through `--resume` — **restart session…**, a parked task's
  **restart**, **Restore agents after start-up**, the pane host replacement, **resume** from
  recently closed — starts in the permission mode it ended in, plan mode included (bypass
  permissions is never restored; verified on Claude Code 2.1.291 and 2.1.292). Only a start
  from a handoff note starts like a new task.
- In auto mode Claude Code asks once by itself before the first Read / Grep / Glob outside the
  project ("Read outside the working directories"). Answered from the rail or the phone once
  the dialog is on screen: **allow** = "Yes, but ask again next time" (this read only),
  **allow and don't ask again** = "Yes, and keep allowing any reads outside the working
  directories", **deny** = Esc (the read is interrupted). "No, and block reads … from now on" is
  the dialog's own second option and only reachable in the terminal — it writes
  `permissions.blockReadsOutsideWorkingDirectories` into `~/.claude/settings.json` for every
  project and every mode.
- A Read / Grep / Glob on a network path — a UNC share such as `\\server\share` on Windows, a
  `/net/<host>/…` automount on macOS and Linux — asks in every mode but bypass, even in auto
  mode and with an allow rule (Claude Code 2.1.292+), and the question offers only "Yes" and
  "No": **allow** and **allow and don't ask again** both answer "Yes" for this read, **deny** =
  Esc. A share mounted under `/Volumes` or `/mnt` is a local path and never asks. The Steward
  (headless) cannot read such a path at all — a project under `/net` is out of its reach.
- A blocked background job Claude Code announces (`claude agents`) is not this pane's question;
  remove a stale one with `claude rm <id>`.

## The plan strip

- When the agent keeps a task list (TaskCreate / TaskUpdate) a strip over the terminal reads
  "3/7 · Running tests": done / total and the running step (else the next pending one, or "all
  steps done"). **steps** unfolds it (✓ done, › in progress, · pending), **hide** folds it. The
  list mirrors into the rail, the phone and the deck as well.

## Terminals inside a task tab

- Every terminal offers **new terminal to the right** (⌘D) and **new terminal below** (⇧⌘D) —
  pane header buttons, Task menu, ⌘K; splits nest, dividers drag; ⌥⌘←→↑↓ (Task → Focus Terminal
  ▸ Left / Right / Above / Below) move the focus; ⌘W closes the focused added terminal ("close
  this terminal (ends the shell)"). The new terminal takes the keyboard at once (since 0.20.32;
  with two or more terminals in the tab the focus used to land nowhere). Added shells share the
  task's folder and environment and close with the task. ⇧↩ types a newline in the terminal.
- Terminal font: ⌘K "terminal: larger / smaller font", **⚙ → appearance → Terminal font**.

## Side questions (ask on the side)

- Since 0.20.35 a Claude Code terminal can be asked beside its conversation while the agent
  keeps working. The usual way in (since 0.20.36): select text in the terminal and **Explain
  this** appears under the selection — one click asks "Explain this: “…”" and opens the **side
  question** window over the terminal's bottom right corner with the answer on its way. A plain
  drag is Claude Code's own selection (it highlights and copies the text itself); Robion reads
  the dragged cells from the terminal, so it works the same as an ⌥-drag, which is xterm's
  selection. The chip keeps the text until you click or type into the terminal or select
  something else (an ⌥-drag highlight itself goes as soon as the mouse moves — Claude Code
  reads the mouse, and that counts as input). The question follows the app's language; **⚙ →
  Application → Side question from a selection** replaces it with your own wording (`{text}`
  = the selection), e.g. to ask and be answered in Czech under an English UI.
- An empty window, to type a question of your own: **ask on the side** — the first of the
  terminal's header buttons, Task → **Ask on the Side**, ⌘K "ask on the side"; with a selection
  on screen the question starts prefilled, to edit first. In the window Enter asks (⇧↩ breaks
  the line), Esc or × closes it and the keyboard goes back to the terminal; the bin clears the
  thread. In a tab with several terminals the menu item aims at the focused one, or at the
  task's Claude Code terminal when a shell has the focus; a shell has no such button. No
  keyboard shortcut: 0.20.35 had ⌥⌘A, 0.20.36 dropped it.
- A fork of the session answers: the conversation as it stands plus your question, with no
  tools. Neither the question nor the answer is written into the agent's conversation, its
  transcript or the terminal, and the agent's turn is not interrupted. "answering…" usually
  takes a few seconds.
- The answer comes only from what the session already holds — what was said, read and run so
  far, plus the prompt and the reply being written at that moment. What the agent's step in
  progress has just read or run (a tool result that arrived seconds ago) is known once that
  step ends. It cannot read another file or run a command; when the answer would need that, it
  says so — ask in the conversation itself then.
- Works while the agent runs, waits for a permission, or holds a question for you. Follow-ups
  know the thread: each question goes out with the last five exchanges.
- The thread belongs to the terminal, is shared with the phone's **aside** tab, keeps the last
  20 questions and lives in the server's memory: closing the task or restarting the server
  (an update) drops it.
- No answer, each with **ask again**: "this session takes no side questions (it is not Claude
  Code, or needs a restart)" — Robion's hooks module is not listening in that session; "the
  conversation has not started yet, there is nothing to ask about" — before the agent's first
  reply, and right after `/clear`; "the session did not answer in time" — two minutes passed
  (a session that started before the update to 0.20.35 may need a restart: tab menu →
  **restart session…**); "the answer failed" — the model call failed or came back empty.
- Claude Code's own `/btw <question>` typed into the terminal is a separate thing: its
  questions and answers stay in the terminal and are not part of this thread.

## Closing the tab, detached tasks, ending the task

- × on a Claude Code tab is **close panel (task keeps running)**: the task stays in the side
  panel's **TASKS** section with its dot ("focus the terminal (or reopen it); × ends the task");
  in a workshop project such chips sit in the top bar. × on a shell tab ends the shell.
- **end task** (tab menu, × in TASKS): "Close task "<title>"? This ends its terminal session." A
  worktree task gets the **end task** dialog with the remove-worktree tick ([checkouts.md](https://robion.app/docs/checkouts/)). The
  **Task teardown script** (⚙ → project) runs in the task folder when it closes.
- "session ended" over the terminal with **restart** starts the pane again; "task was closed"
  when the task is gone. "agent ended with an error" shows in a red bar with the detail.

## From another terminal: robion-cli attach

- `"$HOME/Library/Application Support/Robion/bin/robion-cli" attach` (Linux server:
  `robion-server cli attach`; since 0.20.12) lists the open tasks of every project with their
  state; `… attach <task>` (a task id prefix, its title, or `project/title`) puts that
  terminal at the task's session — the same screen as the tab, typing reaches Claude Code,
  **Ctrl-]** detaches and the session keeps running. Works over `ssh` to the Mac (or the
  server), so a dialog the phone cannot answer is one command away. While attached Robion
  treats the terminal as you looking: a held permission prompt appears there, the finished
  turn counts as seen, the phone gets no push for it; when it detaches, the tab gets its own
  size back and the terminal you ran it in is put back to normal (mouse reporting, bracketed
  paste and the alternate screen off — since 0.20.13; before, a Claude Code session left mouse
  reporting on and the shell showed `[<35;12;5M` whenever the mouse moved). `robion-attach` (same folder) is the older debug hatch straight into the pane
  host: pane names instead of tasks, local only, no seen/held handling.
- **`robion-cli tui`** (since 0.20.12): the rail and one terminal in a plain tty, for a server
  or a Mac reached over `ssh`. Left: every project with its open tasks and a state glyph
  (`!` asks for permission, `?` asks a question, `×` error, `✓` done and not seen yet, `●`
  working, `○` waiting for a prompt, `–` session ended) and "n waiting" in the header; right:
  the selected task's session, live, typing goes to it; bottom: what the task does or waits
  for. The TUI's own keys sit behind **Ctrl-]** (like tmux's Ctrl-b): **j / k** or **↓ / ↑**
  pick the next / previous task (the pane switches), **← / →** jump to the previous / next
  project and **1–9** to the n-th project (its most urgent task; since 0.20.14), **w** opens
  the go-to picker (a box over the pane: type to filter by project or title, ↑↓ move, ←→ jump
  by project, ⏎ opens, Esc closes — no prefix inside it), **c** starts a new task in the
  selected task's project (the status line takes the first brief: type, ⏎ creates, Esc
  cancels; the task runs where the project's new-task setting says and opens at once), **x**
  ends the selected
  task (the status line asks "end task “<title>”? y / n", for a worktree task then "remove
  its worktree? y / n" and, with uncommitted changes, "discard them? y / n"; the selection
  moves on) — both since 0.20.15 — **y** allows and **n** denies the selected task's pending
  permission, **?** shows the keys, **q** quits (every session keeps running), **Ctrl-]**
  twice sends a Ctrl-] to the pane. The TUI shows a task's first pane only, not the
  terminals added with ⌘D. It starts on the task that needs you
  most (a permission, then a question). Below 60 columns the sidebar hides. Like `attach`, the
  TUI counts as you looking at the task it shows (held prompts pass through, the turn is seen,
  no push); a task that closes leaves the list, a new one appears.

## Parking and Robion restarts

- One task, in place: tab menu **restart session…** (Claude Code tabs only; also Task →
  **Restart Session…** for the active task, since 0.20.8) — "Restart the
  session of task "<title>"? The agent finishes its turn and Claude Code starts again in this
  tab (--resume)." A park and a restart in one step, e.g. after a Claude Code upgrade (the new
  version starts): the tab stays, reads "· restarting…" and reattaches when the new session
  reports in; added terminals of the task start again as fresh shells. Takes a few seconds: no
  handoff note is written first (that took about half a minute), the transcript stays on disk.
  Greyed as **restart session (the agent is waiting for you)** while the agent waits for a
  permission or an answer — answer first. When the resume fails, Robion writes the handoff note
  from the transcript then and the session starts fresh from it, like a parked task (below).
- Task → **Park Project Agents…** (⌘K "park all project agents"): "Park n tasks? Each finishes
  its turn, writes a handoff and ends its session." — for a reboot or a Claude Code upgrade;
  result "parked n, skipped n (waiting for you)"; a parked task reads "· parked" and comes back
  with **restart**.
- **⚙ → agents**: **Handoff when parking** ("writes .robion/handoff-<slot>.md using a headless
  fork of the session"), **Restore agents after start-up** ("after a Mac restart each task comes
  back via --resume (or from its handoff)"), **Wait for the turn to finish** (seconds an agent
  gets on system shutdown).
- Quitting or updating Robion itself does not end tasks: terminals live in the pane host
  (**⚙ → agents → Terminal backend**) and reconnect after the restart.
- After an update the sessions usually keep running on the pane host the previous version
  started; the status line then reads **pane host awaiting replacement** (hover: "After a
  Robion update the terminals keep running on the old pane host. It is replaced by itself once
  the last session ends; 'replace now…' does it right away."). **replace now…** asks "Replace
  the pane host now? Every running agent finishes its turn, its session ends and starts again
  at once (--resume). It takes about a minute; do not restart Robion meanwhile." and runs the
  replacement: a banner shows "replacing the pane host: parking sessions n/N", "starting the
  new host", "restoring sessions n/N", every terminal reads "the session is moving to the new
  pane host…" until its session is back, **restart session…** is greyed as **restart session
  (the pane host is being replaced)**, and a new task is refused with "the pane host is being
  replaced; wait for the migration to finish". The same replacement runs by itself at the first
  start after an update when the old host is too old to take over (rare); a restart of Robion in
  the middle only starts it over.

## Resuming a closed task

- **home → recently closed** (also the **history** row of the TASKS section): **resume** — "a new
  task continues the same conversation (claude --resume); in the worktree if it still exists";
  the new task is marked "· resumed". **start again** appears when "the session left no
  transcript (it was closed before its first message)" — a new task with the same title and
  brief. **activity** opens the closed task's timeline.
- A session continued from another client (Remote Control, the Claude app) is recognised by
  its transcript and keeps reporting to Robion.

## Activity — the task timeline

- ⇧⌘A (Window → Activity, tab menu **activity…**, ⌘K, the home list): "task timeline: prompts,
  waits, decisions, results, restores". Kinds: task, prompt, permission, question, decision,
  message, done, idle, error, ended, note; each with its source (desktop, phone, agent).
- The header carries the task's usage: "<n> tok. (out <n>)" — new tokens (in + out + cache
  write), "<n> turns · <n> prompts · <n> tools", "ran <time>", "waited <time>".
- Notes land here too, e.g. "Robion was updated, restart this session" (since 0.19): a session
  that outlived an update gets that line appended to every Robion tool result until restarted.

## Statistics and cost

- **STATISTICS** (⇧⌘U, Window → Statistics, the USAGE widget): ranges today / 7 d / 30 d / 90 d /
  all, **all projects** / **this project only**; KPIs (sessions, prompts, turns, tool calls,
  output tokens, agents ran, waited for you, median wait, interrupts, failures, "vs. previous
  period"); charts tokens, agent time, activity, "when you prompt" heatmap; tables projects
  (click selects the project), models, tools, MCP, skills; footer "last import", "n transcripts".
  Needs **⚙ → application → Usage statistics** (reads Claude Code transcripts); **refresh**.
- Per task: the activity header above. Money: only a workshop design is priced, as its share of
  the month against **⚙ → application → Claude subscription** ([workshop.md](https://robion.app/docs/workshop/)).
- Limits: the USAGE widget's 5h / 7d bars; an exhausted window shows the banner "limit
  exhausted: … — agents are stalled" — "Claude Code is waiting for the quota to reset; prompts
  finish on their own, just later".

## Related projects, send to agent, workshop projects

- **⚙ → project → Related projects**: "the agent can get them as --add-dir"; the ⋯ popover's
  **add related projects (--add-dir)** toggle decides per task.
- "send the failure to the agent": a failed run button's terminal (tab menu), a failed run in
  the controls panel, or a LOG line ("send this line to the agent") hands the output to the
  project's agent task; "the agent is waiting for a permission or a choice right now" / "no
  agent task in this project" block it.
- Workshop projects (**⚙ → project → Project type: workshop**): the design panel is the anchor;
  every agent runs without a terminal tab — its chip sits in the top bar ("the task is running
  but its terminal is closed — click reopens it"); no new-task or terminal buttons; the tab has
  no close button and a layout reset keeps it ([workshop.md](https://robion.app/docs/workshop/)).