# shelbi workspace Inspect and control the project's declared workspace pool — list slots with their host, runner, and loaded agent, change slot runners, and stop stuck panes. ```text shelbi workspace [OPTIONS] ``` `shelbi workspace` manages the project's declared workspace pool. A freshly [`init`](/docs/cli/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 `. 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](/docs/concepts/workspaces) is capacity: a machine, a tmux pane, and a worktree; the [agent](/docs/concepts/agents) 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): Every subcommand accepts the global `-p / --project ` flag, omitted from the per-subcommand tables. ## list ```text 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](/docs/concepts/agents) role the in-flight task loaded (`developer`, `qa`, …), or `-` when idle. | | `STATE` | `idle`, or `in_progress: ` when a task is running here. | ```text 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`](#status). ## set-runner ```text shelbi workspace set-runner [WORKSPACE ...] shelbi workspace set-runner --all ``` Change the runner assigned to existing workspace slots. `` must be a declared key under [`agent_runners`](/docs/configuration/project#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: ```bash shelbi workspace set-runner codex --all ``` Or migrate selected slots only: ```bash shelbi workspace set-runner codex alpha bravo ``` | Flag | Type | Default | Description | | --- | --- | --- | --- | | `` | 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 ```text shelbi workspace stop [OPTIONS] ``` 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 | | --- | --- | --- | --- | | `` | 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 ```text shelbi workspace status [NAME] ``` Print observed workspace state from the hub-side poller. Reads `~/.shelbi/workspaces//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. | 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](/docs/configuration/workflow#run-ready-and-teardown); see [review workspaces](/docs/concepts/review-workspaces) for the full model. ## Examples Snapshot the pool to find a free workspace: ```bash shelbi workspace list ``` Stop a stuck workspace and let the board release its task: ```bash shelbi workspace stop bravo ``` Switch all existing worker slots to Codex: ```bash shelbi workspace set-runner codex --all ``` Restart a workspace on the same task without losing the card: ```bash 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: ```bash shelbi workspace status alpha ``` ## See also - [Workspaces](/docs/concepts/workspaces) — the slot model, the machine-grouped sidebar, and the lifecycle states `status` reports. - [Review workspaces](/docs/concepts/review-workspaces) — tag-routed review slots and the transition commands that boot and tear down their servers. - [Agents](/docs/concepts/agents) — the role shown in the `AGENT` column. - [`shelbi agent`](/docs/cli/agent) — manage the agents a workspace can run. - [Orchestrator](/docs/concepts/orchestrator) — how the scheduler picks a free workspace for the next ready task.