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); ⋯ 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).
• + 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 · ” 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: ” 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): ”: 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).
• Prerequisite: Claude Code 2.1.287 or newer — Robion’s hooks module loads into every session it starts (settings.md, “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, deck.md.
• 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 " dialog with the remove-worktree tick (checkouts.md). 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 “ 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 " 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-.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: ” tok. (out )” — new tokens (in + out + cache write), ” turns · prompts · tools”, “ran ”, “waited ”.
• 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).
• 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).