Project config

The project YAML is the root of a Shelbi project: it declares the repo, the machines work runs on, the runners agents boot, the workspace pool, and the Zen Mode policy. This page is the authoritative field reference. For the why behind each block, follow the concept links.

Where it lives

The file's location depends on the project's config mode:

The project id comes from the filename

A project's id is the config file's basename: ~/.shelbi/projects/shelbi.yaml has the id shelbi. The id is the machine-facing key: it names the state folder (~/.shelbi/projects/<id>/), the settings file, the tmux session, the event-log project=<id> field, and is what --project / $SHELBI_PROJECT match against. It must be a valid slug: lowercase ASCII letters, digits, -, and _, starting with a letter or digit. A file whose stem breaks that rule (Shelbi.yaml, my project.yaml) fails to load with an actionable error; the fix is to rename the file, not to edit a field.

The name: key inside the file is a free-form human label (see top-level fields); it never sets the id.

In global mode every field lives in one flat file. In in-repo mode the shared fields (name, default_branch, default_workflow, orchestrator, agent_runners, zen, …) are committed and the user-local fields (repo, machines, workspaces, editor) live in a per-machine local.yaml. Putting a field on the wrong side errors at load time. The canonical bucket lists are SHARED_PROJECT_FIELDS and LOCAL_PROJECT_FIELDS in shelbi_core::model.

Minimal example

# ~/.shelbi/projects/myapp.yaml (id `myapp`, taken from the filename).
# `name:` is an optional free-form label; omit it and the id `myapp` shows.
name: My App
repo: git@github.com:me/myapp.git
default_branch: main
# Optional: tasks without `workflow:` use workflows/app.yaml instead of
# workflows/default.yaml.
default_workflow: app
machines:
  - name: hub
    kind: local
    work_dir: ~/Workspaces/myapp
orchestrator:
  runner: claude
agent_runners:
  claude:
    command: claude
    flags: []
  codex:
    command: codex
    flags: []
workspaces:
  - { name: alice, machine: hub, runner: claude }

Top-level fields

machines

Each entry is a host where workspaces can run. The worktree for a workspace lives at <work_dir>/.shelbi/wt/<workspace-name>.

machines:
  - name: hub
    kind: local
    work_dir: ~/Workspaces/myapp
    tags: [review]        # every slot on hub inherits the review tag
  - name: m2
    kind: ssh
    host: m2.local
    work_dir: ~/work/myapp

orchestrator

The orchestrator is a single agent that watches the board and dispatches work. See the orchestrator concept.

orchestrator:
  runner: claude

To run the orchestrator with Codex, point orchestrator.runner at a declared Codex runner:

orchestrator:
  runner: codex
agent_runners:
  codex:
    command: codex
    flags: []

Shelbi validates that orchestrator.runner names an entry in agent_runners. Claude gets Shelbi's Claude-specific launch wiring (--append-system-prompt and the first-message bootstrap prompt). Codex is launched as the configured command plus flags, then receives an initial startup prompt containing the rendered orchestrator instructions and bootstrap request. Other runners launch exactly as configured. Put any required Codex mode flags in agent_runners.codex.flags.

Worker hooks are deployed into each worktree under .shelbi/hooks/, and Claude's .claude/settings.json references .shelbi/hooks/claude.* so the pane pushes orchestrator messages to the agent as they arrive. Codex has no hook channel Shelbi can wire without overwriting user-owned .codex/ configuration, so a Codex worker instead pulls its messages: its startup prompt carries a polling contract that tails .shelbi/messages/<task-id>.log. The chosen channel (hooks or polling) is recorded per launch in the events log.

orchestrator.runner only controls the dashboard/orchestrator pane. It does not change worker slots. Worker slots use their own workspaces[].runner value, so a project can run a Codex orchestrator while still dispatching tasks to Claude workers, or mix Claude and Codex workers in the same pool.

agent_runners

A map from runner name to the command line agents are launched with. Referenced by orchestrator.runner and workspaces[].runner.

agent_runners:
  claude:
    command: claude
    flags: []
  codex:
    command: codex
    flags: []

workspaces

The fixed pool of workspace slots. Each owns a stable worktree on its machine and picks up tasks from the board, switching branches (with cleared context) between assignments. See workspaces.

workspaces:
  - { name: alice, machine: hub, runner: claude }
  - { name: bob,   machine: m2,  runner: codex }
  - { name: rev,   machine: hub, runner: claude, tags: [review], slot: 0 }

To switch existing worker slots after setup, use:

shelbi workspace set-runner codex --all

That command edits the same workspaces[].runner fields shown above and validates that codex is declared in agent_runners. You can also update the YAML directly by changing each desired workspace row:

workspaces:
  - { name: alice, machine: hub, runner: codex }
  - { name: bob,   machine: m2,  runner: codex }

Leave orchestrator.runner unchanged unless you also want to change the dashboard/orchestrator pane. Run shelbi workspace list afterward; its RUNNER column shows the runner each workspace will launch.

Route a slot to review work by giving it the review tag. See review workspaces for the tag-routing model.

zen

Zen Mode configuration: which local checks gate a promotion, how long to wait on CI, and which paths always require human review. See Zen Mode. Per-workflow overrides live in the workflow file; per-task overrides live on the task frontmatter.

danger_paths accepts three forms. A bare sequence is shorthand for extend, which keeps the built-in danger list and adds yours; override replaces the built-ins entirely:

zen:
  checks:
    local:
      - cargo test --workspace
      - npm --prefix site test
  ci_timeout: 1200
  danger_paths:
    extend: [".env", "infra/**"]   # or: override: [...], or a bare list

heartbeat

The recurring line the hub poller writes into events.log so the orchestrator's events tail --follow watch wakes up to sweep active tasks even when no real transition has fired. See the events log for how the orchestrator consumes it.

The cadence is adaptive: it holds at interval whenever there's supervisable work in flight (any active, ready, or in-review task, even one emitting no events, which is exactly when the sweep earns its keep), and once the board is quiescent it backs off exponentially, doubling each idle tick up to max. Any real event snaps the cadence straight back to interval. So a fully idle hub relaxes 3m → 6m → 12m → … → 60m, then resets to 3m the moment something happens.

heartbeat accepts three shapes:

The map form's fields:

Durations take an explicit unit: 45s, 3m, 1h. A bare integer is rejected (there's no implicit unit).

heartbeat:
  interval: 3m    # standard cadence while work is in flight
  max: 60m        # back-off cap once the board is quiescent

git

Where workspace branches are based, how generated task branches are named, and how they integrate back. See the merge command.

git:
  base_branch: develop
  branch: '{{github_user}}/{{id}}'
  merge_strategy: rebase

After substitution, branch must use the same safe characters Shelbi allows for generated refs: ASCII letters, numbers, -, _, and /. It must not end with /. Resolution runs in order: an explicit branch: in the task's frontmatter wins; otherwise Shelbi renders git.branch; when neither is set it names the branch after your authenticated GitHub username, falling back to user. The shipped task workflow sets branch: '{{github_user}}/{{id}}'.

See also

• Config modes — global vs. in-repo layout and the shared/user-local field split.
• Workspaces and the orchestrator — the concepts behind workspaces: and orchestrator:.
• Workflow config — the per-project status pipeline and its per-workflow zen / git overrides.