Genie provides seven command groups for observability: events for the audit log, sessions for Claude Code session history, metrics for machine state, schedule for cron triggers, qa for self-testing, log for a unified real-time feed, and brief for session startup context.
The genie events command group queries the PostgreSQL audit event log. Events are structured as OTel-compatible records covering API costs, tool usage, task transitions, and errors.Thirteen subcommands group into three layers: reading (list, errors, costs, tools, timeline, timeline-v2, summary, scan), streaming (stream, stream-follow, subscribe), and operations (migrate, admin). Reading commands hit the table directly; streaming commands tail events in real time (with stream-follow and subscribe targeting the v2 enriched surface); operations commands are one-shot migrations and sentinel-audited incident response.
Stream audit + runtime events in real-time (tail -f style). Reach for this when you want a live firehose across both the legacy audit_events and the enriched genie_runtime_events surfaces — for example, while watching a wish execute or debugging a noisy agent.
genie events stream [options]
Option
Description
--type <type>
Filter by event_type
--entity <entity>
Filter by entity type or entity ID
--errors-only
Show only error events
--kind <kind>
Filter runtime events by kind (tool_call, message, prompt, etc.)
--agent <agent>
Filter runtime events by agent
--audit-only
Stream only audit_events (skip runtime)
--runtime-only
Stream only runtime events (skip audit)
--all
Show all events including noisy ones (command_success, etc.)
Follow-stream enriched genie_runtime_events via PostgreSQL LISTEN/NOTIFY with an id-cursor for resumable consumption (v2). Unlike stream, this command is built for long-running sidecars that need to survive reconnects — pass --consumer-id and it picks up where it left off.The --kind flag accepts * globs for subject-tree subscriptions. For example, --kind 'detector.*' follows every event emitted by the detector subsystem. See Detectors for the catalog of kinds (sibling PR — page lands alongside this one).
genie events stream-follow [options]
Option
Description
--follow
Continuously follow the stream (default: true)
--kind <prefix>
Filter by subject/kind prefix — supports * globs (e.g., detector.*)
--severity <level>
Filter by severity (debug|info|warn|error|fatal)
--since <duration>
Seed window (e.g., 5m, 1h)
--consumer-id <id>
Persistent consumer id for cursor resume
--json
Output as NDJSON
# Follow all detector events at warn-or-higher severitygenie events stream-follow --kind 'detector.*' --severity warn# Resume from a previous cursor under a stable consumer idgenie events stream-follow --consumer-id sentinel-ingest --since 5m --json
Mint a signed subscription token for genie events stream --follow. Tokens carry an RBAC role and optional restrictions on event types, LISTEN channels, TTL, and tenant — letting subscriber agents connect without sharing long-lived credentials.
subscribe requires a running scheduler/issuer with HMAC keys configured. The --types and --channels flags narrow (never widen) the role’s default permissions.
Treat genie events errors as an incident-response tool. A sudden spike in an error pattern usually means a provider outage, a credential rotation, or a broken agent — investigate before spawning more work on top.
Every genie events subcommand supports --json. Pipe into jq for ad-hoc analysis — e.g., genie events costs --since 7d --by-model --json | jq '.[] | select(.usd > 1)' surfaces only models that cost more than $1 in the last week.
Render a causal tree for a trace_id from the enriched genie_runtime_events surface. Unlike timeline, which walks any entity type, timeline-v2 expects a trace id and reconstructs spans with OTel-style parent/child relationships — use it when chasing causality across agent/tool boundaries.
Backfill legacy audit_events rows into genie_runtime_events as a one-shot migration. Useful when adopting the v2 enriched surface on an existing installation or recovering from a gap in the ingestion pipeline.
Run with --dry-run first to inspect row deltas; re-run without --dry-run to commit.
genie events migrate [options]
Option
Description
--audit
Migrate audit_events → genie_runtime_events with sentinel source tag
“Enriched” refers to the genie_runtime_events table — a v2 superset of the legacy audit_events stream that adds OTel-style columns (trace_id, span_id, severity, duration_ms) plus a hierarchical kind taxonomy. It has no dedicated subcommand; instead, the enriched surface is reached via:
genie events list --v2 — table listing with enriched columns and --kind/--severity filters
The genie log command provides a unified observability feed that aggregates transcripts, DMs, team chat, tool calls, and system events into a single stream.
Filter by event kind: transcript, message, tool_call, state, system
--since <timestamp>
Only events after ISO timestamp
--last <n>
Show last N events
--ndjson
Output as newline-delimited JSON (pipeable to jq)
--json
Output as pretty JSON
-f, --follow
Follow mode — real-time streaming
# Follow an agent's live feedgenie log engineer -f# Show last 20 events for the whole teamgenie log --team auth-rewrite --last 20# Stream tool calls as NDJSONgenie log engineer --type tool_call --ndjson -f
genie brief shows an aggregated startup brief with context since the last session — useful for agents resuming work or operators reviewing what happened overnight.
# Show brief for the current agentgenie brief# Show brief for a specific team since midnightgenie brief --team auth-rewrite --since 2026-03-30T00:00:00Z
