shelbi workspace
View as markdownshelbi workspace <SUBCOMMAND> [OPTIONS]shelbi workspace manages the project's declared workspace pool. How a new
project's pool starts depends on how it was created: shelbi project add,
shelbi wizard, and shelbi init -y write an empty pool,
while shelbi init without -y and the app's Add project form write two hub
workspaces, dev and a review slot named review. If a project's pool is
empty, the orchestrator provisions it on
first boot (asking how many workspaces and which naming scheme) and adds 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 Shelbi
session, 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.
add
shelbi workspace add [OPTIONS] <NAME>Add a workspace to the pool, create its worktree, and wire Shelbi's Claude hooks
into the worktree's .claude/settings.local.json. It refuses a name that
already exists or slug-collides with an existing workspace.
If a user-authored settings.local.json can't be self-healed, add prints a
message describing the hooks to merge and exits with status 3 without adding
the slot. Merge the hooks and re-run the same command.
| Flag | Type | Default | Description |
|---|---|---|---|
<NAME> | string | — | Name for the new workspace (positional, required): lowercase letters, digits, -, _. |
--machine <MACHINE> | string | local hub | Machine to place the workspace on, as declared under machines:. |
rm
shelbi workspace rm [OPTIONS] <NAME>Remove a workspace from the pool and tear down its worktree and session. It
refuses a workspace holding an in-progress or review issue (release it first
with shelbi workspace stop <name>), or one whose worktree has uncommitted or
unpushed work, unless you pass --force.
| Flag | Type | Default | Description |
|---|---|---|---|
<NAME> | string | — | Workspace name (positional, required). |
--force | flag | off | Remove even if the workspace holds an in-progress or review issue, or its worktree holds uncommitted or unpushed work. |
--force discards work
--force tears down the worktree even when it holds uncommitted or unpushed
changes. That work is lost.
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 idleThe same table appears in the Workspaces section of
shelbi status --full, the snapshot the orchestrator reads
at session start. It's the view you want when answering "who's free, and what
are they running?" An AGENT of - with idle state is a free slot. STATE
combines the board and a live probe: a slot with an in-progress or review issue
shows in_progress: <task-id> or review: <task-id> from the board; every
other slot's session is probed (over SSH for remotes) to tell idle from
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 session. By default the in-flight issue is moved back to
todo and its assigned_to field is cleared, so the board never shows an
orphaned in_progress card pointing at a dead session. On a review slot, the
issue it was serving is unloaded instead: it stays in the review column,
unassigned, and isn't auto-loaded again. 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 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/projects/<project>/workspaces/<name>/status.yaml files; no live session 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.Bounce a stuck workspace and relaunch it on the same issue, keeping its work:
shelbi workspace stop alpha --keep-task
shelbi issue resume t-009Inspect a single workspace's raw status without a live session 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.