Run your first task

Instructions for

Set this up with an AI agent

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

An issue moves through five columns: Backlog → Todo → In Progress → Review → Done, with a sixth, Canceled, for work you drop. 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 Shelbi

From inside the project's repository:

shelbi

Inside a registered project's work_dir, shelbi opens that project's TUI (Shelbi resolves by reverse-lookup against ~/.shelbi/projects/*.yaml). Anywhere else, with no hub daemon running, it opens the launch screen: pick your project under Projects on this Mac (↑↓ to move, ⏎ to open).

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 (Orchestrator, Issues, Changelog), your declared workspaces, and any issues waiting on review. The right pane opens on the Issues board; Orchestrator switches it to the orchestrator's live session.

Ctrl+P opens a fuzzy command palette. Use it to switch projects, jump to a workspace, or swap the right pane to another view, including Activity and Machines, which live only in the palette. Enter on a sidebar row activates it: focus a workspace, open a review, switch to the Issues board.

Open Shelbi.app. With no hub daemon running, it opens the Welcome to Shelbi window: pick your project under Projects on this Mac (↑↓ to move, Return to open), or use Add project if you haven't set one up yet. To change projects later, click the project name at the top of the sidebar (the project switcher) or use File ▸ Switch Project….

The window is two columns. The sidebar on the left lists the project switcher, the nav (Orchestrator ⌘O, Issues ⌘I, Changelog ⌘L), your workspaces, and any issues waiting on review. The main area shows the selected view; Orchestrator is the orchestrator's live session.

⌘K (or ⌃P, or the magnifier at the top of the sidebar) opens the command palette. Use it to switch projects, jump to a workspace, or open another view, including Activity and Machines, which also live under the Go menu. Click a sidebar row to open it: a workspace, a review, the Issues board. Busy workspaces and reviews are numbered, so ⌘1 to ⌘9 jump straight to them.

Add an issue

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: you/fix-login-bug-on-safari

Branches are named <your GitHub login>/<issue id>, so you stands for your GitHub login throughout this page.

The orchestrator creates an issue 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 issue add "Fix login bug on Safari"

Flags you'll reach for occasionally:

shelbi issue 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 issue body now instead of editing later.
--depends-on: record a dependency (repeat for several). The card shows 🔒 until each dependency is in done, its PR targets the parent's branch while the parent is open, and merging the parent restacks it. Starting it is refused while a parent hasn't started yet (still in Backlog or Todo) or was canceled; once the parent is in progress, the card can be dispatched and its branch stacks on the parent's.
--prefers-machine: the orchestrator only dispatches the issue to a workspace on that machine, leaving it in Todo until one is free.

On the board

Press Ctrl+P and pick "Issues", or hit Enter on the Issues sidebar nav. You land on the Kanban board, one column per status (Backlog, To Do, In Progress, Review, Done, and Canceled; an empty column folds to a narrow strip). 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
`Tab`	Cycle the workflow filter
`o`	Open the selected card's workspace
`/`	Search cards
`f`	Filter by workspace
`Esc` / `q`	Close an open card

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

Click Issues in the sidebar (⌘I). You land on the Issues board, one column per status (Backlog, To Do, In Progress, Review, Done, and Canceled). Click + (New issue) in the toolbar, or press n, type a title, and press Enter to add it to Backlog. Click a card to open its task pane, where you edit the title and description in place and set Status, Workflow, and Priority.

Drag a card to another column to move it, or within a column to reorder it. The keyboard works too:

Key	Action
`h` / `l`	Step between columns
`j` / `k`	Step between cards 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
`n`	New issue
`s`	Start the card on a workspace
`e` / `E` (shift)	Edit the description / open it in your editor
`o`	Open the selected card's workspace
`/`	Search cards
`f` / `w`	Filter by workspace / workflow
`Esc`	Close the task pane

The task pane's More (⋮) menu has the same actions: Move left, Move right, Start, Assign…, Edit description, Open in editor, Open workspace, and Copy branch name.

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 viewby dragging the card into To Do on the board (or pressing L on it) or by asking the orchestrator to:

you: promote fix-login-bug-on-safari.
 
Orchestrator: ✓ moved to todo. dispatched to delta.
                workspace: delta
                branch: you/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 issue start fix-login-bug-on-safari --workspace delta

That moves the card to In Progress, creates the branch you/fix-login-bug-on-safari in the workspace's worktree, and feeds the issue prompt into the workspace's agent CLI. The sidebar badge next to delta flips from · (idle) to ⏵ (working)a dot (idle) to a green ▶ (working), and the row names the agent it's running.

Jump in any time. Enter on the workspace's sidebar rowClicking the workspace's sidebar row (or pressing its ⌘1–⌘9 shortcut) drops you straight into its session to watch the run live.

you@hub — myapp

                              
 myapp                        
                              
                              
  🔍 Search               ⌃P  
                              
                              
  💬 Orchestrator             
                              
  📋 Issues                   
                              
  🚀 Changelog                
                              
                              
 — Workspaces —               
 · alpha                 idle 
 · bravo                 idle 
 · charlie               idle 
 ⏵ delta            Developer 
                              
   ⚙     📣

 Issues · myapp   3 total                                                     Workflow: All ▾ Workspace: All ▾ 
                                                                                                               
 BACKLOG (2)                                  T   IN PROGRESS (1)                              R     D     C   
 Add CSV export                               O   Fix login bug on Safari                      E     O     A   
  task                                             task  ⎇ you/fix-login-bug-on-safari         V     N     N   
                                              D                                                I     E     C   
 Tighten rate-limit copy                      O                                                E           E   
  task                                                                                         W    (0)    L   
                                             (0)                                                           E   
                                                                                              (0)          D   
                                                                                                               
                                                                                                          (0)  
                                                                                                               
  h/l col   j/k row   ⏎ open   ⇧h/⇧l move col   ⇧k/⇧j reorder   ⇥ workflow   f filter   / search   r refresh

myapp

Orchestrator⌘O

Issues⌘I

Changelog⌘L

Workspaces

alphaIdle

bravoIdle

charlieIdle

deltaDeveloper⌘1

Zen mode off

Filter:WorkflowsWorkspacesboard 2sSearchNew issue

BACKLOG2

Add CSV export

task

Tighten rate-limit copy

task

TO DO0

IN PROGRESS1

Fix login bug on Safari

taskyou/fix-login-bug-on-safari

REVIEW0

DONE0

CANCELED0

h/l column   k/j card   ↵ open   ⇧h/⇧l move   ⇧k/⇧j reorder   drag to move or reorder   s start   a assign   e edit   E editor   n new

Badge	Workspace state
`·`	idle: no issue assigned
`⏵`	working: agent actively running a turn
`?`	awaiting input: finished a turn, sitting at the prompt
`⚠`	awaiting permission: showing a permission dialog
`⏸`	paused: runner stalled on a usage/session limit

Glyph	Workspace state
dot	idle: no issue assigned (the row reads Idle)
green ▶	working: agent actively running a turn
yellow `?`	awaiting input: finished a turn, sitting at the prompt
`⚠`	needs permission: showing a permission dialog
`⏸`	paused: runner stalled on a usage/session limit

A finished dev workspace doesn't get its own completion glyph: on promotion the poller closes its session, so the row reads idle immediately. The "done, awaiting human" state lives in the sidebar's review sections, not on the workspace row.

Review the branch

When the workspace finishes, it writes a review-ready marker into its worktree. The hub poller picks it up on the next tick and moves the card into Review. The in-progress → review transition pushes the branch and opens a PR, the workspace's session closes, and its row drops back to idle. The card shows in the sidebar's Queued for Review section:

The Queued for review section lists it as a two-line row: the issue title over its branch, you/fix-login-bug-on-safari.

Review the change in the PR's diff. To run it as well (boot its dev server and click through the app), tag a workspace for review; see set up review workspaces. With a free review workspace, the hub daemon loads the queued card onto it automatically (or press Enter on the queued row to pick a slot), and the Review agent serves the branch there. The row then moves to Ready for Review with a ✓ and its machine:workspace locationcyan check. A fresh project has no review workspace, so Enter onclicking the queued row only reports "No review workspace is configured." and the card waits in the queue.

Accept the issue

Accept by moving the card to Done: L in the kanban view from Reviewdrag it from Review to Done on the board (or press L), or Approve in its review view, or:

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

You can also ask the orchestrator in chat:

you: merge it.

The move runs the workflow's review → done transition, which pushes the branch and merges it. If a PR is open for the branch, Shelbi squash-merges it through the GitHub CLI (so a PR-protected branch still accepts it); otherwise the hub squash-merges into the workflow's base branch (main in the shipped task workflow) and pushes. Asked to merge, the orchestrator runs that same merge action and then moves the card to Done itself.

The dev workspace has been free since the handoff, and the orchestrator dispatches it to the next ready todo card on its own.

You own the Review → Done move

The orchestrator never moves an issue out of Review on its own initiative. Deciding when an issue reaches Done (and with it, the merge) is the human checkpoint, until you hand that step off to Zen Mode.

What just happened

You added an issue, 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 issues 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.
Customize the orchestrator prompt: 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.