shelbi events

View as markdown

shelbi events <SUBCOMMAND> [OPTIONS]

shelbi events exposes ~/.shelbi/events.log, the append-only log of every column transition and workspace state change across the hub. The orchestrator follows it as its trigger stream. To see what the orchestrator is seeing, run events tail --follow in another pane.

The most common line shapes are:

<ts> project=<p> task=<id> workflow=<name> <from> -> <to> reason=<r> from_category=<c> to_category=<c>
<ts> project=<p> workspace=<name> <prev> -> <new>
<ts> project=<name> heartbeat

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.

Every subcommand accepts the global -p / --project <PROJECT> flag.

tail

shelbi events tail [OPTIONS]

Print recent transitions, and optionally stream new ones as they're appended. Useful for live debugging, for orchestrator bootstrap (--follow in the background and watch 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 (e.g. `10m`, `2h`, `1d`)	—	Only show events newer than this. When set, `-n` is ignored and all matching lines print.
`-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 with `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 tail

Follow the log live, the same thing the orchestrator does on bootstrap:

shelbi events tail --follow

Print everything from the last two hours, no live tail:

shelbi events tail --since 2h

Combine a longer history with a live follow:

shelbi events tail --lines 100 --follow

tail

Examples

See also