Skip to guide
Hormesis LabsDownload

How to use Hormesis Workspace (open alpha)

On this page

Workspace runs your own Claude Code and Codex agents in terminal panes and draws them on a map. You brief an agent in its pane, as you would in a terminal. The map shows who is working, who is idle and who is waiting for you.

The map

  • Projects. A project is a folder. Each project is a box on the map with its agents inside, sorted into a Leads row and groups.
  • Agent cards. Each card is one agent. Its mark shows its state: working, idle, needs you (a hand), waiting on another agent (an hourglass), or asleep.
  • The hand badge. A hand marks an item that may need your answer. Check Needs you for what you can do about it. In rare alpha cases a hand badge can have no matching row; open the pane to check.
  • Lines. A line between two cards shows who handed work to whom, across projects too.
  • Open a card to show its terminal beside the map and type to the agent. The pane shows its available terminal history.
  • Moving around. Scroll or pinch to zoom. Use the Hand tool, or hold Space while dragging, to pan. With the selection tool, drag cards or boxes to move them; dragging empty space selects an area. The minimap shows your position.

Start an agent

  • Use Start an agent on an empty project card, or right-click the project in the sidebar → New agent here.
  • In another folder of the project: right-click → New agent in subfolder….
  • Add a project: right-click PROJECTS in the sidebar → pick a folder, or scan a folder for projects.

The agent opens in its own pane, running your Claude Code or Codex. If the CLI is not signed in, it shows its own sign-in screen first.

Brief it

Type the task in the agent's pane and press Enter, as in a terminal. Be specific about the goal and what "done" means.

A pane is a terminal: ⌘F searches its history, ⌘C and ⌘V copy and paste, right-click opens a menu.

Workspace also manages messages that agents send each other, and can append its role guide to the first brief it delivers to an agent that another agent started.

Leads and workers

  • A lead is an agent you give a goal to. It can start other agents (workers) in the same project, brief them and collect their results. The lines on the map show the hand-offs.
  • When a project has no lead, its header says "no lead", and an eligible agent's right-click menu offers Make lead of that project.
  • Questions from workers are normally routed to their lead first. Questions without a suitable lead, escalations and prompts that need a person can reach you directly.
  • A second model can check the work: a Claude agent with a Codex reviewer beside it, or the other way round.

Needs you

Needs you sits above the Work list and collects requests for your attention: questions, permission prompts, decision cards, and some held-message or escalation items.

  • A question. The agent asked something. Open its pane and answer there.
  • A permission prompt. The CLI wants approval for an action. Approve or refuse it in the pane. Sign-in and folder-trust screens show here too.
  • A decision card. An agent puts a choice to you as a card, sometimes with a picture: approve, reject, or pick an option, with an optional note.

Eligible notifications can produce a macOS banner when Workspace is not in front, subject to your notification settings.

Layout: Arrange and Fit

Open Layout in the map's toolbar:

  • Arrange the map, or the current selection. With a selection, Arrange whole map is offered too.
  • Re-arrange all also re-flows cards you placed by hand. Pinned and locked items stay.
  • Undo (⌘Z, when the map has focus) puts the previous layout back.
  • Reset layout returns to the default.
  • With one box selected: Fit container to content or Fit content to container.

The Fit button in the tool palette fits the whole map on screen (⇧1).

Sleep and wake

Each live agent is a real process and uses memory. Workspace keeps a live agent budget and puts eligible idle agents to sleep: ones that can be resumed, are not on screen and have no recorded open work. Busy or blocked agents are left alone.

  • Sleeping stops the process; the conversation can be resumed.
  • A sleeping agent keeps its place. Open it, pick it in ⌘K or message it, and it wakes when there is room in the budget.
  • Quit and reopen Workspace: your map, conversations that can be resumed and recent terminal history come back.

Reports

Agents can publish short reports (a result, a number, a status). The newest headlines sit in the status bar; the Reports view lists them. Reports are stored on your Mac.

Monitors

A monitor is a script in your project that Workspace runs on a schedule, with no agent involved, and posts the result as a report card. Monitors live in the project's .hormesis/monitors/ folder and run only after you approve them.

Accounts

Settings → Accounts: add more than one of your own Claude accounts, choose which one new agents use, and turn on Enable usage to see the plan usage Claude Code reports. You can ask to move an agent to another account after its turn ends. Workspace copies the conversation that can be resumed; the new account may need to process the context again, which can use more quota. Each account is signed in with Claude Code's own /login.

Host health

The status bar has a Host icon (your Mac's load, swap use and free disk) and a Workspace health pill. Open the pill for a plain list: an overloaded Mac, agents that look stuck, agents waiting for you, and agents cut off by a restart.

The status bar counts working and monitoring separately. You may see "0 working" while some agents are monitoring.

Settings worth knowing

Open with ⌘,.

  • Appearance: theme, terminal font and size.
  • Workspace → Wire style: Rounded, Straight or Curved.
  • Workspace → Live agent budget and the sleep timers.
  • Workspace → Auto-continue interrupted agents: after a restart, agents whose turn was cut off are asked to carry on. On by default; you can switch it off.
  • Notifications: mute, or set the minimum level.
  • Claude & Codex: what Workspace added to your CLI settings, Remove, and the approval policy for new agents.

Keyboard basics

KeysDoes
⌘KQuick switch: projects and tabs
⌘,Settings
⌘?The full shortcut list
⌘1 to ⌘9Switch to tab N in the project
⌘TNew shell tab
⌘D / ⌘⇧DSplit the pane right / down (shell)
⌘⌥D / ⌘⌥⇧DSplit the pane right / down (Claude)
⌘WClose the pane
⌘FSearch the pane's history
⌘⇧RBrowse Claude sessions
⌘ZUndo a layout change, when the map has focus
EscOn the map: close a menu or clear the selection. In a pane, Esc goes to the CLI.