---
title: "Workspace — Robion user manual"
description: "The window: project rail, home and overview, tabs and panel groups, the side panel with tree and git, ⌘K, shortcuts, appearance, projects, the desktop in a browser."
url: "https://robion.app/docs/workspace/"
lang: en
---

# 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](https://robion.app/docs/tasks/)), **+ 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 <when>").

## 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](https://robion.app/docs/tasks/), "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](https://robion.app/docs/settings/), "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](https://robion.app/docs/settings/)), 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 <dir> and runs
  git init". <dir> 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 <ago>", **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](https://robion.app/docs/tasks/)).
- ⌘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](https://robion.app/docs/checkouts/)), **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](https://robion.app/docs/checkouts/)); 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 "<model> 7d" windows with the
  percentage and "in <when>" until reset (90 % and above red), "<tokens> today · <tokens>
  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](https://robion.app/docs/tasks/), "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](https://robion.app/docs/panels/)), **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](https://robion.app/docs/troubleshooting/)); **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.