01
Check Node
Cubicle needs Node 20 or newer, on macOS or Linux. Windows is not supported yet — it works under WSL.
node --version # v20 or higher
CUBICLEINSTALL
Six steps to
an open floor.
Cubicle runs entirely on your machine. One global install, hooks once, then launch your sessions through it — only the processes you start that way are ever shown.
Node 20+ · npmmacOS · Linux · WSL~1 minute
02
Install Cubicle
One global install. Nothing is compiled, and nothing runs until you ask it to.
npm install -g cubicle-cliThe package is cubicle-cli; the command it installs is cubicle.
03
Install the hooks
Detects Claude Code and Codex, and writes Cubicle's hook entries into each one's own config. It backs them up first, merges rather than overwrites, and changes nothing on a second run.
cubicle initThis teaches the runtimes how to report. It does not track anything by itself.
04
Start a tracked session
This is the opt-in. It launches Claude Code or Codex normally with a run id in its environment, starts the local office the first time, and opens it in your browser.
cubicle run claude --name "Fix the review table"
cubicle run codex --name "Audit the queue worker"A plain claude or codex stays invisible. Only what you start this way appears.
05
Watch the floor
Every later run joins the same office. Leave the tab open on a second monitor — characters arrive, work, and walk over when they need you.
cubicle open
# http://localhost:4517If something else holds 4517, Cubicle takes the next free port and cubicle open still finds it.
06
Check it over
Verifies Node, both runtimes, the hooks, the local files, the server, the websocket and the ports — and lists what is being tracked right now.
cubicle doctorcubicle status shows live runs, cubicle stop stops the office (never your agents).
When the header reads BACKEND LIVE and a character walks in after cubicle run claude, you are done.
LOCALHOST:4517HOW TO USE IT
Reading the floor
AT A DESK
Working. The label under the character names the tool and the file, and how long it has been in that state.
COORDINATING
Thinking between tools, or running subagents. An agent with work in flight is never drawn as idle.
NEEDS YOU
Blocked on an approval or a prompt. It walks to your door with a ring around it — answer it in the terminal you launched from.
SHAKING
A tool failed. The failure holds on screen rather than being replaced by the next quiet moment. Click the character to read its events.
YOUR OFFICE
A finished turn brings you a card. One agent at a time; the rest queue outside. Press Received and the next one comes in.
LOUNGE
Nothing to do. The character waits by the portal instead of sleeping at a desk, and comes back as itself on your next prompt.
WHAT YOU CAN CLICK
IF SOMETHING IS OFF
The header says RECONNECTING
The server stopped. Any cubicle run starts it again, and the office reconnects on its own — cubicle status will tell you whether one is up.
No character appears when I start an agent
Almost always because it was started as a plain claude or codex, which Cubicle ignores on purpose. Launch it with cubicle run claude. If that still shows nothing, run cubicle doctor to check the hooks.
The floor is empty after I restart the server
By design. Only runs whose process is genuinely still alive come back; everything else is archived into History, so a restart can never repopulate the floor with old sessions.
A character is standing in the lounge
That run has nothing to do at this moment. It keeps its desk and its identity, and walks back in on your next prompt.
Two sessions in one repository
They are two runs under one project, tracked and shown separately. You can track one and ignore the other.