Set up your first project

From the Git repository you want Shelbi to manage, install and start it:

brew install jlong/shelbi/shelbi && shelbi

On the happy path, Shelbi asks one question: launch the detected plan? It does not write project state until you confirm the card.

1. Watch the preflight

First-run setup prints the Shelbi banner, then checks the environment in front of you. A typical preflight looks like this:

  ✓ git repo            ~/code/myapp
  ✓ default branch      main
  ✓ remote              github.com:you/myapp.git
  ✓ agent               codex 0.27.0 on PATH
  ✓ tmux                3.5a
  ✓ machine             10 cores, recommending 4 workspaces

Shelbi detects the repository root, default branch, origin, supported agent runners, tmux, and a workspace count suited to the machine. The values appear as each check completes.

? Which agent?
  claude (<detected version>)
  codex (<detected version>)

2. Confirm the setup card

After preflight, Shelbi summarizes everything it will create:

  ┌─ myapp ────────────────────────────────────────┐
  │                                                          │
  │  repo        ~/code/myapp (main)                         │
  │  github      github.com:you/myapp.git                    │
  │  agent       codex                                       │
  │  workspaces  created on first boot                       │
  │  workflows   task (branch → PR → review) · subtask       │
  │  agents      orchestrator · developer · review           │
  │              (+ qa, security, adversarial, opt-in)       │
  │                                                          │
  │  Everything above is editable later: Ctrl+Space → "Edit" │
  └──────────────────────────────────────────────────────────┘
 
  Enter launch    c customize    q quit

• Press Enter to create the project and open the dashboard.
• Press c to customize the detected values before creating anything.
• Press q, Esc, or Ctrl+C to quit without writing project state.

The displayed plan includes the local hub, the shipped task and subtask workflows, and the default agent roles. Both built-in runner declarations remain available in settings, even though the detected runner is the one the orchestrator uses for the workspaces it creates. The workspace pool starts empty: the orchestrator provisions it on first boot, asking how many workspaces and which naming scheme you want and creating each with shelbi workspace add.

Customize instead

Pressing c opens the detailed path. Each detected value is prefilled, so press Enter to keep it or edit it:

Customize setup. Press Enter to keep each detected value.
 
? Project name:
? Path to the repo:
? Default branch:
? GitHub repo URL (optional):
? Agent runner (used by every workspace):
? Orchestrator runner:

This is where you can choose a different project name or root, change the branch or remote, or use a different runner for the orchestrator. Workspaces themselves are sized and named later, in the orchestrator's first-boot interview.

3. Land on the dashboard

After Enter, Shelbi prints ✓ Project <name> created. and launches the TUI. The new board contains one Backlog card named Welcome to Shelbi and the sidebar briefly shows:

Ctrl+P palette · type E to edit settings

The Welcome card is the first hands-on tour. Promote it from Backlog to Todo and watch Shelbi dispatch it to an available workspace in the sidebar. Open the command palette with Ctrl+P; type E to find project and agent settings. The card is only a guide and is safe to delete.

To change settings later, use that Ctrl+P, then E path. You can also edit the generated project files directly and run shelbi reload. See Project configuration for the full schema and Config modes if you want to share config through the repository.

Edge cases before the card

The directory is not a Git repository

Shelbi asks before initializing Git:

? <path> is not a Git repo. Initialize one here with git init -b main? (Y/n)

Accept to continue. Decline and Shelbi writes nothing, then prints:

No files were written. Run git init -b main and try Shelbi again.

A prerequisite is missing

Failed checks are shown with ✗, and setup stops with a concrete next step. For example:

  ✗ tmux                not found on PATH
 
tmux was not found on PATH. Run brew install tmux, then start Shelbi again.

If no supported runner is found, Shelbi points to Claude Code and Codex install instructions and asks you to authenticate one before starting Shelbi again. No partial project is left behind.

Add another project

Run shelbi project add from another repository. It uses the same preflight, card, Customize path, and dashboard launch as first-run setup.

Next

Your project is configured and the Welcome card is ready. Continue with Run your first task.