# Set up your first project

Let Shelbi inspect your repo and machine, confirm one setup card, and land on a dashboard that is ready to use.

```text
Set up Shelbi for the Git repository in my current directory. Run `shelbi`, review the preflight and detected setup card with me, and press Enter only after I approve it. If I want to change a detected value, use `c` to Customize. Do not hand-write the generated config.
```

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

```bash
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:

```text
  ✓ 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.

<Callout type="note" title="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:

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

Choose one and setup continues. This is the only extra question on an otherwise
detected Git repository.

</Callout>

## 2. Confirm the setup card

After preflight, Shelbi summarizes everything it will create:

```text
  ┌─ 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:

```text
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:

```text
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](/docs/configuration/project) for the full schema and
[Config modes](/docs/concepts/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:

```text
? <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:

```text
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:

```text
  ✗ 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](/docs/guides/getting-started/first-task).