Set up your first project

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).

From the Git repository you want Shelbi to manage, install Shelbi and run its detected setup:

brew install jlong/shelbi/shelbi jlong/shelbi/shelbi-desktop
shelbi project add

Shelbi runs a preflight, asks where issues should live (and which runner, if you have both), then shows one plan card to confirm. It does not write project state until you confirm the card.

The desktop app's Add Project wizard

The desktop app adds a project with its own short wizard instead: Add project on the Welcome to Shelbi window, + Add project in the project switcher (click the project name at the top of the sidebar), or File ▸ Add Project…. It asks for the Project folder (Browse, or type a path), then Agent defaults (the Default Harness, Claude Code or Codex, and its Default model), then Where should settings live? (In the project or Outside the project), and Create Project writes the config, agents, and workflows. Okay on You're all set! opens the project on its Orchestrator.

The wizard creates a file-system board, without the preflight, the issue-tracker questions, or the plan card. For those, run shelbi project add in the repo as below; the project then shows up in the desktop app too, since both clients share one daemon.

1. Watch the preflight

Setup 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
  ✓ agent               codex 0.27.0 on PATH
  ✓ machine             10 cores

Shelbi detects the repository root, default branch, origin, supported agent runners, and the machine's core count. The values appear as each check completes. With both runners installed, the agent row lists both (claude <version> + codex <version> on PATH).

If both runners are installed

When both Claude Code and Codex are on PATH, Shelbi cannot infer which one you prefer. It asks exactly one runner question before the plan card:

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

Choose one and setup continues.

2. Choose where your issues live

Next, Shelbi asks where this project's board should live:

Where should this project's issues live?
  GitHub Issues  cards are GitHub issues your team can see and file (requires `gh` logged in)
  File system    private markdown files on this machine (no GitHub needed)
? Issue tracker:
> GitHub Issues
  File system

GitHub Issues stores each card as a GitHub issue. It is pre-selected, with the owner/repo pre-filled, when your origin remote is a GitHub repo. Shelbi preflights first: gh must be installed and authenticated, and your account must be able to read issues and create labels on the repo (Issues enabled plus push access). If the preflight fails, Shelbi explains the fix and lets you retry or fall back to File system, so a GitHub config that would not load is never written. On success it creates shelbi:id/* and shelbi:status/* labels on first use and stores a small metadata block in each issue's body.
File system keeps the board as private markdown under ~/.shelbi/projects/<name>/tasks/. No GitHub needed, and it is the default.

You can move a board between backends later with shelbi issue-store migrate. For the full picture of what the GitHub backend writes onto your repo (the label scheme, the metadata block, and how assignees gate Zen Mode), see the GitHub Issues backend.

3. Confirm the setup card

After preflight, Shelbi summarizes everything it will create:

  ┌─ myapp ────────────────────────────────────────────────────┐
  │                                                            │
  │  repo        ~/code/myapp (main)                           │
  │  github      github.com/you/myapp                          │
  │  agent       codex                                         │
  │  issues      GitHub · you/myapp                            │
  │  workspaces  created at first boot (orchestrator interview)│
  │  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.

On a file-system board the issues row reads file system (local markdown). The written plan also declares the local hub machine, the shipped task and subtask workflows, and the default agent roles. The detected runner becomes the orchestrator's runner; both built-in runner declarations stay in the project config, so agents can use either. 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:
? Issue tracker:

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. Only the Orchestrator runner answer is saved today; the Agent runner answer is not written, and each agent resolves its own runner. Workspaces themselves are sized and named later, in the orchestrator's first-boot interview.

4. Land on the dashboard

After Enter, Shelbi prints ✓ Project <name> created. and launches the TUI. On a file-system board, the new board contains one Backlog card named Welcome to Shelbi (a GitHub Issues board shows your repo's issues instead). The first time you set up a project on this machine, the sidebar also 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.

After Enter, Shelbi prints ✓ Project <name> created. and launches the TUI in that terminal. The desktop app is a second client over the same daemon, so open Shelbi.app and pick the project under Projects on this Mac, or from the project switcher at the top of the sidebar if the app is already open.

On a file-system board, the new board contains one Backlog card named Welcome to Shelbi (a GitHub Issues board shows your repo's issues instead). The Welcome card is the first hands-on tour: drag it from Backlog to To Do and watch Shelbi dispatch it to an available workspace in the sidebar. The card is only a guide and is safe to delete.

To change settings later, open Settings (⌘,, or the gear at the bottom of the sidebar): its project section has Workspaces, Workflows, and Agents pages. The command palette (⌘K) also lists Edit Project Settings and the other config files once you type "Edit", and File ▸ Edit Configuration does the same; they open the file in your editor. 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:

  ✗ agent               claude and codex not found on PATH
  ✓ machine             10 cores
 
No supported agent runner was found on PATH. Install and authenticate Claude Code (https://docs.claude.com/en/docs/claude-code) or Codex (npm install -g @openai/codex), then start 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 described above. You can also use Add project on the launch screenthe desktop app's Add Project wizard (File ▸ Add Project…).

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