Run your first task

Set this up with an AI agent

Copy a prompt describing this guide and paste it into Claude Code (or your agent of choice).

A task moves through five columns: Backlog → Todo → In Progress → Review → Done. You drive the ends: what lands in the backlog and what gets accepted out of review. The orchestrator drives the middle: the moment a card hits todo, it picks a free workspace and starts it.

Open the TUI

From inside a project, or from anywhere with the project on disk:

shelbi

With one project configured, shelbi launches its TUI directly. With more than one, you get a fuzzy picker: type to filter, Enter to launch. Inside a registered project's work_dir, that project always wins (Shelbi resolves by reverse-lookup against ~/.shelbi/projects/*.yaml).

You can also target a project by name:

shelbi -p myapp

The TUI is two panes. A borderless sidebar on the left lists the project name, the nav (Chat, Tasks), your declared workspaces, and any tasks waiting on review. The right pane is a real tmux pane: the orchestrator agent by default, or one of the built-in views (Chat / Tasks / Machines / Review) when you switch.

Ctrl+P opens a fuzzy command palette as a tmux popup. Use it to switch projects, jump to a workspace pane, or swap the right pane to another view. Enter on a sidebar row activates it: focus a workspace, open a review, switch to the Tasks board.

Add a task

You have two ways in: through the orchestrator (the easy one) or directly via the CLI.

Through the orchestrator

The orchestrator is the conversational front door. Tell it what you want in plain English:

you: fix the login bug on Safari — cookie domain mismatch
     breaks the SSO redirect.
 
Orchestrator: ✓ added to backlog as `fix-login-bug-on-safari`.
              branch: shelbi/fix-login-bug-on-safari

The orchestrator creates a markdown task card in the backlog column. It won't auto-promote. The backlog is your triage queue.

Via the CLI

Same end result, no chat:

shelbi task add "Fix login bug on Safari"

Flags you'll reach for occasionally:

shelbi task add "Fix login bug" \
  --id fix-login \
  --status todo \
  --description "Cookie domain mismatch breaks the SSO redirect." \
  --depends-on auth-refactor \
  --prefers-machine devbox

--id — override the auto-slug.
--status — drop straight into todo (or any other column).
--description — fill in the task body now instead of editing later.
--depends-on — repeat for multiple dependencies. The orchestrator skips a todo card until everything it depends on is in done.
--prefers-machine — soft hint; the orchestrator routes to a free workspace on that machine when one's available.

Via the kanban view

Press Ctrl+P and pick "Tasks", or hit Enter on the Tasks sidebar nav. You land on the 5-column Kanban board. Keys:

Key	Action
`h` / `l`	Step between columns
`j` / `k`	Step between rows in the current column
`Enter` / `Space`	Open the highlighted card
`H` / `L` (shift)	Move the selected card to the previous / next column
`K` / `J` (shift)	Reorder within a column
`r`	Refresh
`Esc` / `q`	Close an open card

Adding a task from the kanban view goes through the orchestrator, so it's faster to just talk to it in chat.

Promote to todo, watch the auto-dispatch

Promotion is the start signal. Move a backlog card into todo, either by hitting L (shift-l) on the card in the kanban view or by asking the orchestrator to:

you: promote fix-login-bug-on-safari.
 
Orchestrator: ✓ moved to todo. dispatched to delta.
                workspace: delta
                branch: shelbi/fix-login-bug-on-safari

The orchestrator reacts to the move on the event log (~/.shelbi/events.log). It scans the workspace pool, picks the first free workspace in YAML declaration order (honoring prefers_machine if set), and runs:

shelbi task start fix-login-bug-on-safari --workspace delta

That moves the card to In Progress, creates the branch shelbi/fix-login-bug-on-safari in the workspace's worktree, and feeds the task prompt into the workspace's agent CLI. The sidebar badge next to delta flips from · (idle) to ⏵ (working).

Jump in any time. Enter on the workspace's sidebar row drops you straight into its pane to watch the run live.

you@hub — myapp

 myapp                        
                              
 💬 Chat                       
 📋 Tasks                      
 ⚡ Activity                   
                              
 — Workspaces —               
 ▾ hub                        
   · alpha               idle 
   · bravo               idle 
   · charlie             idle 
   ⏵ delta          Developer 
                              
 — 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 · myapp   3 total                                                     Workflow: All ▾  Workspace: All ▾ 
                                                                                                               
 BACKLOG (2)           TO DO (0)             IN PROGRESS (1)       REVIEW (0)            DONE (0)              
 Add CSV export                              Fix login bug on                                                  
  app                                        Safari                                                            
                                              app  ⎇ shelbi/fix-lo…                                            
 Tighten rate-limit                                                                                            
 copy                                                                                                          
  app                                                                                                          
                                                                                                               
  h/l col   j/k row   ⏎ open   n new   f filter   r refresh

Badge	Workspace state
`·`	idle — no task assigned
`⏵`	working — agent actively running a turn
`💬`	awaiting input — finished a turn, sitting at the prompt
`⚠`	awaiting permission — showing a permission dialog
`✓`	review-ready — task moved to the review column

Review the workspace's branch

When the workspace finishes, it writes a review-ready marker into its worktree. The hub poller picks it up on the next tick, moves the card into Review, and the workspace's badge flips to ✓. The sidebar's Ready for Review list grows a row:

— Ready for Review —
✓ fix-login   delta

Click that row (or Enter on it) to focus the workspace's window, where the finished branch is checked out for you to interrogate the diff. Ask the agent to walk you through the change, run tests, or explain a tricky hunk. Nothing about the workspace's run is locked in yet; you can ask for edits and have them committed onto the same branch.

To go a step further and run the change — boot its dev server and click through the app — tag a slot for review and let the review status route the branch onto it. See set up review workspaces.

Accept the task

Two flavors of accept.

Merge into the default branch. From the review pane or the chat, just ask:

you: merge it.

Under the hood that's shelbi merge fix-login-bug-on-safari. The CLI squash-merges the branch into default_branch and prints the resulting commit hash. Add --pr to open a PR via the GitHub CLI instead of merging directly.

Move the card to Done. The orchestrator never auto-completes review. You confirm the merge landed and move the card yourself, with L in the kanban view from Review, or:

shelbi task move fix-login-bug-on-safari --to done

The workspace is already free at that point (the review handoff flipped its badge back) and the orchestrator dispatches it to the next ready todo card on its own.

You own the Review → Done move

The orchestrator squash-merges on request but never marks a task Done for you. Confirming the merge landed and moving the card out of Review is the human checkpoint, until you hand that step off to Zen Mode.

What just happened

You added a task, promoted it, watched a workspace pick it up, reviewed the result, and merged it. The same loop (backlog → todo → in progress → review → done) is the whole product surface. Everything else is volume: more tasks at once, more workspaces, more machines.

The rest of getting-started walks the same loop at increasing levels of autonomy:

Run a multi-workspace dispatch loop: fill the backlog with a stack of work and watch every workspace in your pool run in parallel without you touching the dispatcher.
Enable Zen Mode — flip the orchestrator from scheduler to lead. It auto-promotes eligible backlog cards and auto-merges finished branches that clear a project-defined confidence bar.
Author a custom Shelbi workflow: fork the orchestrator's prompt and encode routing rules, Zen judgment categories, and reporting style for this project specifically.

For deeper reference any time:

The Concepts docs for the full mental model of workspaces, columns, the events log, and the orchestrator.
The CLI reference for every flag on every shelbi subcommand.