Getting Started

Shelbi is an agent orchestrator for your desktop and terminal: a board of issues, a pool of git workspaces, and an orchestrator that keeps the workspaces loaded with work and shepherds each result back for review. This guide is the shortest path from an empty machine to that loop running on one of your own repositories.

You'll work through it roughly in order (each page assumes the one before it), but the pages stand alone if you already have part of the setup.

The arc

You'll start by installing the binary and setting up a project. On a fresh machine, shelbi opens a launch screen where you add your first project; shelbi project add, run inside the repo, walks the full detected setup instead. Shelbi checks the repo, runner, and machine, asks where issues should live, then shows one detected plan. Press Enter to write it and open the dashboard, or press c to customize the detected values. Then you'll run your first issue end to end, watch a single card cross the board, and review the branch it produces.

From there the guide opens up: a multi-workspace dispatch loop fills the whole pool and runs cards in parallel, review workspaces load a finished branch onto a live dev server so you can click through the change, Zen Mode hands both ends of that loop to the orchestrator, and customizing the orchestrator prompt shows how to encode your own routing rules, Zen judgment, and reporting style.

The last page steps back to the model underneath all of it: Workflows, the per-project YAML that declares the statuses an issue moves through and the git side-effects that fire on each transition. Read it once here and the rest of the docs (every concept page and every branching-model deep-dive) clicks into place.

Where to go next

• Concepts: the reference pages behind the loop: agents, workspaces, the orchestrator, the events log, and Zen Mode.
• Understanding Workflows: deep-dives that map trunk-based, git-flow, feature-branch, and forking onto a Shelbi Workflow, once you know the workflow basics.