ROBIONDocs

Workspace

The desktop window from the user’s side: the project rail, the home screen and the overview, the panel workspace with its tabs, the side panel (tree and git), ⌘K, the status line, menus.

Window layout

  • Left: the project rail — the rows OVERVIEW, BOARD, INBOX, AUTOMATIONS, then the projects (a paired remote server gets its own group), the USAGE widget at the bottom.
  • Top bar of a project: name, root path, a git tag, + new task with the main checkout / own worktree segment and ⋯ (tasks.md), + terminal; on the right preview :port when the task has ports, the design panel button in a Maker Pack task, and ⚙ (settings, ⌘,).
  • Middle: the panel workspace — terminals, files and the home anchor as tabs in groups; the side panel TASKS / TREE / GIT left or right of it; the status line at the bottom. Banners above the workspace: hooks not installed or outdated, a Maker Pack update, an exhausted Claude limit (“limit exhausted: … — agents are stalled”, “reset in ”).

Closing the window vs. quitting

  • The window’s red close button hides the window; Robion stays in the Dock and the server keeps running (since 0.20.16): automations, the Steward’s schedule, pushes, the phone and the deck all work with the window closed. Agents and terminals run on regardless. Click the Dock icon to bring the window back; a notification click or a deck button does the same.
  • Robion → Quit (⌘Q) ends Robion: the server exits, agents and terminals keep running in the pane host and reconnect at the next start (tasks.md, “park”). Until 0.20.15 closing the window did this too.
  • Robion → Open at Login (checkbox in the app menu, installed app only) starts Robion at login, so a background Robion survives a reboot.
  • A sleeping Mac runs nothing: a closed lid stops the server, the agents and every cron rule alike, and a cron minute that passed in sleep is not caught up. ⚙ → Remote access → Keep Mac awake prevents idle sleep only (a closed lid still sleeps unless power and an external monitor are connected). Work that must run while the laptop sleeps belongs on a remote server (settings.md, “Servers”).

Project rail

  • A row: the project’s icon (or a dot) in its colour, the label, a second line “1 terminal · 2 agents” plus “n checkouts” when there is more than one, and a strip of small cells on the right, one per open terminal, coloured by state. The selected project sits in a rounded frame in its colour (so does the selected OVERVIEW, BOARD, INBOX or AUTOMATIONS row, in a neutral one). A row whose project has an agent at work pulses as a whole, in step with its breathing blue cells (since 0.20.27; off under “reduce motion”).
  • INACTIVE · n (since 0.20.27): a fold-away group at the bottom of the list (per server) for projects nobody touched for Inactive projects days (⚙ → Application, default 14; 0 = never fold) — no prompt typed, no task started by hand or from a controls button, no agent working, waiting or sitting on an unread result. Click the header to show or hide them — each server’s group on its own (since 0.20.31; one click used to unfold every server’s group), remembered on this Mac; the group opens by itself while the selected project is inside it. The tooltip states the rule. A task started by an automation or another agent does not count as a touch.
  • “drag to reorder; right button: colour, icon, order”. Drag rows (or ⌥↑ / ⌥↓); order is per server.
  • Right button: the colour picker on top (red, rose, pink, plum, purple, indigo, blue, teal, mint, green, brown, grey, no colour) and move up, move down, icon…, project settings…, notes for the agent (CLAUDE.md)…, clone to “server”… (paired servers; the project needs an origin remote), and at the bottom remove from Robion… and delete project with files… (since 0.20.4; the latter for projects of the local server only) — the same actions as Remove project / Delete project in ⚙ → Project (settings.md), with the same confirms; both are greyed out while the project has an open task, and a refusal the server still makes appears in a dialog. The colour tints the icon or dot, the stripe on tabs and the selection frame; the same fields are in ⚙ → project (Colour, Icon).
  • icon… opens a grid of 72 monochrome icons (code, terminal, chip, rocket, hammer, book, house, heart, …) and no icon; the icon sits where the dot was — rail, ⌘K, overview tiles, hover card, phone. An emoji set earlier stays as text until an icon is picked (since 0.20).
  • Hover card: resting on a row with tasks lists up to six of them by state with the last prompt and reply, “+n more”; a held permission has allow / deny; “click opens the task; nothing is marked as seen”.
  • Dropping a file or folder from the tree or the Finder on a row copies it into that project; hovering long enough springs the project open. Folders cannot move between servers.
  • Bottom buttons: ⊕ new project, + add project (folder picker), ↓ import projects. Empty rail: “no project yet — create one below, add a folder or import”. Remote rows can read “connecting…”, “disconnected — retrying”, “update this server (protocol mismatch)”, “not paired”.

New, add and import a project

  • NEW PROJECT (⊕, File → New Project…): “What kind of project?” — Development (“software: terminal, files, git”) or Workshop (“I want to make a thing: the design panel leads, the agent works in the background”); then a folder name; it “creates the folder in and runs git init”. is ⚙ → application → Folder for new projects; unset, the dialog asks “Where should new projects live?” with choose folder…. A remote server has its own folder in ⚙ → Servers.
  • Add project (File → Add Project…) picks an existing folder on this Mac.
  • IMPORT PROJECTS (File → Import Projects…): “Folders where Claude Code has already run on this Mac, found in its transcripts” — source (menu bar / claude), last activity, select all, clear selection, add selected (n), a server: picker, a manual absolute path (add path). Empty: “nothing new to import”.
  • ⚙ → project → Remove project: “Files stay, it only disappears from the rail.”

Home screen and overview

  • home sits in the workspace whenever no terminal or file is open (“create a task or open a file from the tree”). It lists recently closed tasks — “closed ”, activity, and resume (“a new task continues the same conversation (claude —resume); in the worktree if it still exists”) or start again when the session left no transcript — and six vertical cards (“six workshops · one process”: 3D print, electronics, wood, metal, CNC & laser, software) with example prompts: “click an example — a task starts working on it right away”; physical ones need the Maker Pack (⚙ → agents).
  • OVERVIEW (⌘0, first rail row, Window → Overview): every open task of every project as tiles grouped: asking for permission, waiting for an answer, error, done — unreviewed, working, waiting for a prompt, session ended, terminals. The header counts tasks and “n waiting”; a tile click opens the task terminal; a held permission has allow / deny on the tile. The rail row shows the waiting count in amber, else the total.

Panels and tabs

  • Every terminal, file, diff, preview and tool panel is a tab; tabs sit in groups, drag a tab to another group or to an edge to split. A tab carries a stripe in the project colour.
  • A group whose visible tab is a tool panel (CONTROLS, LOG, MCP, JIRA, STATISTICS, activity, DRC) keeps its width while the groups around it change: a neighbour closes, a tab is dragged out into a new group, a file opens in a new group. The space comes from and goes to the terminals and files next to it. Its height is kept only when a row closes, so a tab dropped at the top or bottom edge still splits the grid in half. With a file or terminal in front the group flexes like any other.
  • Maximize: ⇧⌘↩, double-click the tab, View → Maximize Panel, or the tab menu (maximize panel / restore layout); a badge reads “maximized · click restores the layout”.
  • Scrollbars show their thumb only while the pointer is over the panel that scrolls (since 0.20.6); the gutter stays, so nothing shifts when it appears.
  • ⌥⌘L View → Reset Layout returns to the default (the layout is saved per project). A crashed workspace offers try again, start from the default layout, reload the window.
  • ⌘W closes the active panel (an added terminal in focus goes first); home has no ×.
  • Tab right button: rename…, maximize / restore, activity…, close panel, close all tabs, end task (tasks.md).
  • ⌘E recent panels (Window → Recent Panels): open panels most-recently-used first; ⌘E then ↩ bounces between the last two, a repeated ⌘E (or ↓) walks further, Esc closes.
  • ⌘1–9 switch to the n-th task (Window → Task n; works on the Czech keyboard).
  • ⌘I toggles the INBOX screen (Window → Inbox; since 0.20.4); Window → Board and Automations toggle the other two screens (no chord; since 0.20.8); ⌘K has inbox, automations and board as actions.
  • ⚙ → application → Max. open files: “the next file closes the one open the longest; 0 = no limit; unsaved files are never closed”.

Side panel: tasks, tree and git

  • Three sections, each folds to its caption: TASKS (tasks by checkout, checkouts.md), TREE, GIT. ⌘B (View → Toggle Side Panel, ⌘K, the button in the TREE caption) folds the whole panel to an icon strip; the icons bring it back. Shown or folded is remembered per project (a workshop project starts folded), width and split per device; the sashes drag. A hairline on the edge towards the grid separates the panel from the terminals and files.
  • ⚙ → appearance → Side panel: left / right; Side panel reveal: pinned (always shown, ⌘B folds it) or on hover (folded; slides out when the pointer reaches the strip, hides once it leaves). A file opened from the tree lands in a group right next to the panel.
  • The tree’s search box: find file… (⌘F, by name) and search in files… (⇧⌘F, text; both also Edit → Find ▸, where the chords live so they work while a terminal has the keyboard; until 0.20.8 the Window menu had Tree ⇧⌘E and Git ⇧⌘G — gone, ⌘B is enough); gitignored files are skipped; long results end ”… and n more”.
  • Tree right button: new file…, new folder…, rename…, move to trash, reveal in Finder, copy path, copy relative path, open in editor, save to disk… (remote). On a folder row the new file/folder goes inside it, on the background into the project root; an empty folder shows in the tree too. The same two as icons in the tree’s search row, next to name / text: new file and new folder put it next to the selected file, or into the root when nothing is selected; the name dialog says which folder (“new file name in src/”).
  • Drag a tree row onto a folder (or onto a file — its folder) to move it there; onto the tree background to move it to the root. Nothing is overwritten (a name already there refuses the move); a folder cannot go into itself. Not while the search box shows results. A row dragged onto a terminal types its path, onto another project’s tree copies it.
  • GIT: since the last agent turn (a baseline is taken on every agent turn; capture baseline by hand), uncommitted changes, earlier on this branch, recent commits, worktrees; stage / unstage. When an agent asks for a review the section opens and lights up for a moment (diffs open as tabs only for up to three files or when the agent asks). The GIT caption is the checkout switcher (checkouts.md); the TREE caption repeats the checkout name dimmed. Both follow the active task.
  • ⌥⌘F Search Terminals… (Edit → Find, ⌘K): “the last ~2000 lines of every project terminal (from 2 characters)”; a hit opens that terminal; “first matches shown — narrow the query”.

Command palette ⌘K

  • Window → Commands…; “command, task, project or file…”. Groups: actions, tasks (every project, with state dots), checkouts (of the selected project — “show in the side panel”), projects, files (“searched in the active task (from 2 characters)”). Keyboard only.
  • Actions: waiting agent, overview, new task / terminal, show git / tree / side panel, open activity / statistics / Jira / MCP servers / controls / web preview, recent panels, settings, reset layout, maximize / restore, park all project agents, toggle dark / light, terminal font larger / smaller, search terminals, new terminal right / below, shortcuts, what’s new.

⌘J — jump to the waiting agent

  • Window → Waiting Agent: the most urgent pane — permissions before questions before errors before unread results, older first; if that is already the current task the next one follows, so repeated presses cycle. Shells never count.

Status line and rail widgets

  • Status line: the selected project, “n projects”, “n sessions” (agents), “n waiting for you” in amber, “n done” (finished turns nobody looked at), server notices ⚠, the hooks state, “server connected” / “connecting to server…” / “server starting…” / “server failed”, “claude missing”, the last error (click dismisses), the limits glance “5h 63 % · 7d 24 %” (hover: reset), the update chip, the server version.
  • USAGE widget: a dot for Claude’s status page (“Claude: all systems operational” or the incident), bars for the 5h session, the week and ” 7d” windows with the percentage and “in ” until reset (90 % and above red), ” today · 7 days” (click opens STATISTICS, ⇧⌘U), the account e-mail; notes “limits: sign in in Claude Code (/login)” / stale / “endpoint rejected the request” / off, retry. Needs ⚙ → application → Usage statistics and Track subscription limits.
  • The Dock badge counts every agent that needs you (permission, question, error, unread finished turn); it clears once the pane is viewed.

Updates

  • Robion checks GitHub releases every 6 hours and after wake, downloads the new version and shows it in the status line: “Robion x.y.z · downloading n %”, then “Robion x.y.z is ready · restart”. Restarting installs it; agents and terminals keep running and reconnect. ✕ hides the chip until the next start; the app menu keeps Restart and Install x.y.z above Check for Updates… (a check while a version waits fetches a newer one if there is one, else offers the restart); Later installs on quit. Failures: “Cannot reach GitHub…”, “The newest release is not published yet…”, Try Again.
  • After the restart the status line may read pane host awaiting replacement with replace now…: the terminals still run on the previous version’s pane host, which replaces itself once the last session ends — or now, on a click (tasks.md, “Parking and Robion restarts”). A remote server’s chip carries the server’s name in front.

The menu bar

  • Robion (the app menu): Settings… ⌘,, Open at Login (installed app only, see “Closing the window vs. quitting”), the macOS items, Quit ⌘Q.
  • File is about projects: New Project…, Add Project…, Import Projects…, Show Project in Finder (the selected project’s folder; does nothing for a project on a remote server). Edit: the standard Undo / Redo / Cut / Copy / Paste / Select All, plus Find ▸ Find File… ⌘F (with the caret in a file editor it finds in that file instead, since 0.20.10), Search in Files… ⇧⌘F, Search Terminals… ⌥⌘F.
  • Task (since 0.20.8; these used to sit under File and View): New Task ⌘T, New Terminal ⇧⌘T, Restart Session… (the active task, as the tab menu’s restart session…; it asks first and does nothing for a shell task, a task already restarting or an agent waiting for you), New Terminal to the Right ⌘D, New Terminal Below ⇧⌘D, Focus Terminal ▸ Left / Right / Above / Below (⌥⌘←→↑↓), Close Panel ⌘W, Park Project Agents….
  • View: Reset Layout ⌥⌘L, Maximize Panel ⇧⌘↩, Toggle Side Panel ⌘B; Appearance ▸ the theme (Dark, Midnight, Graphite, OLED Black, Catppuccin Mocha, Catppuccin Macchiato, Light, System — the same choice as ⚙ → appearance, the current one checked); Reload Window (a renderer restart for a wedged window: the server, agents and terminals keep running and reconnect); Zoom In / Zoom Out (⌘+ / ⌘−), Actual Size (⇧⌘0): scales the whole window including terminals; the same value is ⚙ → appearance → Interface size; Terminal font (px) is multiplied by it. Full screen: ⌃⌘F. Force Reload and the developer tools left this menu in 0.20.8.
  • Window: panels and screens (panels.md), Waiting Agent ⌘J, Commands… ⌘K, Recent Panels ⌘E, Task 1–9 ⌘1–9, then the macOS window items.
  • Help: Keyboard Shortcuts (⌘/) lists every chord: application, tasks, panels, view; What’s New shows the release notes (they open once by themselves after an update); robion.app; Report a Problem… (the issue tracker on GitHub, github.com/biokys/robion-releases); Open Logs Folder (Application Support/Robion/logs: desktop.log, server.log — troubleshooting.md); Developer Tools. Until 0.20.8 the menu linked “Robion on GitHub”, a private repository that showed visitors a 404.

Language, theme and appearance

  • ⚙ → appearance applies immediately, no saving; language and theme are shared with the server and the phone, sizes apply only to this computer.
  • Language: English / Čeština — “app, menu and server texts (activity, notifications); changing it reloads the window” (a confirm warns about unsaved editors).
  • Theme: dark, Midnight, Graphite, OLED black, Catppuccin Mocha, Catppuccin Macchiato, light, system (“system” follows the macOS appearance); also View → Appearance ▸ (since 0.20.8); ⌘K has “toggle dark / light”.
  • Cursors: Terminal cursor, Editor cursor, Blinking cursor, Smooth caret.

The desktop in a browser

  • The whole window — rail, terminals, tree and git, every panel — also runs as a web page the server serves at /d/ (since 0.20.36). Agents, terminals and files stay on the server; the browser tab is a view, like the Electron window. It works on the Mac that runs Robion (any browser) and on another device over the tailnet once ⚙ → Remote access is on; a Linux server serves it too (robion-server pair --desktop, see the server guide). Chrome first: Safari and Firefox render it, but notifications and the app badge need an installed web app there.
  • Opening it: ⚙ → Remote access → desktop in a browser → open in a browser on this Mac (your default browser opens, paired at once) or, with remote access on, link for another device (a one-time link valid 10 minutes — copy it and open it there; new QR code mints another). The link sets the pairing cookie and lands on /d/; the device appears under ⚙ → Servers as “browser (Mac) · date” and can be revoked there. The page can be installed as an app (browser menu → Install); the tab title carries the count of waiting agents.
  • Shortcuts in a browser: the desktop’s chords work wherever the browser lets a page have them; the ones a browser keeps for itself have a Ctrl form — ⌃⇧T new task, ⌃⇧N new terminal, ⌃⇧W close panel, ⌃, settings, ⌃0 overview, ⌃1–9 switch task (the ⌘ forms stay listed and work in an installed web app that passes them on). ⌘/ shows the overview with the right forms; the terminal never sees a chord.
  • What stays with the desktop app: Show in Finder and the trash (the browser deletes through the server, like on a remote server), dragging Finder files as paths (they move as bytes), the SpaceMouse, the app’s own update (the page is always the server’s version), interface size (use the browser’s zoom), pairing other servers (⚙ → Servers says “other servers are paired in the desktop app on the Mac; a browser tab shows one server”), the agent’s preview_screenshot / dom_query / element picker (the agent gets “preview tools need the desktop app” unless the desktop app also shows the project), and the preview tunnel for a dev server on another machine (the panel shows the ssh -L command instead; a browser on the server’s own machine frames the preview as usual). + add project asks for the folder path in a prompt (“Folder path on the server…”, no folder dialog in a browser); new project and import projects work as usual.
  • generate a new token (⚙ → Remote access) signs the browser out like the phone; open a new link. A browser that never paired, or whose cookie is gone, shows the window with “disconnected” in the status line — pair it again.