Enable Zen Mode

Instructions for

By default the orchestrator is the scheduler and you own both ends: you decide what gets promoted out of backlog, and you accept what comes back from review. Zen Mode changes that. The orchestrator promotes backlog items it judges safe to run and lands exact-provenance PRs that clear a project-defined confidence bar.

This page is the practical on-ramp: configure the bar, flip the switch, and watch one issue land end to end. The Zen Mode concept page has the full reference for everything you can tune.

Set the confidence bar

Before turning Zen on, tell Shelbi what "safe to merge" means for this project. The minimum useful config is a list of local checks the orchestrator runs against every Zen-eligible review before it lets the PR merge.

Add a zen block to the project YAML

Open the project's shared YAML (~/.shelbi/projects/<name>.yaml in global mode or <repo>/.shelbi/project.yaml in in-repo mode) and add a zen block:

# ~/.shelbi/projects/<name>.yaml (global mode)
name: myapp
repo: /Users/you/Workspaces/myapp
# … the rest of the wizard's output …
 
zen:
  checks:
    local:
      - 'cargo test --workspace'
      - 'cargo clippy --workspace --all-targets -- -D warnings'
  ci_timeout: 900   # seconds (15 minutes, the default)
  danger_paths:
    extend:
      - 'crates/shelbi-state/src/migrations/**'

Three things to know about that block:

checks.local: shell commands run from the worktree root. Each must exit 0 for the branch to clear the bar. Anything red leaves the issue in review for you, with a tagged reason in the activity feed.
ci_timeout: how long to wait for required GitHub checks to settle after the PR opens. Anything still pending when the deadline hits bails out. Integer seconds; default 900 (15m). A duration string like 15m is rejected and stops the project YAML from loading.
danger_paths.extend: globs the orchestrator treats as too sensitive to auto-merge. Shelbi already ships built-in danger paths and detects more from your project shape (cargo workspace, next.js app, .github/, etc.); extend adds yours on top. override replaces everything if you want the explicit list.

Apply the change

shelbi reload

Verify Shelbi sees the config

shelbi zen status

zen mode: off
checks:
  - cargo test --workspace
  - cargo clippy --workspace --all-targets -- -D warnings
ci timeout: 15m
danger paths (detected: cargo workspace, github):
  - .github/workflows/**
  - scripts/install.sh
  - *.yaml
  - *.yml
  - LICENSE
  - package-lock.json
  - Cargo.lock
  - Cargo.toml
  - rust-toolchain.toml
  - .cargo/config.toml
  - .github/CODEOWNERS
  - .github/dependabot.yml
  - crates/shelbi-state/src/migrations/**
last crash: never
in-flight zen issues: 0

The danger-path list is the fully resolved set of guarded globs: the built-in defaults, the globs contributed by your detected project shapes (detected: … names them), and anything you added under extend, deduped into one flat list. If something you expected to be guarded isn't on it, add it under extend.

Flip the switch

Any of these works:

CLI: shelbi zen on

Palette: Ctrl+P → Turn Zen Mode on
Hotkey: Alt+Z (the global.zen_toggle binding) while the Activity view has focus

The first time you turn Zen on from the TUI, an Enable Zen Mode? intro explains what it does (tick "Don't show this again" to skip it next time).

Rebinding: if your terminal swallows Alt (macOS Terminal.app does), set defaults.global.zen_toggle in ~/.shelbi/keys.yaml to another chord, such as ctrl-g, ctrl-shift-z, or 'ctrl-\' (quoted), or rebind it in Settings ▸ Keybindings. See keys.yaml.

You'll know it's on by the full-width green ZEN MODE ON band along the bottom edge of the sidebar, under the toolbar. That band is the at-a-glance "the agent is in lead mode" signal. When Zen is off or paused, the band is simply absent.

 Orchestrator
 Issues
 Changelog
 
 Workspaces
 · alpha
 · bravo
 · charlie
 
 ⚙  📣
 ZEN MODE ON

Sidebar: click the Zen pill at the bottom of the sidebar
Shortcut: ⌥Z, or View ▸ Turn Zen Mode On
Palette: ⌘K → Turn Zen Mode on

The first time you turn Zen on from the app, an Enable Zen Mode? intro explains what it does (tick "Don't show this again" to skip it next time).

You'll know it's on by the pill at the bottom of the sidebar: it turns green and reads Zen mode on. That pill is the at-a-glance "the agent is in lead mode" signal. When Zen is off or paused, it reads Zen mode off.

To use a different shortcut, rebind Toggle Zen mode in Settings ▸ Keybindings (⌘,), or set defaults.global.zen_toggle in keys.yaml; the bindings are shared with the TUI.

Watch one issue land end to end

Drop a small, clearly-in-scope issue into the backlog:

you: tighten the rate-limit error copy to mention the retry window.

With Zen off, the card would sit in backlog waiting for you to promote it. With Zen on, the orchestrator scans backlog when a workspace frees up, runs the judgment categories from your project's zenmode.md against each mechanically-eligible card, and promotes the ones at least one category applies to. You'll see a Zen row in the Activity view (Ctrl+P → Activity⌘K → Activity, or Go ▸ Activity):

promoted Tighten the rate-limit error copy   backlog → todo

The dispatch and run that follow look exactly like the manual loop: the card moves to in_progress, the workspace badge flips to working, and the agent works the prompt.

Zen only auto-merges without a review workspace

If the project declares any review-tagged workspace (new projects do, and the review workspaces guide sets one up), Zen still auto-promotes and dispatches, but it never runs the bar on a handoff: every finished issue waits for you to load it and Approve on the review slot. Remove the slot (or its review tag) to let Zen merge on its own.

What changes is what happens when the workspace writes its review-ready marker. Instead of stopping at review for your inspection, the orchestrator runs the bar:

review-marker -> probe (local checks, merge conflict, diff size, danger paths)
              -> orchestrator's own review of the diff vs the issue
              -> pr-create (only if no matching PR is open)
              -> ci-watch
              -> move to done (the review -> done transition merges)

The probe, PR, and CI steps are single-purpose CLI primitives (see shelbi zen). The probe's repository, base, reviewed head, and prebuilt integration commit are passed unchanged to pr-create and ci-watch, so CI runs on exactly the candidate that was reviewed, and any movement fails closed. The in-progress → review transition already opened the PR, so pr-create only runs when it's missing or has drifted. The merge itself belongs to the workflow: moving the card to done fires the review → done transition, which pushes and merges the branch. (shelbi zen pr-merge is reserved for the release flow; running it on an ordinary issue would merge twice.)

2026-06-22T14:31:08+00:00 project=myapp task=tighten-rate-limit-error-copy workflow=task review -> done reason=orchestrator:zen-merge_pr=241 from_category=handoff to_category=done

The review → done move merges the branch, and the card lands in Done:

you@hub — myapp

                              
 myapp                        
                              
                              
  🔍 Search               ⌃P  
                              
                              
  💬 Orchestrator             
                              
  📋 Issues                   
                              
  🚀 Changelog                
                              
                              
 — Workspaces —               
 · alpha                 idle 
 · bravo                 idle 
 · charlie               idle 
                              
   ⚙     📣                   
                              
 ZEN MODE ON

 Issues · myapp   1 total                                                     Workflow: All ▾ Workspace: All ▾ 
                                                                                                               
   B     T     I     R   DONE (1)                                                                          C   
   A     O     N     E   Tighten the rate-limit error copy                                                 A   
   C                 V    task                                                                             N   
   K     D     P     I                                                                                     C   
   L     O     R     E                                                                                     E   
   O           O     W                                                                                     L   
   G    (0)    G                                                                                           E   
               R    (0)                                                                                    D   
  (0)          E                                                                                               
               S                                                                                          (0)  
               S                                                                                               
                                                                                                               
              (0)                                                                                              
                                                                                                               
  h/l col   j/k row   ⏎ open   ⇧h/⇧l move col   ⇧k/⇧j reorder   ⇥ workflow   f filter   / search   r refresh

myapp

Orchestrator⌘O

Issues⌘I

Changelog⌘L

Workspaces

alphaIdle

bravoIdle

charlieIdle

Zen mode on

Filter:WorkflowsWorkspacesboard 2sSearchNew issue

BACKLOG0

TO DO0

IN PROGRESS0

REVIEW0

DONE1

Tighten the rate-limit error copy

task

CANCELED0

h/l column   k/j card   ↵ open   ⇧h/⇧l move   ⇧k/⇧j reorder   drag to move or reorder   s start   a assign   e edit   E editor   n new

Fail any of them (a flaky test, a too-large diff, a touch on a danger path, a red CI) and the card stops in review for you, with a tagged reason line that tells you why:

Reason	Meaning
`zen:failed-checks cmd=… exit=…`	A `checks.local` command exited non-zero.
`zen:diff-too-large files=… lines=…`	Diff exceeded the size threshold.
`zen:danger-path paths=…`	One or more danger-path globs matched.
`zen:merge-conflict files=…`	Branch wouldn't merge cleanly.
`zen:ci-timeout duration=…`	CI didn't settle within `ci_timeout`.
`zen:review-reject`	The orchestrator's own diff review failed; the card goes back to `todo` with its findings.

The card behaves like any other manual review from there. You review the branch, fix what needs fixing, and either accept it yourself (move it to done) or push new commits that clear the bar on the next attempt.

The activity feed

Zen-driven moves show up in the Activity view (Ctrl+P → Activity⌘K → Activity, or Go ▸ Activity). Press z (or click the Zen pillfilter) to filter the feed down to them, so machine-initiated actions are easy to separate from anything you did. The most common reason strings:

Reason	When it fires
`orchestrator:zen-promote category=<n>`	The orchestrator promoted a backlog card under judgment category `<n>`.
`orchestrator:zen-decline reason-text=<short>`	A mechanically-eligible card was considered and explicitly left in backlog; the orchestrator surfaces it in its next reply.
`orchestrator:zen-merge pr=<n>`	A reviewed issue cleared the bar and landed on `main`.

shelbi events tail --follow shows the same lines in raw form if you want to watch from a shell. In the raw log, spaces in a reason become underscores (orchestrator:zen-promote_category=2, orchestrator:zen-merge_pr=241).

Pause and stop

Three flavors of "stop", in increasing severity:

shelbi zen pause: softer. No new auto-promotions, but Zen issues already mid-flight keep applying the bar. Use this when you want to triage incoming work yourself for a bit without aborting in-flight merges.
shelbi zen off (or the Zen toggle in the app): hard off. New auto-promotions stop and the orchestrator stops initiating the merge bar on review handoffs. Anything already in the bar runs to completion on its current trajectory.
Per issue: set zen: { enabled: false } in the issue's frontmatter to keep Zen from auto-promoting it, without changing the global mode. Moving a card from todo back to backlog yourself also stops Zen from promoting it, until you move it out of backlog again. A card that reaches backlog any other way can still be promoted.

Crash recovery

If the orchestrator's session dies mid-run, Shelbi relaunches it automatically, and Zen keeps the mode it was in. If you'd rather look over in-flight work before Zen carries on, run shelbi zen pause (or shelbi zen off), check, and turn it back on with shelbi zen on.

Tune the bar over time

The values you set in project.yaml are the easy half. The judgment categories that decide which backlog items the orchestrator considers promoting, and the merge conditions it applies, live in a policy file you own, not the YAML:

~/.shelbi/projects/<name>/zenmode.md      # global mode
<repo>/.shelbi/zenmode.md                 # in-repo mode

Open it from the palette (Edit Zen Mode) or any editor. Its first line is the one-line summary the heartbeat re-injects into the orchestrator, so keep it accurate when you change the policy. You can tune the auto-promote logic for your project (what counts as "routine," when to refuse, how to phrase a decline) by editing prose, not code. The next page, customize the orchestrator prompt, walks through doing it end-to-end.

In the meantime, the deep reference for everything Zen touches:

Zen Mode: the full mental model, the high-confidence bar, judgment categories, per-issue overrides, configuration reference.
shelbi zen - every subcommand the orchestrator sequences during exact-provenance auto-merge, callable by hand for one-off probes.
The events log: the canonical format of every mode=zen and orchestrator:zen-* line Zen emits.

You've handed the agent autonomous triage and merge flow, and given it a confidence bar that matches this project. The last step is making the orchestrator itself yours: customize the orchestrator prompt to change routing rules, tune Zen's judgment, and adjust how the orchestrator reports back to you.