# Changelog

Major Shelbi features and when they landed on main, newest first.

The major, user-facing features Shelbi has grown, each with the date it landed
on `main`, newest first. This page is hand-curated: it tracks capabilities, not
every commit, so small copy edits and cosmetic tweaks are folded away. Entries
are prose with `code` and links where they earn their place.

### August 5, 2026

**v0.7.2. Honest mid-flight comms and workflow-aware handoffs.**

**`shelbi message` tells the truth about delivery.** The command used to print a
checkmark and exit 0 the instant it wrote the durable record, conflating "queued"
with "the worker read it" — and on some hosts the ack never once landed (12 sent,
12 timeouts). Root cause: the worker's ack was gated behind `jq`, absent on stock
macOS and minimal Linux, so the ack block was silently skipped. Now the ack
extraction is `jq`-free and sends over `nc` (flavour-detected, `-N` on Linux) or a
`python3` fallback. The CLI stops over-promising too: a bare push prints
`queued … not yet confirmed delivered`, `--wait` blocks and exits non-zero on the
ack window elapsing, `shelbi message status <id>` reports the real outcome, and a
`done` task or dead pane is reported undeliverable rather than implying a future
pickup.

**Handoffs follow the workflow's base branch.** The workspace startup prompt
hardcoded `git rebase origin/main`, ignoring a task workflow's `git.base_branch`.
For fan-out workflows whose base isn't `main` (e.g. `feature/{{feature}}`), agents
that followed it produced wrong-base branches the merge guard rightly refuses. The
prompt now rebases onto the workflow's resolved base, mirroring the merge side so
the handoff and the merge target agree.

**Smaller fixes.** `task add`/`task edit` no longer hang reading stdin when the
body was already supplied by `--body`/`--body-file`/`-d`; the command palette hides
the redundant 'Switch Project' entry from its empty-query menu (it still surfaces
on typing); and the generated Homebrew formula drops the redundant `version`
stanza that `brew audit --strict` rejects.

### August 4, 2026

**v0.7.1. Feature-branch fan-out you can trust.**

**Subtasks land on their parent branch again.** A workflow whose `git.base_branch`
is templated — `feature/{{feature}}`, `update/{{update}}`, `task/{{task}}` — now
resolves that base from the task's frontmatter at every step instead of silently
falling back to `main`. A subtask filed without its parent link is refused at
dispatch rather than cut from a degraded base, `{{var}}` placeholders are validated
against a workflow's `required_params` at load, and the finish-flow rebase freshens
and restacks against the real `origin/<base>` — no more branches quietly rebased
onto `main` and polluted with unrelated history. Most important, the handoff-less
`merge` is now gated *before* a task is marked done: a merge that fails or
integrates nothing leaves the task in-progress and emits a `merge status=failed`
event instead of stranding a false `done` with the work landing nowhere. A
pre-merge ancestry guard also stops a wrong-base squash from reverting an
already-merged sibling.

**Reliability.** `shelbi daemon restart` now recovers a launchd job wedged in the
loaded-but-never-spawned state with `kickstart -k`, the orchestrator's event feed
self-drains and emits keepalives so a dead follower can't silently blind it, and a
review slot stranded by a quit or restart no longer re-runs the developer on resume.

**Interface.** The dashboard sidebar and review panel now share one user-adjustable
width, Add project moved into the projects sidebar, and an awaiting-input workspace
shows a yellow `?` badge instead of a speech balloon.

### August 1, 2026

**v0.7.0. Shelbi Zen ships, and a reviewer to match.**

**Shelbi Zen is a real autopilot now.** Zen can take a handoff branch all the
way to `main` on its own: it runs the project's local pre-merge checks, gates on
merge conflicts, diff size, and danger-path edits, then drives the PR create →
CI-watch → squash-merge flow to completion. `shelbi zen probe` self-recovers
when the hub's primary checkout is holding the task branch, and it flags the
cases that used to slip through — a stale base, an already-merged branch, or a
squash-merge that would silently revert a sibling PR. Orchestrator self-review is
now codified in the shipped defaults, so the old fresh-context evaluator subagent
is retired.

**A two-column review interface.** Reviewing a task is now a dedicated
experience: a left panel with the diff and reviewer actions,
a View Diff action alongside Chat with Reviewer, and a reject-reason prompt that
opens as a tmux popover with a real textbox and buttons. Queued-for-Review tasks
auto-load onto an idle review slot, the Review agent is dispatched there instead
of the status's Zen agent, and a review slot stranded by a quit or restart is
resumed on the next launch.

**The command palette learned about projects.** Switch Project is pinned to the
top with inline "Switch to X" entries, each project carries a loaded or unloaded
status glyph, and a second column lists your other projects — `Right` to focus
it, `Up`/`Down` to move, `Enter` to switch.

**A traveling sidebar for window-per-workspace navigation.** The dashboard
sidebar now travels with you across per-workspace windows, clamped to its
canonical width, and self-heals so a render fault or a process exit can't leave it
gone. Activity is a plain-language timeline with multi-line wrapping rows, and
project config validation errors surface directly in the sidebar.

**System configuration ships as a skill.** Shelbi bundles a system configuration
skill with an inventory and an all-surface lint, and injects the system plugin
into the built-in runners so a fresh install carries it.

**CLI and reliability.** `shelbi quit` tears down a running project cleanly, and
`shelbi task edit` gains non-interactive flags for title, body, and field
substitutions. SSH grew a stabilized managed `ControlMaster` — keepalive,
per-host locking, and mux recovery — and now surfaces the ssh diagnostic behind a
blank `exit status: 255` instead of swallowing it. The launchd daemon registers
idempotently, and the heartbeat and poller are hardened so a busy board or an
unreachable machine can't starve them.

### July 18, 2026

**v0.6.0. Workspaces, project names, and safer worktree integration.**

**Workspaces are provisioned by the orchestrator, not hand-edited YAML.** New
commands `shelbi workspace add <name>` and `shelbi workspace rm <name>` manage
the pool, and a fresh project's workspaces are created through a first-boot
interview: the orchestrator asks how many and which naming scheme (phonetic,
greek, or toy-story) and creates them on the current machine. `shelbi init` no
longer auto-provisions a pool.

**Shelbi no longer overwrites your worktree settings.** Its Claude hooks are
wired into `.claude/settings.local.json` — which Claude merges additively —
instead of clobbering a committed `.claude/settings.json`. A pre-existing
user-authored file is left untouched; the orchestrator merges the hooks in.

**The default-branch commit guard only fires inside Shelbi.** The `pre-commit`
guard that keeps agents from landing work directly on the default branch is now
scoped to Shelbi-managed panes, so your own commits from a normal shell are
never blocked. Its install is disclosed at `shelbi init`, and
`shelbi guard uninstall` removes it.

**Project names can be anything.** Name a project `ContextStore` or `My App`;
Shelbi slugifies it for the on-disk folder and settings file and shows the
human-readable name in the sidebar and command palette.

**`git.branch` branch-name templates.** The git block gains a `branch` template
key that parameterizes the branch names Shelbi cuts for tasks, rendered with
`{{var}}` substitution, and mutually exclusive with the older `branch_prefix`.
The shipped `subtask` workflow now cuts its branches from a `branch` template
instead of a prefix. See the [git block reference](/docs/configuration/workflow#git).

**Zen gained a fresh-context evaluator gate.** Before auto-merging a handoff,
Zen spawns a read-only evaluator that checks the diff against the task's
acceptance criteria and scope, so a branch that builds but doesn't do what the
task asked is caught. Zen integration commits are now authored by you with the
worker's real commit message rather than a synthetic bot identity.

**Codex orchestrator liveness.** The heartbeat keep-alive that nudges a
Codex-native orchestrator was restored, and `shelbi zen probe` now emits a
structured JSON error when its own setup fails instead of empty output.

### July 15, 2026

**v0.5.0. Shelbi runs on Codex, not just Claude.** The orchestrator and workers
can now run under Codex as a first-class runner alongside Claude. A
`RunnerAdapter` capability model unifies per-runner behavior so dispatch, the
board, and supervision treat both the same way, backed by a durable event and
wake queue that survives restarts; Claude consumes that same durable feed and
acknowledges each item so nothing is dropped or replayed. Where a runner has no
lifecycle hooks, Shelbi fills the gap: Codex workers receive orchestrator
messages by polling, and an idle Codex orchestrator wakes on board events rather
than waiting for a prompt. `shelbi status` surfaces per-agent integration health
and names the fallback reason when a runner is degraded, and switching a project
between the Codex-native and legacy runners is a guided migration rather than a
hand edit.

**A detected getting-started plan.** `shelbi init` now reads the shape of the
project and proposes a tailored setup plan instead of a one-size-fits-all
default.

**CLI version-mismatch detection.** The hub daemon warns when a workspace's
`shelbi` CLI version has drifted from the hub's, so a stale binary on a remote
machine shows up as a notice instead of confusing behavior.

**"Add project" from the palette.** A new palette flow adds a project through a
details dialog, without dropping back to the wizard.

**Zen merge-safety hardening.** Zen's PR create and merge steps now match on
exact provenance, so they no longer false-fail on Zen's own push or a rebased
head, and local checks run under a per-check timeout so a loaded hub fails fast
instead of hanging on one wedged check.

### July 10, 2026

**v0.4.0. A user-owned Zen policy that stays in context.** The Zen autopilot
policy is now a user-editable `zenmode.md` file, and the hub re-injects its
one-line summary into the orchestrator on a heartbeat cadence, so the policy
keeps steering even as the orchestrator's context turns over. See
[Zen Mode](/docs/concepts/zen-mode).

**`shelbi reload <target>`.** Reload one piece in place, a workflow, an agent's
instructions, or config, without restarting the whole hub.

**Palette and workspace conveniences.** The command palette gains "Edit …
Settings" openers, hidden until you query for them, and clicking an idle
workspace now opens a user shell in its tmux window instead of doing nothing.

**Auto-resume of usage-limit-stalled workers.** A worker parked on an agent
usage limit now resumes automatically when its quota window resets, rather than
sitting paused until you nudge it.

**Sturdier under bad remotes.** `list` and `status` bound their per-workspace
probes so a single wedged SSH host can't hang the whole command, and a worker's
worktree detaches from its task branch on handoff so the branch is free to merge
and clean up.

### July 9, 2026

**v0.3.0. A batteries-included default install.** `shelbi init` now sets up the loop
most projects want without any YAML editing. Two things landed. First, six
agent presets materialize on first load instead of three: the
`orchestrator`, `developer`, and `review` roles that run the core loop, plus
three specialized reviewers, `qa` (verifies a change against its acceptance
criteria), `security` (a defensive-only diff review), and `adversarial` (an
automated skeptic that tries to refute the change). The reviewers ship
materialized but unwired, so the default board stays a plain
`developer → review` loop and adding a gate is a one-line edit: name
`agent: qa` (or `security`, or `adversarial`) on a status. Second, the scaffold
ships two workflows instead of one. `task` is the new review-gated default:
branch off `main`, `Backlog → Todo → In Progress → Review → Done`, one PR on
the `In Progress → Review` edge, squash-merge to `main` on accept, with the
`Review` status served on a `review`-tagged workspace by the Reviewer agent.
`subtask` is a lighter flow for a piece of a parent task: it branches off and
merges into the parent's branch, opens no PR, and has no review. Fresh
projects get `default_workflow: task` written in, so the review gate is on out
of the box. See the [agents concept](/docs/concepts/agents) and the
[workflows guide](/docs/guides/getting-started/workflows#shipped-workflows-task-and-subtask).

### July 8, 2026

**v0.2.0.** The headline fix: launching a pane on a remote machine whose login
shell is zsh no longer fails at startup. The tmux targets Shelbi passed over
SSH were being eaten by zsh's equals-expansion, so remote workspaces died
before the agent ever started; they now come up cleanly. The release also
closes the loop on packaging: the release workflow now publishes the Debian
package to the signed APT repository as part of the tag-triggered pipeline, so
`apt install shelbi` picks up new versions without a manual publish step. And
it ships two supervision fixes. The hub poller can now drive a workflow that
declares no review/handoff status to completion: when a worker finishes and
its status has an outgoing transition that merges, the poller advances the
task along that edge (merge, branch cleanup) instead of stranding it in
progress. And the hub checkout is guarded against stray commits: a
Shelbi-managed pre-commit hook rejects commits made directly on the default
branch, backed by dispatch-time branch checks.

### July 7, 2026

**v0.1.0, the first versioned release.** Shelbi now ships as prebuilt
binaries, not just source. Pushing a `v*` tag runs a release workflow that
builds macOS (Apple Silicon and Intel) and Linux x86_64 binaries, publishes
them with SHA256 checksums and GitHub artifact attestations, opens a
version-bump PR against the Homebrew tap, and produces a Debian package.
`brew tap jlong/shelbi && brew install shelbi` on macOS; a signed APT
repository serves Ubuntu. See the
[install guide](/docs/guides/getting-started/install) for both paths.

### July 3, 2026

**Usage-limit pause detection.** The workspace poller now recognizes when a
worker has stalled on an agent usage limit rather than genuinely working, and
surfaces a `⏸` pause badge in the sidebar roster instead of leaving the pane
looking busy. You can tell at a glance which workers are blocked on quota and
will resume on their own versus which need a hand.

**Adaptive hub heartbeats.** The `heartbeat` cadence now backs off when the
board is quiet instead of firing at a fixed interval forever. It holds at the
standard `interval` (default `3m`) while there's supervisable work in flight,
then doubles each idle tick, capped at a new `max` bound (default `60m`),
once the board goes quiescent, and snaps back to `interval` on the next real
event. The config gains the `max` field: `heartbeat: 3m` still works (bare
interval, default cap), as does `heartbeat: off`, and a map
`heartbeat: { interval: 3m, max: 60m }` sets both bounds. Every existing
project gets back-off with no YAML edit. Backing off on "nothing supervisable
in flight" rather than "no log line" is deliberate: a silently-stuck
`in_progress` task also emits nothing, and the heartbeat sweep is exactly what
catches it. See the [`heartbeat` field reference](/docs/configuration/project#heartbeat)
and [the events log](/docs/concepts/events-log#heartbeats).

**`shelbi task resume`.** A stalled or killed worker no longer has to lose its
task. `shelbi task resume <task>` relaunches the runner in the worker's existing
worktree, picking the branch back up where it left off instead of dispatching
from scratch.

**Crash-safe workspaces.** Shelbi now auto-restarts a managed pane if its agent
crashes, and re-submits the in-flight prompt after the restart so the worker
resumes the task rather than sitting idle at a fresh prompt.

**Self-documenting config on `.yaml`.** New config scaffolds ship with their
optional sections present but commented, so the file itself documents every knob
you can turn. No need to hunt the reference to discover a setting exists. At the
same time every config file standardizes on the `.yaml` extension; existing
`.yml` files are migrated automatically on first load.

**Wizard simplified.** The onboarding wizard's sole phase is project setup.
The orchestrator prompt now reads *"You are the Orchestrator"* statically,
with no legacy name placeholder substitution at render time.
`~/.shelbi/shelbi.yaml` is now just the per-project `last_launched` index.

### July 2, 2026

**Review workspaces.** Reviewing a finished task now loads its branch into a
dedicated, long-lived review workspace with its own agent, rather than a
throwaway top-level clone. The orchestrator dispatches the review onto that
workspace, a review queue tracks what's waiting, and the sidebar gains `Ready`
and `Queued` sections so you can see the pipeline at a glance. The server pane
persists across reviews and is reaped on completion.

### July 1, 2026

**In-repo project config.** A project's configuration can now live inside the
repo at `.shelbi/project.yaml` instead of only under `~/.shelbi/`, so it can be
committed and shared with a team. `shelbi migrate-to-in-repo` converts an
existing global project in one step, and resolution is mode-aware about which
half of the config is user-local versus shared.

### June 30, 2026

**Two-way worker communication.** Workers can talk back to the orchestrator, not
just the other way around. A hub-side Unix socket (reverse-forwarded to remote
machines over SSH) carries a per-task message log, and hook-capable workers
inject those messages via `SessionStart` + `Stop` hooks; non-hook runners poll
for them in the prompt. On top of it sits a clarification loop (a worker can ask a
question and block for an acknowledged answer) plus `launchd`/`systemd`
supervision so the hub socket survives restarts.

### June 29, 2026

**Custom agents and configurable workflows.** The worker concept was reframed as
a *workspace* that runs a named *agent*, and dispatch resolves which agent to run
from the task's workflow status, so different columns can hand work to different
agents, each with its own context and a shared preamble. A `shelbi agent`
CLI quartet (`list`/`show`/`new`/`edit`) manages them. Kanban columns are no
longer hardcoded either: `workflows/statuses.yml` defines the status identity the
board and CLI render from.

**`shelbi open` and marker-free project resolution.** The pane-lifecycle entry
point is now the top-level `shelbi open <workspace>` (was `shelbi workspace
open`): same behavior, focus a workspace pane and create it if it doesn't exist
yet, under a shorter name. Shelbi also stopped dropping a `.shelbi/project`
marker into each repo to identify the active project; resolution now scans
`~/.shelbi/projects/*.yaml`, collects each project's local `work_dir`, and
matches the current directory against them (deepest match wins). Less stray state
on disk; the project YAML is the single source of truth.

### June 25, 2026

**Hub heartbeats.** The hub-side workspace-state poller appends a periodic
`<ts> project=<name> heartbeat` line to `~/.shelbi/events.log`, giving the
orchestrator's `events tail --follow` watch a guaranteed recurring trigger
when the board is otherwise quiet. Cadence is set per project via the
`heartbeat` key in `project.yaml`: `45s`, `3m`, `1h`, or `"off"` to
disable; default `3m`. Bare integers (`heartbeat: 180`) are rejected at
load time, so a missing-unit typo can't silently land as seconds. Emission
is debounced against any other write to the events log, so active boards
don't see padding. Heartbeats also pause while the hub is offline. A
quick TCP probe of `1.1.1.1:443` gates each due tick and emission resumes
once connectivity is back, so a coffee-shop wifi drop doesn't fill the
feed with no-op lines the orchestrator can't act on anyway. Heartbeats
are filtered out of the TUI activity feed by default (they'd produce
one "nothing happened" row every few minutes) but show up verbatim
under `shelbi events tail`. See
[the events log](/docs/concepts/events-log#heartbeats) for the line shape
and rationale.

### June 24, 2026

**Zen Mode.** An opt-in autopilot that lets the orchestrator promote and merge
low-risk work without waiting on you. A per-action confidence bar, configurable
project checks, danger-path guards, and a `dry-run` preview keep it honest, and
the `ZEN ON` pill in the sidebar (toggle with `Alt+Z`) makes the state
unmistakable. Zen auto-disables after an orchestrator crash so it never runs
unsupervised. Drive it from the CLI with `shelbi zen on|off|pause|status`.

### June 23, 2026

The first public cut of Shelbi: an open-source agent orchestrator for the
terminal, built on tmux. You talk to one orchestrator agent; it delegates work to
worker agents running in tmux panes, locally or over SSH, and reports back. This
landed the full local-to-remote loop end to end.

**Onboarding.** A first run with no projects drops you into a two-phase,
idempotent wizard that walks each project through setup. It auto-fills from your
environment (repo path, default branch, GitHub URL) and suggests a worker count
from available RAM. `shelbi` with no arguments launches the sole project's TUI,
or a fuzzy picker when there's more than one.

**The TUI.** A two-pane ratatui dashboard: a sidebar with Chat/Tasks
navigation, a live worker roster with state badges (working, awaiting input,
awaiting permission, review-ready, idle), and a `Ready for Review` queue;
beside it a content pane that swaps between the orchestrator chat, a five-column
Kanban (Backlog → Todo → In Progress → Review → Done), a Machines view, and a
Review list. `Ctrl+P` opens a Nucleo-backed fuzzy command palette as a tmux
popup for jumping between projects, workers, and views.

**Orchestration.** Move a card to Todo and the orchestrator takes it from
there. It watches the column and, as soon as a worker frees up, checks out the
highest-priority unblocked card on a fresh branch in that worker's own
worktree and starts the runner. `depends_on` blocks a task until its
dependencies land in Done. Finished work lands in Review and the worker stops;
activating a review checks the branch out, spawns a fresh agent pane to
interrogate the diff, and lets you merge into the default branch, or push and
open a PR with `--pr`.

**Anywhere tmux runs.** Workers run on the hub or on any machine reachable over
SSH with `tmux` and an agent CLI installed. Shelbi drives panes with
`tmux send-keys` + `capture-pane`, transparently prefixed with `ssh host --`
for remotes; a poller reads each pane's `shelbi:<state>` title marker into
worker status, which is what lights up the sidebar badges. Agent runners
(`claude`, `codex`, or any interactive CLI) are pluggable and declared
per project.

**State you can read.** No daemons, no servers, no database: every project,
task, log, and worker status is a markdown or YAML file under `~/.shelbi/`.
The same `shelbi` CLI the orchestrator drives (`task`, `merge`, `reload`,
`events`, …) is the one you can run yourself.

**The website and docs.** A Next.js marketing site and a contentlayer-backed
MDX documentation set (Getting Started, Concepts, and a CLI reference for every
`shelbi` subcommand) ship alongside the release.

Install from source with `./scripts/install.sh` (builds `--release`, drops the
binary at `$HOME/bin/shelbi`, ad-hoc re-signs on macOS).