Observability commands

These commands use physics-inspired names (nucleate, evolve, decay, spore, …). New to the vocabulary? See The physics vocabulary.

cs peek

Peek — canonical fleet observation command (TUI default; --no-tui for plaintext stream)

The context gauge uses the latest reported turn's input over the model window. Unknown occupancy has no percentage; token columns stay cumulative.

Usage: cs peek [OPTIONS]

EXAMPLES: cs peek # TUI over the current .cosmon/ cs peek --phase done,failed # + the archive; project scope unchanged cs peek --phase harvestable # the harvest queue: finished work still # owed a cs done (completed, unarchived) cs peek --all-galaxies # same phases, every .cosmon/ + tmux socket cs peek --all # sugar for --all-galaxies --phase all cs peek --no-tui # plaintext event stream cs peek --snapshot # byte-deterministic 120-col canonical view cs peek --snapshot > /tmp/a # capture from any device, then diff two # captures and expect zero bytes (see # docs/guides/peek-snapshot.md)

The context gauge uses the latest reported turn's input tokens over the model window. An unknown turn or window shows no percentage; IN/CACHED/OUT/RSN remain cumulative session counters. Snapshot follows the same rule. JSON keeps its existing cumulative usage schema and exposes no context percentage.

The selected dependent's blocked-by detail names a collapsed or frozen blocker and the operator gesture that can release or replace the edge.

Keys in the TUI: j/k navigate, p tmux pane capture, b/l/e/s/r/n/g briefing/log/events/synthesis/responses/notes/git tabs.

Options:

• --no-tui — Disable the TUI and render plaintext events to stdout. Required until the Phase 1 ratatui TUI lands

• --once — Run a single poll + diff + propel pass and exit. Implies --no-tui

• --follow — Follow the event stream until interrupted (the default for --no-tui when --once is not set)

• --stale-after <STALE_AFTER> — Staleness threshold in seconds, passed to the propel pass

  Default value: 300

• --poll-ms <POLL_MS> — State poll cadence in milliseconds

  Default value: 1000

• --propel-every <PROPEL_EVERY> — Propel nudge cadence in seconds. Defaults to min(60, stale_after/5)

• --no-tmux — Disable tmux propulsion. State is still read and diffed, but no nudges are sent

• --all — Sugar for --all-galaxies --phase all, and exactly that. Both axes at their widest: every project AND every phase, archive included. --all means all, literally; it never narrows. Conflicts with the two flags it expands to — sugar and its expansion are one way of saying one thing, not two ways of saying it twice. See docs/guides/peek-temporalities.md

• --all-galaxies — Perimeter axis: scan every project under $COSMON_CLUSTER_ROOT instead of the current one. Opt-in — cross-project reach is never implicit. Says nothing about which phases you see. Same spelling as cs tail --all-galaxies: one word, one meaning, across the binary. In TUI mode the a key toggles this at runtime

• --phase <PHASE> — Temporality axis: which phases to surface. Repeatable and comma-separated; the values union. Says nothing about the perimeter. Defaults to unfinished — every molecule whose story is not over. --phase unfinished,done,failed is what --past used to mean; --phase harvestable is the harvest queue — finished work still owed a cs done. In TUI mode the A key cycles this at runtime

  Possible values:

  • live: A worker is on it right now
  • waiting: Nucleated, not yet started
  • blocked: An external authority is refusing service (ADR-062)
  • parked: Frozen by an operator gesture; one cs thaw from running
  • failed: Collapsed
  • done: Completed — the whole archive, harvested or not
  • harvestable: The harvest queue: completed and not yet archived, i.e. still owed a cs done. A strict subset of done
  • unfinished: Every phase whose story is not over — the default view
  • all: Every phase, archive included. All of this axis, and only this axis: it does not touch the perimeter

• --energy-tick-interval <ENERGY_TICK_INTERVAL> — Cadence in seconds for emitting UsageObserved events into events.jsonl. Zero disables emission. Only active in --no-tui mode

  Default value: 30

• --snapshot — Emit a byte-deterministic, fixed-width (120-col) ASCII snapshot of the fleet and exit. The same fleet state produces byte-identical output across every device — iPhone SSH, iPad Blink, MacBook, tmux pane — so a PR reviewer can diff two captures and expect zero differences. Implies --no-tui and disables propulsion; no clock or environment ($COLUMNS, $TERM) affects the output

cs tail

Tail — live notify-driven reader over events.jsonl (fleet or --all-galaxies)

Usage: cs tail [OPTIONS]

EXAMPLES: cs tail # live tail of the current galaxy events.jsonl cs tail --all-galaxies # multiplex all known galaxies

Live notify-driven reader over events.jsonl. Default scope is the current fleet; --all-galaxies multiplexes across the registered cosmon roots.

SEE ALSO: cs events (one-shot dump), cs ensemble (snapshot view).

Options:

• --all-galaxies — Scan every project under $COSMON_CLUSTER_ROOT. Opt-in — cross-project reach is never implicit

• -f, --follow — Stay attached and stream new events via notify

• --since <SINCE> — Only show events at or after this timestamp. Accepts ISO-8601 (2026-04-24T12:00:00Z) or relative (-5m, -1h, -2d). allow_hyphen_values lets the relative form be written without --since=

• --kind <KIND> — Only show events whose type tag matches (e.g. molecule_nucleated)

• -n, --tail <TAIL> — Number of most-recent lines to print before follow (like tail -n)

  Default value: 20

• --cluster-root <CLUSTER_ROOT> — Override the cluster root used by --all-galaxies

cs errors

Errors — aggregate molecule-collapse events into one failure overview: what is breaking the fleet, and which molecules are hit

Usage: cs errors [OPTIONS]

Options:

• --since <SINCE> — Time window — accepts a relative duration (<N>d, <N>h, <N>m, <N>s) or an RFC-3339 absolute timestamp. Defaults to 7 days

  Default value: 7d

• --kind <VARIANT> — Filter to one CollapseReason variant. Accepts the on-wire strings: worker_crashed, gate_failed, blocker_stuck, manual_abort, resource_exhausted. Any other value is treated as a substring match on the free-form Other payload

• --reason <TEXT> — Substring match on the free-form reason text. Case-sensitive

• --top <TOP> — Maximum number of variant rows to display in the summary

  Default value: 10

• --ops-dir <OPS_DIR> — Path to the state store root (overrides walk-up discovery)

• --json — Emit JSON instead of the tabular summary. The global --json flag also enables this

cs health

Health — read-only molecule-health anomaly catalog, federation-wide (ADR-137 §7)

Usage: cs health [OPTIONS]

EXAMPLES: cs health # read-only anomaly catalog, current galaxy cs health --all # every project below the configured root cs health --json # NDJSON: one header line, one line per finding cs health --no-tmux # state-only (skip the tmux liveness probe)

The Witness (ADR-137 Phase 1): a zero-mutation, control-plane-only scan that surfaces the molecule-health anomaly catalog (A1 unsent-paste, A3 auth-dead, A4 idle-after-complete, A5 idle-running-zombie, A6 overloaded, A7 ghost-merge, A8 completed-unharvested, A9 crash-zombie) the way cs peek surfaces fleet state. Every signal is read from the state machine — molecule status, liveness lease, transport probe — NEVER from a pane glyph (the be1e use/mention guard). It heals nothing; the remedies it prints are advisory. Exit code: 0 all-healthy, 1 findings present (CI/monitor-friendly).

Options:

• --all — Scan every .cosmon/state/ below the configured cluster root, the way cs peek --all aggregates. Without it, only the current galaxy's state store is scanned
• --no-tmux — Skip the tmux liveness probe (state-only mode, for tests / headless). Session liveness is reported as unknown, so session-dependent classes (A1/A4/A5/A9) are conservatively not flagged

cs pulse

Pulse — runtime-vitality reading: RPM tachometer, six-voyant strip (ADR-138 P1)

Usage: cs pulse [OPTIONS]

EXAMPLES: cs pulse # runtime-vitality: RPM tachometer + six voyants cs pulse --window 10m # widen observation window (default 5m) cs pulse --json # cosmon.pulse/v1 NDJSON line (CI/scripting)

Pulse (ADR-138 Phase 1): a zero-mutation, stateless projection of fleet liveness onto a single tachometer headline + six-voyant strip.

Headline: RPM = dΦ/dt = completions/min in the observation window W. The event log is the pre-integrated derivative — no stored Φ, no new state store (IFBDD). A word replaces the number when magnitude lies: SPINNING — tokens burn, Φ flat (P==0, B>b_min) → RED DRAINAGE OFF — no forward tick in τ → RED

Traffic light (first-match wins): RED — subsystem dead (H_sched>τ) OR fuel exhausted OR spinning AMBER — stalled (P==0, L>0, ¬dead) OR starved molecules present GREEN — doing work (P>0) OR quiescent (L==0)

Voyant strip: scheduler / drainage / propel / heal / fuel / workers A dead subsystem serializes 'off' (red-class) — never silently absent.

Exit code: always 0 (read-only, non-blocking — callers use --json state).

Options:

• --window <WINDOW> — Observation window — accepts <N>d / <N>h / <N>m / <N>s. Defaults to 5 minutes (5m)

  Default value: 5m

• --sched-tau <SCHED_TAU> — Scheduler-dead threshold — age beyond which H_sched triggers RED. Defaults to 10 minutes (10m)

  Default value: 10m

• --sched-log <SCHED_LOG> — Path to the launchd-scheduler heartbeat log.

  Defaults to ~/.cosmon/scheduler.state.json.events.jsonl (derived from the scheduler state file by appending .events.jsonl).

  Override with COSMON_SCHED_LOG env var or this flag for testability or non-standard launchd setups.

• --sched-state <SCHED_STATE> — Path to scheduler.state.json.

  The drainage, propel, and heal voyants read patrols.<name>.last_fired_at from this file — the authoritative per-patrol fire time written by the scheduler on every dispatch, regardless of what the patrol command does.

  Defaults to ~/.cosmon/scheduler.state.json. Override with COSMON_SCHED_STATE env var or this flag for testability.

• --json — Emit the aggregate as a single cosmon.pulse/v1 NDJSON line. The global --json flag also enables this

• --swiftbar — Emit SwiftBar/BitBar formatted output for the macOS menubar plugin.

  First line = menubar face (colored dot + headline + SwiftBar params). Below ---: the six voyant lines, fuel%, scanned, separator, action items. Consumed by menubar/cosmon-pulse.10s.sh which execs cs pulse --swiftbar. See ADR-068: cs pulse --swiftbar is the UI surface for cs pulse.

cs doctor

Doctor — diagnostic probes (whisper channel, …)

Usage: cs doctor <COMMAND>

Subcommands:

• whisper — Probe the whisper channel of a molecule's assigned worker
• leaks — Scan tracked files for leaked secrets and non-public state (blocking)
• worktrees — Audit .worktrees/ for perm/symlink/untracked hazards
• mcp — Audit MCP servers registered in the configured service registry
• deps — Flag unpinned or mutable dependency declarations
• gitignore — Check that .cosmon/.gitignore tracks the archive it claims to
• supervision — Detect binaries supervised by both cosmon and a LaunchAgent
• security — Run every security probe and aggregate findings

cs doctor whisper

Probe the whisper channel of a molecule's assigned worker

Usage: cs doctor whisper <MOLECULE_ID>

Arguments:

• <MOLECULE_ID> — Molecule ID (full or unambiguous prefix)

cs doctor leaks

Scan tracked files for leaked secrets and non-public state (blocking)

Usage: cs doctor leaks [OPTIONS]

Options:

• --path <PATH> — Limit scanning to this subdirectory (relative to repo root)
• --include-untracked — Also scan untracked working-tree files (use when pre-commit check)
• --corpus <FILE> — Byte-literal patterns, one per line (UTF-8, # comments)

cs doctor worktrees

Audit .worktrees/ for perm/symlink/untracked hazards

Usage: cs doctor worktrees [OPTIONS]

Options:

• --root <ROOT> — Override the project root (default: git top-level)

cs doctor mcp

Audit MCP servers registered in the configured service registry

Usage: cs doctor mcp [OPTIONS]

Options:

• --registry <REGISTRY> — Override the path to the service registry database.

  Defaults to the platform data dir used by the service registry.

cs doctor deps

Flag unpinned or mutable dependency declarations

Usage: cs doctor deps [OPTIONS]

Options:

• --root <ROOT> — Override the workspace root

cs doctor gitignore

Check that .cosmon/.gitignore tracks the archive it claims to

Usage: cs doctor gitignore [OPTIONS]

Options:

• --root <ROOT> — Override the galaxy root (the directory containing .cosmon/)

cs doctor supervision

Detect binaries supervised by both cosmon and a LaunchAgent

Usage: cs doctor supervision [OPTIONS]

Options:

• --patrols <PATROLS> — Override the patrols config (~/.config/cosmon/patrols.toml)
• --daemons <DAEMONS> — Override the daemons config (~/.config/cosmon/daemons.toml)
• --launch-agents-dir <LAUNCH_AGENTS_DIR> — Override the LaunchAgents directory to scan

cs doctor security

Run every security probe and aggregate findings

Usage: cs doctor security [OPTIONS]

Options:

• --root <ROOT> — Override the workspace/git root
• --registry <REGISTRY> — Override the path to the service registry database
• --include-untracked — Also include untracked files in the leak scan