shelbi events
View as markdownshelbi events <SUBCOMMAND> [OPTIONS]shelbi events exposes ~/.shelbi/events.log, the append-only log of task
transitions, workspace state changes, heartbeats, and hub operations (dispatch,
merge, forward health) across the hub. The orchestrator mirrors it with
events tail --follow --project <name> as a low-latency wake-up; its
authoritative feed is the durable
shelbi orchestrator events queue. To see what the
orchestrator is seeing, run events tail --follow --project <name> in another
terminal.
The most common line shapes are:
<ts> project=<p> task=<id> workflow=<name> <from> -> <to> reason=<r> from_category=<c> to_category=<c> [owner=<who>]
<ts> project=<p> workspace=<name> <prev> -> <new>
<ts> project=<name> heartbeat zen=<on|off> zen_eligible=<n> idle_workspaces=<n>Hub operations add their own shapes, such as dispatch project=<p> task=<id> …, merge task=<id> …, and ssh reverse-forward host=<h> ….
The token is workspace=, not worker= (a retired pre-rename alias). On the
first workspace transition <prev> is none.
heartbeat is the periodic wake-up the hub poller writes. Its cadence is
adaptive: the standard interval runs whenever there is supervisable work in
flight, and the poller backs off (doubling toward the max) while the board is
quiescent. Cadence comes from the heartbeat key in project.yaml (default
interval 60s, backing off toward a 5m cap). See
the events log for the full
shape catalog.
events tail is hub-global by default. Pass --project <name> (long form
only; -p isn't accepted here, and $SHELBI_PROJECT is ignored) to scope it to
one project.
tail
shelbi events tail [OPTIONS]Print recent transitions, and optionally stream new ones as they're
appended. Useful for live debugging, as the orchestrator's low-latency
wake-up (--follow --project <name> in the background, watched with
Monitor), and for post-hoc forensics (--since 1h to scope to a window).
| Flag | Type | Default | Description |
|---|---|---|---|
-n, --lines <LINES> | integer | 20 | Number of trailing lines to print before following (or before exiting if --follow is not set). |
--since <SINCE> | duration: <n>s, <n>m, <n>h, <n>d, or bare seconds | — | Only show events newer than this. When set, -n is ignored and all matching lines print. Lines whose timestamp doesn't parse are kept. |
--project <PROJECT> | string | all projects | Only show lines with project=<PROJECT>. Lines without a project= token (such as merge task=… and ssh reverse-forward …) are dropped. -n and --since count the project's own lines. Non-consuming: safe to run alongside shelbi orchestrator events next. |
-f, --follow | flag | off | Stream new transitions as they're appended. Exit on Ctrl-C. |
--format <FORMAT> | raw, envelope | raw | Print historical log lines, or a normalized JSON envelope (version, transport, kind, project, timestamp, and the original line). Push-capable harness callbacks use this same envelope. |
Shelbi only transports events. Whether a harness wakes the orchestrator through
Claude-style Monitor output, a callback socket, or the pre-turn drain path, the
orchestrator remains responsible for deciding what action to take.
Examples
See the last twenty transitions:
shelbi events tailFollow one project's lines live, the same accelerator the orchestrator starts on bootstrap:
shelbi events tail --follow --project myappPrint everything from the last two hours, no live tail:
shelbi events tail --since 2hCombine a longer history with a live follow:
shelbi events tail --lines 100 --followSee also
- Events log — the full schema of both line kinds and which reason tags the orchestrator recognizes.
- Orchestrator — how the scheduler turns events into dispatch decisions.
shelbi orchestrator events: the durable, consuming event queue the orchestrator drains and acks.