shelbi workspace
View as markdownshelbi 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 agent is loaded where), grow
or shrink the pool (add / rm), and intervene (stop a pane to release a stuck
issue). A slot no longer selects a runner: runner/model resolution is owned by
the agent that runs there.
A workspace is capacity: a machine, a tmux pane,
and a worktree; the agent inside it is chosen per issue
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):
Every subcommand accepts the global -p / --project <PROJECT> flag, omitted
from the per-subcommand tables.
list
shelbi workspace listPrint 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. |
AGENT | The agent role the in-flight issue loaded (developer, qa, …), or - when idle. |
INTEG | The integration tier of the project's baseline runner: conventional when it emits recognized markers (Claude Code, Codex), degraded when Shelbi can only poll it. |
STATE | The live pane state (see below). |
NAME HOST AGENT INTEG STATE
alpha hub developer conventional in_progress: t-009
bravo hub - conventional idle
charlie hub review conventional review: t-004
delta devbox qa degraded in_progress: t-017
echo devbox - conventional idleThis 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
is live-probed, not board-derived — list runs a real tmux/SSH probe of each
pane. It renders idle, in_progress: <task-id>, review: <task-id>,
occupied (user shell), orphaned session, or unreachable (<reason>). For
the poller's finer-grained read of an in-flight issue (working,
awaiting_input, blocked), use status.
stop
shelbi workspace stop [OPTIONS] <NAME>Stop the workspace's tmux pane. By default the in-flight issue 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 issue 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 issue in in_progress with assigned_to pointing at this workspace. Use when you're about to restart on the same issue 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 listStop a stuck workspace and let the board release its issue:
shelbi workspace stop bravoChange which runner an agent uses (edit the project config, not the pool):
# In project.yaml: agents.<name>.runner, or a house model in runners.<kind>.
# See /docs/configuration/agents.Restart a workspace on the same issue without losing the card:
shelbi workspace stop charlie --keep-task
shelbi issue start docs-write-cli-reference-pagesInspect a single workspace's raw status without spawning a tmux probe:
shelbi workspace status alphaSee also
- Workspaces — the slot model, the
machine-grouped sidebar, and the lifecycle states
statusreports. - Review workspaces — tag-routed review slots and the transition commands that boot and tear down their servers.
- Agents — the role shown in the
AGENTcolumn. shelbi agent— manage the agents a workspace can run.- Orchestrator — how the scheduler picks a free workspace for the next ready issue.