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 project's sessions, 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.

In the flat global file the name: key is a free-form human label (see top-level fields); it never sets the id. The committed in-repo project.yaml is the one exception, described below.

In global mode every field lives in the one flat ~/.shelbi/projects/<id>.yaml that shelbi init --mode global writes. In-repo mode uses a two-file split instead. shelbi init --mode in-repo writes both halves; shelbi init --pick-up writes just the user-local half and reads the already-committed shared half in place:

• Shared fields (SHARED_PROJECT_FIELDS) — name, display_name, default_branch, default_workflow, orchestrator, agent_runners, runners, agents, zen, heartbeat, git, and the rest — live in the committed <repo>/.shelbi/project.yaml, so every clone shares them.
• User-local fields (LOCAL_PROJECT_FIELDS) — repo, machines, workspaces, editor — live in a per-machine ~/.shelbi/projects/<id>/local.yaml.

There is no flat ~/.shelbi/projects/<id>.yaml for an in-repo project. 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.

In the committed <repo>/.shelbi/project.yaml, the name: key is the project's canonical id: a valid slug that shelbi init --pick-up reads back to seed a teammate's local alias. The human label rides under display_name: (only emitted when the entered name was slugified into a different id). This is the one file where name: carries an id rather than a label. The id Shelbi uses locally is still the registry directory name (~/.shelbi/projects/<id>/), which can be a suffixed alias such as myapp-2 when the canonical id is already taken on your machine.

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: ~/Workspaces/myapp
default_branch: main
# Optional: tasks without `workflow:` use workflows/app.yaml instead of
# workflows/task.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 }

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: [gpu]           # every slot on hub inherits the gpu 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 the worktree's .claude/settings.local.json wires $CLAUDE_PROJECT_DIR/.shelbi/hooks/*.sh (session-start, stop, pane-working, pane-idle, pane-blocked) so the session 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 orchestrator session. It does not change worker slots. A worker slot no longer selects a runner: the dispatched agent (role) owns runner/model resolution through its agent.yaml manifest, and the project's runner fleet supplies the concrete launcher. So a project can run a Codex orchestrator while dispatching a task agent onto Claude, or run one agent on Opus and another on Sonnet, all resolved per agent rather than per slot. See agents for the manifest and the precedence chain.

agent_runners

A map from runner name to the command line agents are launched with. Referenced by orchestrator.runner, and used as the concrete launcher an agent resolves onto (kind-keyed lookup, bridged from this map when no top-level runners fleet is declared).

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

runners

An optional, kind-keyed runner fleet that layers on top of agent_runners: one entry per runner kind (claude / codex / generic) carrying the concrete launcher plus an optional house model / reasoning_effort authoritative for every agent of that kind. A field it omits falls through to each agent's agent.yaml recommendation. Empty by default; when empty, a kind resolves through the agent_runners bridge. See agents for the full shape and the resolution precedence.

runners:
  claude:
    command: claude
    # model / reasoning_effort omitted -> each agent's manifest decides
  codex:
    command: codex
    model: gpt-5          # authoritative for every codex agent

agents

Per-agent overrides keyed by the agent's directory name. Today each entry carries a single runner: field that pins which runner kind the project runs that agent on, authoritative over the manifest's preferred_runner. There is deliberately no per-agent model block: per-agent differentiation comes from each agent's manifest, and a house model is set once at the kind level in runners.

agents:
  orchestrator: { runner: codex }
  review:       { runner: claude }

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 }
  - { name: bob,   machine: m2 }
  - { name: rev,   machine: hub, tags: [review], slot: 3000 }

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 takes extend, which keeps the built-in danger list and adds yours, or override, which replaces the built-ins entirely. A legacy bare list still loads as extend, but the config-upgrade pass rewrites it to { extend: [...] }:

zen:
  checks:
    local:
      - cargo test --workspace --no-fail-fast
      - shelbi msrv-check            # build on the Cargo.toml rust-version
      - npm --prefix site test
  ci_timeout: 1200
  danger_paths:
    extend: [".env", "infra/**"]   # or: override: [...]

heartbeat

The recurring line the hub poller writes into events.log so the orchestrator wakes up to sweep active tasks even when no real transition has fired. It is the orchestrator's fallback wake-up and the stream's liveness signal. 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 60s → 2m → 4m → 5m, then resets to 60s 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: 60s   # standard cadence while work is in flight
  max: 5m         # back-off cap once the board is quiescent

disk

Hub disk management. Rust build output accumulates in the hub checkout's shared cargo target/ and can fill the data volume over a week of Zen builds, and a full volume looks like a wedged hub (probes hang, heartbeats stop, CLI calls take minutes). These two knobs bound that.

Both default to 20 GiB and apply even when the disk: block is absent, so an existing project is already protected without any config change. The block only makes the knobs explicit and tunable, and is elided from the wire form when left at the defaults.

disk:
  target_cap_gib: 20   # clear the hub's shared cargo target/ above this
  low_free_gib: 20     # warn when the work_dir volume drops below this

git

Where workspace branches are based, how generated task branches are named, and how they integrate back. See understanding workflows.

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

After substitution, branch must use the same safe characters Shelbi allows for generated refs: ASCII letters, numbers, -, _, and /. It must not end with /. A task's branch name resolves in this order:

1. An explicit branch: in the task's frontmatter.
2. The task's workflow git: block, when it sets branch or branch_prefix. It replaces the project's naming wholesale.
3. The project's git.branch template.
4. The project's git.branch_prefix, as <branch_prefix>/<id>.
5. <github-login>/<id>, using your authenticated GitHub username, or user/<id> when it can't be determined.

The shipped task workflow sets branch: '{{github_user}}/{{id}}'.

review

Behavior of the review interface's View Diff action.

By default View Diff opens Shelbi's own diff view. Set diff_command for a tool whose CLI takes a revision range (such as skim, invoked skim <base> <head>), which diff_tool can't express: that setting hands a tool a pair of files or folders.

The command runs in the review worktree with three placeholders substituted (shell-escaped):

• {worktree}: the review workspace worktree,
• {base}: merge-base(<base branch>, HEAD), the fork point, and
• {head}: HEAD.

{base} and {head} are the same range the built-in view shows.

review:
  diff_command: skim {base} {head}

A diff tool that exits without rendering leaves a short message in the pane rather than only git warnings.

The config-upgrade pass currently misreports a review: block as a removed key (PROJECT_REMOVED_KEY). The block is live: keep it rather than acting on that finding.

issue_tracker

Which backend the project's board lives in, plus the non-secret connection facts for a remote backend. An absent block is the default (file_system), so existing projects keep working. See GitHub Issues backend for the concept and the full behavior.

Only the selected backend's connection block is validated, so you can stage a github: block alongside backend: file_system without it failing the load. The auth token is never a field here: it is resolved out of band from gh (see prerequisites).

issue_tracker:
  backend: github
  github:
    repo: owner/repo
  # Optional, remote-only:
  refresh_secs: 30

github connection

issue_tracker budget

The rate-limit governor's thresholds for a remote backend. Every field defaults, so an untouched block is the shipped policy. See freshness and rate limits.

The PR-body template (pr-template.md)

Alongside the project's YAML, workflows/, agents/, and zenmode.md, each project carries a pr-template.md. It is the guidance a developer worker follows when it authors the pull-request body for a finished task. Shelbi materializes it from a shipped default on shelbi init, self-heals it on shelbi reload, and the boot-time config-upgrade pass materializes it for projects that predate the file. Like zenmode.md and the agent instructions, it is user-editable and self-heal-preserving: your edits survive a reload byte-for-byte, and editing the file changes the guidance workers follow for subsequent PRs.

Not a substitution template

Unlike the git.branch template above, pr-template.md has no {{var}} placeholders and does no variable substitution. It is instructions to the worker, not a fill-in-the-blanks form. Only an agent that understands the change can write a real summary, produce a Mermaid diagram, sketch an ASCII wireframe, or list a concrete QA checklist, so the worker reads the template and writes the body itself.

Where it lives

The path is config-mode-aware, resolving next to the rest of the project's config half:

What the shipped default asks for

The default template tells the worker to write the body for the human reviewer, grounded in the real problem the change solves rather than a copy of the task requirements, in these sections, top to bottom:

1. Summary: a few sentences on the feature or fix and the problem it solves, so the reviewer understands the why before the how.
2. Technical details: key design decisions and rejected alternatives, tradeoffs, risky or subtle areas, and any migration or rollout notes.
3. Data model changes: a conditional section, included only when the change touches a database or schema, with a Mermaid ER or class diagram GitHub renders natively.
4. UI changes: a conditional section, included only when the change alters the interface, with a shareable screenshot when one exists or an ASCII wireframe otherwise.
5. QA checklist: concrete, checkable items a reviewer or tester can run through, using GitHub task-list syntax.

Conditional sections are omitted entirely when they do not apply, so a non-schema, non-UI change carries only sections 1, 2, and 5.

How a worker uses it at handoff

When a worker finishes a task it reads pr-template.md, writes the finished body to .shelbi/pr-body.md in its worktree, then emits its ready marker as usual. The orchestrator picks up .shelbi/pr-body.md when it opens the pull request. If the file is absent (a worker that genuinely could not produce a useful description just does not write it), Shelbi falls back to a task-body-based PR, so a missing description never blocks the handoff.

The body belongs to the task it was written for. Dispatching a different task onto the worktree removes the file, and a pull request only uses a body from the task the worktree is currently on. Sending the same task back to the worktree, after a bounce for example, keeps its body.

See also

• Config modes — global vs. in-repo layout and the shared/user-local field split.
• Config upgrade: the boot-time pass that materializes pr-template.md for older projects and heals drifted config.
• Workspaces and the orchestrator — the concepts behind workspaces: and orchestrator:.
• Workflow config — the per-project status pipeline and its per-workflow zen / git overrides.
• GitHub Issues backend: the concept behind the issue_tracker block and how a GitHub-backed board behaves.