shelbi workspace

View as markdown

shelbi workspace <SUBCOMMAND> [OPTIONS]

shelbi workspace manages the project's declared workspace pool. A freshly init'd project starts with an empty pool; the orchestrator provisions it on first boot (asking how many workspaces and which naming scheme), adding each slot with shelbi workspace add <name>. Beyond that you use these commands to observe (what's idle or working, which runner and agent are loaded where), grow or shrink the pool (add / rm), change existing slot runners, and intervene (stop a pane to release a stuck task).

A workspace is capacity: a machine, a tmux pane, and a worktree; the agent inside it is chosen per task by the workflow, which is why list reports both. The sidebar shows the same pool, grouped by machine, with a badge marking each state (⏵ working, · idle):

jlong@hub — my-project

 shelbi                       
                              
 💬 Chat                       
 📋 Tasks                      
 ⚡ Activity                   
                              
 — Workspaces —               
 ▾ hub                        
   ⏵ alpha          Developer 
   · bravo               idle 
   · charlie             idle 
 ▾ devbox                     
   ⏵ delta                 Qa 
   · echo                idle 
   · foxtrot             idle 
                              
 — Ready for Review —         
 ✓ Cold-start cache  hub:3000 
   shelbi/cold-start-cache    
 ✓ CSV import fix devbox:3000 
   shelbi/csv-import-fix      
 ✓ Nightly report devbox:3001 
   shelbi/nightly-report      
                              
 — Queued for Review —        
 · Validate webhook payloads  
   shelbi/validate-webhook-pa…
 · Harden token refresh       
   shelbi/harden-token-refresh
 ^P palette  q quit           
                              
 ZEN MODE ON

 Tasks · shelbi   5 total                                                    Workflow: All ▾  Workspace: All ▾ 
                                                                                                               
 BACKLOG (1)           TO DO (1)             IN PROGRESS (2)       REVIEW (0)            DONE (1)              
 Draft Q3 roadmap      Add ratelimit to API  Deploy staging env                          Ship dark-mode        
  app                   app                   app  ⎇ shelbi/deploy…                      toggle                
                                                                                          app                  
                                             Backfill order index                                              
                                              app  ⎇ shelbi/backfi…                                            
                                                                                                               
  h/l col   j/k row   ⏎ open   n new   f filter   r refresh

Every subcommand accepts the global -p / --project <PROJECT> flag, omitted from the per-subcommand tables.

list

shelbi workspace list

Print every declared workspace as a row. The columns:

Column	What it shows
`NAME`	The workspace's stable name (`alpha`, `bravo`, …).
`HOST`	The machine it's pinned to — `hub` or a declared remote.
`RUNNER`	The workspace runner name from `workspaces[].runner` (`claude`, `codex`, `opus`, …).
`AGENT`	The agent role the in-flight task loaded (`developer`, `qa`, …), or `-` when idle.
`STATE`	`idle`, or `in_progress: <task-id>` when a task is running here.

NAME         HOST     RUNNER         AGENT          STATE
alpha        hub      opus           developer      in_progress: t-009
bravo        hub      opus           -              idle
charlie      hub      opus           -              idle
delta        devbox   sonnet         qa             in_progress: t-017
echo         devbox   sonnet         -              idle

This is the first command the orchestrator runs at session start to snapshot the pool, and the same snapshot you want when answering "who's free, and what are they running?" An AGENT of - with idle state is a free slot. STATE here is board-derived. For the poller's live read (working, awaiting_input, blocked), use status.

set-runner

shelbi workspace set-runner <RUNNER> [WORKSPACE ...]
shelbi workspace set-runner <RUNNER> --all

Change the runner assigned to existing workspace slots. <RUNNER> must be a declared key under agent_runners. This edits workspaces[].runner; it does not change orchestrator.runner.

Use this after setup when you want existing worker slots to launch Codex instead of Claude:

shelbi workspace set-runner codex --all

Or migrate selected slots only:

shelbi workspace set-runner codex alpha bravo

Flag	Type	Default	Description
`<RUNNER>`	string	—	Runner name declared in `agent_runners`.
`[WORKSPACE ...]`	string list	—	Workspace names to update.
`--all`	flag	off	Update every declared workspace. Cannot be combined with workspace names.

stop

shelbi workspace stop [OPTIONS] <NAME>

Stop the workspace's tmux pane. By default the in-flight task is released back to its ready status (todo in the default workflow) and its assigned_to field is cleared. The board never shows an orphaned in_progress card pointing at a dead pane. Pass --keep-task when you're about to restart on the same task and don't want the card to move.

For a remote workspace, stop also kills the remote tmux session so no detached agent process lingers on the other machine.

Flag	Type	Default	Description
`<NAME>`	string	—	Workspace name (positional, required).
`--keep-task`	flag	off	Leave the in-flight task in `in_progress` with `assigned_to` pointing at this workspace. Use when you're about to restart on the same task and don't want the card to move.

status

shelbi workspace status [NAME]

Print observed workspace state from the hub-side poller. Reads ~/.shelbi/workspaces/<name>/status.yaml files; no tmux probing. Cheaper than list and safe to call repeatedly. With a NAME, prints a single row plus the raw status.yaml contents.

Flag	Type	Default	Description
`[NAME]`	string	—	Workspace to inspect (positional, optional). Omit to show every declared workspace.

Serving a review branch is a transition, not a subcommand

Booting a dev server for review is not a workspace subcommand. A review status boots and tears down its server through transition run/ready commands; see review workspaces for the full model.

Examples

Snapshot the pool to find a free workspace:

shelbi workspace list

Stop a stuck workspace and let the board release its task:

shelbi workspace stop bravo

Switch all existing worker slots to Codex:

shelbi workspace set-runner codex --all

Restart a workspace on the same task without losing the card:

shelbi workspace stop charlie --keep-task
shelbi task start docs-write-cli-reference-pages

Inspect a single workspace's raw status without spawning a tmux probe:

shelbi workspace status alpha

list

set-runner

stop

status

Examples

See also