Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tools commands

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

cs pilot

Pilot — interactive cognitive pilot REPL over a client-side model (--experimental). --remote pilots an avatar over the §8p wire (ADR-115)

Usage: cs pilot [OPTIONS]

Options:
  • --experimental — Enable the experimental verb. While the interactive loop matures, cs pilot without this flag prints a safety notice and does nothing — no REPL, no model call, no side effects (mirrors cs ask, ADR-071)
  • --model <TAG> — Ollama model tag to drive the loop (default: llama3.2). Falls back to the COSMON_PILOT_MODEL environment variable when the flag is omitted
  • --base-url <URL> — Override the model endpoint (default: the local Ollama OpenAI-compatible endpoint http://localhost:11434/v1). Falls back to COSMON_PILOT_BASE_URL when the flag is omitted
  • --transcript <PATH> — Path the on-disk transcript is appended to (default: pilot-transcript.md in the current directory). Falls back to COSMON_PILOT_TRANSCRIPT when the flag is omitted
  • --timeout <SECS> — Per-request timeout in seconds for each model round-trip (default: 300). The pilot defaults far above the provider's 60s library default because it injects the full repo CLAUDE.md (~36 KB) as bootstrap context, so a large local model (e.g. qwen2.5:32b) legitimately spends minutes on the first prefill. Falls back to COSMON_PILOT_TIMEOUT (also in seconds) when the flag is omitted
  • --remote — Pilot a REMOTE avatar over the network instead of the local cosmon instance (ADR-115 §6). The model still runs client-side (this box); only cosmon operations cross the wire, via the avatar's cosmon-rpp-adapter §8p routes (ADR-080). Read-only unless --write
  • --profile <NAME> — Which cosmon-remote profile to use in --remote mode (the avatar's host + JWT identity). Defaults to the configured default profile (~/.config/cosmon-remote/). Ignored without --remote
  • --write — In --remote mode, expose the write tools (nucleate / tackle) in addition to the read tools. Off by default — a remote session sees the fleet but cannot change it unless asked. done / evolve are never available regardless (ADR-080 §5). Ignored without --remote

cs prime

Prime the system — load .cosmon/config.toml and self-check gates

Usage: cs prime [OPTIONS] [MOLECULE]

EXAMPLES: cs prime # load .cosmon/config.toml, report gates

Boot-time self-check. No network calls; verifies the local project is well-formed.

Arguments:
  • <MOLECULE> — Molecule ID to prime (optional — auto-detects from running molecule)
Options:
  • --hook — Check hook and prime if work is assigned

cs paths

Paths — project the write-path taxonomy (--writes), a pure derived view

Usage: cs paths [OPTIONS]

Options:

  • --writes — Emit the set of paths cosmon writes under the state root.

    Currently the only projection mode; the flag is explicit so future projections (e.g. --reads) can be added without changing the default behaviour. Omitting it is equivalent to passing it.

cs archive

Archive — operator view over durable terminal snapshots (list/show/verify/prune, ADR-030)

Usage: cs archive <COMMAND>

EXAMPLES: cs archive list # every archived molecule, all months cs archive list --year 2026 # scoped to one year cs archive list --year 2026 --month 04 # scoped to one month cs archive list --json # NDJSON for scripting cs archive show # manifest + artifact inventory cs archive verify # recompute hashes (exit 1 if tampered) cs archive prune --dry-run # what retention policy would delete cs archive prune # execute the retention policy

Operator view onto .cosmon/state/archive/. Terminal transitions (cs done / cs collapse / cs freeze / cs stuck) populate the archive when [archive] enabled = true in the project config — the default since 2026-09; set enabled = false to opt out. Enabling is not retroactive. The archive outlives worktree teardown and branch deletion — a fresh clone sees every merged molecule's canonical snapshot. If entries never reach git status, run cs doctor gitignore.

Retention is controlled by [archive.retention] in config.toml: keep_all (default true) — safety switch; must be false to delete max_age_days (default 0) — 0 disables the age rule max_total_mb (default 0) — 0 disables the size rule keep_kinds (default decision, deliberation)

Hash-chain integrity is enforced: a molecule referenced as parent (DecayedFrom / BlockedBy / MergedFrom) by a kept entry is never deleted.

Subcommands:
  • list — List archived molecules (optionally filtered by year / month)
  • show — Show the manifest + artifact inventory for one archived molecule
  • verify — Verify artifact hashes — exits non-zero if tampered
  • prune — Apply the [archive.retention] policy; --dry-run shows the plan

cs archive list

List archived molecules (optionally filtered by year / month)

Usage: cs archive list [OPTIONS]

Options:
  • --year <YYYY> — Restrict the scan to a single year (e.g. 2026)
  • --month <MM> — Restrict the scan to a single month (01..=12). Must be used with --year to be meaningful; standalone --month still filters across whichever years contain that month
  • --since-days <N> — Keep only entries whose directory was modified within the last N days. 0 means no limit. Combines with --year/--month. Used by the CI gate (.github/workflows/archive-verify.yml)
  • --ids-only — Emit one molecule id per line, skipping the table header / JSON envelope. Intended for shell pipelines (xargs cs archive verify)

cs archive show

Show the manifest + artifact inventory for one archived molecule

Usage: cs archive show <MOLECULE>

Arguments:
  • <MOLECULE> — Molecule id or unique prefix

cs archive verify

Verify artifact hashes — exits non-zero if tampered

Usage: cs archive verify <MOLECULE>

Arguments:
  • <MOLECULE> — Molecule id or unique prefix

cs archive prune

Apply the [archive.retention] policy; --dry-run shows the plan

Usage: cs archive prune [OPTIONS]

Options:
  • --dry-run — Show what would be deleted and exit — never touch disk

cs journal

Write down what you notice while you work; anything worth doing becomes a task without you stopping to file it

Usage: cs journal <COMMAND>

EXAMPLES: cs journal start # open a carnet cs journal start --galaxy example --root delib-example-0001 cs journal note "Torvalds elected path a" cs journal note --tag insight "the carnet is the primitive" cs journal note "!spark implémenter session-to-spark" # prefix auto-promotes cs journal end # seal with BLAKE3 + auto-commit cs journal end --no-seal # ephemeral scratch close

PROMOTE — turn journal notes into spark molecules: cs journal promote 10:46:55 # promote one note by timestamp cs journal promote 10:46:55 10:47:01 # promote several cs journal promote --all-spark-prefix # promote every !spark-prefixed note cs journal promote --dry-run # show what would be promoted cs journal promote --session session-2026-04-22T10-31-31Z 10:46:55

Notes beginning with !spark are automatically promoted by the session-to-spark LaunchAgent (when installed, fires every 5 min). Explicit cs journal promote <ts> works regardless of prefix and is idempotent — sidecar markers under .cosmon/state/journals/.promoted/ prevent duplicate sparks.

Exit codes: 2 a session is already open (on cs journal start) 3 no open session (on cs journal note / cs journal end)

Journals live under .cosmon/state/journals/ as append-only markdown files. The seal is a BLAKE3 hash of the body between the frontmatter and footer — a trace, not a lock (architectural-invariants.md §8b). Promotion never mutates a sealed journal — markers are sidecar-only.

Subcommands:
  • start — Open a journal — every note you take lands in it until you end it
  • note — Append a timestamped note to the open journal
  • end — Close the open journal, optionally sealing it with BLAKE3
  • promote — Turn journal notes into spark molecules (via the session-to-spark tick)
  • route — Route journal notes through the Tier-1 regex classifier (ADR-072)
  • review — Review router-staged molecules (verdict-door)

cs journal start

Open a journal — every note you take lands in it until you end it

Usage: cs journal start [OPTIONS]

Options:
  • --galaxy <GALAXY> — Galaxy this session belongs to (free-form label)
  • --root <MOL_ID> — Root molecule(s) this session is anchored on (repeatable)

cs journal note

Append a timestamped note to the open journal

Usage: cs journal note [OPTIONS] <TEXT>

Arguments:
  • <TEXT> — Free-form note body
Options:
  • --tag <TAG> — Optional tag rendered alongside the timestamp (e.g. insight, todo)
  • --cause-kind <KIND> — How the note was produced. One of direct (human typed), transcription (human spoke, agent transcribed), oracle-suggestion (agent proposed, human accepted), autonomous (agent authored alone). Omit to skip the cause: subline entirely — the note renders in the pre-schema format. Supplying any --cause-* flag enables the subline with defaults kind=direct, agent=null, channel=keyboard
  • --cause-agent <AGENT> — Identity of the mediating agent (e.g. apfel-oracle-<host>, matrix:@tenant_auditor:hs). Leave unset when --cause-kind direct
  • --cause-channel <CHANNEL> — Physical channel the note arrived on. Known variants: keyboard, voice, matrix, webhook. Any other value is accepted verbatim and round-trips as Other(<value>)

cs journal end

Close the open journal, optionally sealing it with BLAKE3

Usage: cs journal end [OPTIONS]

Options:
  • --no-seal — Skip the BLAKE3 seal — ephemeral scratch close. By default the session body is sealed (mirrors prompt_seal / briefing_seals)

cs journal promote

Turn journal notes into spark molecules (via the session-to-spark tick)

Usage: cs journal promote [OPTIONS] [NOTE_TIMESTAMPS]...

Arguments:

  • <NOTE_TIMESTAMPS> — Note timestamp to promote (HH:MM:SS, optionally prefixed by <session_id>@ to disambiguate across sessions). Repeatable.

    When omitted, behaviour depends on --all-spark-prefix (default: on) and --dry-run.

Options:
  • --session <SESSION> — Session file stem (e.g. session-2026-04-22T10-31-31Z) or an absolute path. Defaults to the currently open session; if no session is open, defaults to scanning every session file
  • --all-spark-prefix — Promote every note whose body begins with !spark . Default behaviour when no explicit timestamps are passed; when timestamps ARE passed, this is additive (promote both the prefixed notes and the explicit ones)
  • --dry-run — Print what would be promoted without nucleating or writing sidecars. Forwarded to the tick script
  • --tick-script <PATH> — Override the tick script location. Defaults to walk-up discovery from $PWD looking for scripts/session-to-spark-tick.sh

cs journal route

Route journal notes through the Tier-1 regex classifier (ADR-072).

Walks a journal file, computes blake3(body) for each note, applies the Tier-1 cascade, writes a sidecar under .cosmon/state/journals/.route/<sid>/<body_hash>.json, and (when confidence warrants) nucleates a temp:proposed molecule via cs nucleate. Tiers 2–4 are future work; low-confidence notes are marked tier4_pending and escalate to the verdict-door.

Usage: cs journal route [OPTIONS] [SESSION]

Arguments:
  • <SESSION> — Session file stem (e.g. session-2026-04-22T10-31-31Z) or an absolute path. When omitted, defaults to scanning every session file if --all is passed, or the currently-open session otherwise
Options:

  • --all — Process every session file under .cosmon/state/journals/

  • --dry-run — Print what would be classified without writing sidecars or nucleating molecules

  • --no-stage — Skip auto-nucleation of high-confidence temp:proposed molecules — write sidecars only. Useful when backfilling or debugging

  • --max <MAX> — Cap sidecars emitted this run (safety net for batch backfills)

    Default value: 500

cs journal review

Review router-staged molecules (verdict-door).

Renders temp:proposed molecules as a markdown review file at .cosmon/state/journals/.review/<sid>.md, opens it in $EDITOR, and — on --apply — translates each verdict: line into a keep / dismiss / undo transition. Silent when nothing is pending (no editor opens). See ADR-072 §7.

Usage: cs journal review [OPTIONS] [SESSION]

Arguments:
  • <SESSION> — Session id (e.g. session-2026-04-22T10-31-31Z). When omitted, review every session that has pending staged molecules
Options:
  • --apply — Parse the previously-composed review file and apply the verdicts. Without this flag, the verb composes the markdown review file and opens it in $EDITOR
  • --editor <CMD> — Override the editor (defaults to $EDITOR, then vi). Ignored with --apply and with --json

cs sessions

Two agent sessions — a Claude and a Codex, or two of either — work the same mission on this machine. One holds the controls and may change the mission; the other reads the same material, compares, and advises, and can change nothing. Both see each other, can write to each other, and leave a hand-over note when they stop, so the next session resumes without re-reading the whole conversation.

Passing the controls is never automatic. A session may ASK for them; only you, the human, hand them over, by signing the request with your key. No quota, timeout or heuristic moves them.

The verbs come in the order you meet them: find a session (discover, show), take a seat (attach, list, peers), talk (send, inbox), hand over (checkpoint, drift, takeover). hook wires the routine ones into the agent itself, so they happen without being typed.

Both seats are live sessions of the SAME mission, and only a human signature moves the controls between them. For separate molecules — each with its own lifecycle, visible in cs peek and harvested on its own — exchanging bounded findings instead, see cs work (ADR-182).

Usage: cs sessions <COMMAND>

EXAMPLES: cs sessions discover # provider sessions in this repo cs sessions discover --all --provider codex # every Codex session on the host cs sessions show claude:4940f28e --tail 5 # one session, named exactly cs sessions attach --role copilot --follow claude-sid
--as codex:0198aabb --capability observe cs sessions list --role primary # who holds a seat cs sessions peers # who is around me, and which way cs sessions send --to claude-sid --message 'that evidence ref is circular' cs sessions inbox # read and consume; --peek to look

HAND-OVER: cs sessions checkpoint publish --mission task-20260731-e4d0
--include 'the cockpit' --exclude 'the probe'
--next 'merge-strategy:deny=do not merge before the doc gate'
--evidence 'merge-strategy=docs/adr/168.md' cs sessions checkpoint list --mission task-20260731-e4d0 cs sessions drift claude-sid codex-sid --mission task-20260731-e4d0 cs sessions takeover show --mission task-20260731-e4d0 cs sessions takeover trust # which key may seat a pilot cs sessions takeover request --mission task-20260731-e4d0 --reason 'quota'

THE OPERATOR GESTURE (the part an agent cannot type for itself): cs sessions takeover challenge --mission task-20260731-e4d0 --request req-… --by emmanuel > takeover.txt minisign -Sm takeover.txt # your passphrase, your gesture cs sessions takeover grant --mission task-20260731-e4d0 --request req-… --by emmanuel --attestation takeover.txt.minisig

--by is a label; the signature is the authority. A grant with no valid attestation seats nobody — including one appended straight into the ledger, because every line is checked when it is read. Pin the public key at .cosmon/takeover.pub and commit it, so a swapped trust root is a diff.

WITHOUT TYPING ANYTHING (the hook, mission M6): cs sessions hook install --provider claude # .claude/settings.local.json cs sessions hook install --provider codex # ~/.codex/config.toml notify cs sessions hook status # wired? and what has it cost cs sessions checkpoint stage --mission task-20260731-0d49
--next 'gate:affirm=run just gates before done' cs sessions hook uninstall --provider claude # leaves no residue COSMON_COPILOT_HOOK_OFF=1 # quiet now, still wired

The hook pings presence, drains the mailbox where the pilot can read it and publishes a staged checkpoint at a transition. It never claims a seat and never writes a checkpoint's content: a hand-over record is the pilot's own words, and only its moment is the hook's.

The canonical name of a session is <provider>:<native-session-id>, and nothing else ever breaks a tie: a title, a cwd and a modification time help you recognise a session, never choose one. A selector that matches zero or two sessions prints the candidates and refuses.

Exit codes (drift, matching cs diverge): 0 AGREE — the compared positions match 1 FINDING — a decidable test fired, both sides cited 2 INCONCLUSIVE — not comparable; never rendered as agreement

Authority is a lease with an epoch (ADR-168 §D6). A co-pilot may observe, message and checkpoint; only the operator grants the controls, and no quota reading transfers them.

SEE ALSO: cs presence (the substrate), cs journal (operator carnet), cs pilot (cognitive REPL), cs diverge.

Subcommands:
  • discover — Which agent conversations exist on this machine, and the exact name to refer to one by
  • list — Which of them have taken a seat, and in which role
  • show — Look inside one conversation — its last events, read-only
  • attach — Take a seat: say "I am here, in this role". Until you do, the others cannot see you
  • peers — Who is seated around this session, and which way each one faces
  • send — Write one message to another session. Delivered, and consumed, once
  • inbox — Read the messages addressed to this session (--peek to look without consuming them)
  • checkpoint — Leave — or read — the note that lets someone else resume this mission
  • drift — Compare what two sessions concluded — AGREE, FINDING or INCONCLUSIVE, never a score
  • takeover — The controls: who may change the mission, who asked for them, and the signature that hands them over
  • hook — Wire the routine gestures — take a seat, read the mailbox, leave a note — into the agent itself, so they happen without being typed

cs sessions discover

Which agent conversations exist on this machine, and the exact name to refer to one by

Usage: cs sessions discover [OPTIONS]

Options:
  • --repo <PATH> — Repository whose sessions to show. Defaults to the repository the current directory is in. Resolved to an exact checkout — a worktree is never its canonical checkout (REPO-EXACT)
  • --cwd <PATH> — Show sessions whose recorded working directory is exactly this path
  • --all — Show every session every adapter can see, from any repository
  • --provider <NAME> — Restrict to one provider (claude, codex, …)

cs sessions list

Which of them have taken a seat, and in which role

Usage: cs sessions list [OPTIONS]

Options:
  • --galaxy <GALAXY> — Filter to one galaxy
  • --role <ROLE> — Show only pilots in this seat (primary or copilot)
  • --follows <SID> — Show only pilots co-piloting this session
  • --all — Include snapshots whose heartbeat has gone stale

cs sessions show

Look inside one conversation — its last events, read-only

Usage: cs sessions show [OPTIONS] <SELECTOR>

Arguments:
  • <SELECTOR> — The canonical selector, <provider>:<native-session-id>
Options:

  • --tail <N> — Print the last N normalised events (kinds and sizes — never content)

    Default value: 0

  • --no-read — Skip reading the log; show only what discovery already knows

cs sessions attach

Take a seat: say "I am here, in this role". Until you do, the others cannot see you

Usage: cs sessions attach [OPTIONS]

Options:

  • --role <ROLE> — Seat to take: copilot (default) or primary. A primary seat is checked against the mission's lease ledger and refused if it is not this session's to take

    Default value: copilot

  • --follow <SID_OR_SELECTOR> — The pilot this session is co-piloting — a cosmon session id, or a <provider>:<native-session-id> selector that a live pilot advertises

  • --session <SID> — This session's cosmon id. Defaults to $COSMON_SESSION_ID

  • --as <SELECTOR> — The provider session this pilot is driving, as a canonical selector. Equivalent to --provider + --native-session-id

  • --provider <NAME> — Provider half of this session's key, when not using --as

  • --native-session-id <ID> — Native id half of this session's key, when not using --as

  • --mission <MOLECULE_ID> — Mission this seat is about. Required for a primary seat

  • --epoch <N> — The lease epoch this pilot believes it holds. Required for a primary seat: a claim that names no generation is not a claim

  • --capability <TOKEN> — A capability this pilot advertises. Repeatable

  • --headline <HEADLINE> — One line describing what this pilot is doing

  • --galaxy <GALAXY> — Galaxy label to record

    Default value: cosmon

cs sessions peers

Who is seated around this session, and which way each one faces

Usage: cs sessions peers [OPTIONS]

Options:
  • --session <SID> — The session whose neighbourhood to show. Defaults to $COSMON_SESSION_ID
  • --all — Include snapshots whose heartbeat has gone stale

cs sessions send

Write one message to another session. Delivered, and consumed, once

Usage: cs sessions send [OPTIONS] --to <SID_OR_SELECTOR> --message <TEXT>

Options:
  • --to <SID_OR_SELECTOR> — Destination — a cosmon session id, or a selector a live pilot advertises
  • --message <TEXT> — The message. Stored content-addressed; the envelope carries its hash
  • --from <SID> — Sender session id. Defaults to $COSMON_SESSION_ID
  • --expires-in <SECONDS> — Seconds after which an unread envelope reads as expired rather than as a fresh instruction

cs sessions inbox

Read the messages addressed to this session (--peek to look without consuming them)

Usage: cs sessions inbox [OPTIONS]

Options:

  • --session <SID> — Mailbox to read. Defaults to $COSMON_SESSION_ID

  • --peek — Show pending envelopes without acknowledging them

  • --all — Include already-acknowledged envelopes

  • --follow — Keep reading, printing each envelope as it arrives, until interrupted

  • --interval <SECONDS> — Seconds between polls under --follow

    Default value: 2

cs sessions checkpoint

Leave — or read — the note that lets someone else resume this mission

Usage: cs sessions checkpoint <COMMAND>

Subcommands:
  • publish — Publish this pilot's hand-over record for a mission
  • stage — Write the same record as a draft, for the hook to publish at the next natural transition. Takes exactly the flags publish takes
  • list — List the checkpoints published for a mission
  • show — Show one checkpoint in full

cs sessions checkpoint publish

Publish this pilot's hand-over record for a mission

Usage: cs sessions checkpoint publish [OPTIONS] --mission <MOLECULE_ID>

Options:
  • --mission <MOLECULE_ID> — The mission being flown
  • --session <SID> — Publishing session. Defaults to $COSMON_SESSION_ID
  • --epoch <N> — The authority epoch the publisher believes it is under. Defaults to the epoch on its own presence snapshot, then to 0
  • --id <ID> — Identifier for this checkpoint. Defaults to a timestamped id
  • --include <TEXT> — Something this mission covers. Repeatable
  • --exclude <TEXT> — Something this mission explicitly does not cover. Repeatable
  • --hypothesis <CLAIM> — A position currently held, as SUBJECT[:affirm|deny]=STATEMENT. Repeatable
  • --next <CLAIM> — An intended next move, in the same SUBJECT[:STANCE]=STATEMENT form. Repeatable — this is the list a co-pilot's contradiction is found in
  • --done <TEXT> — Something already done, in the pilot's words. Repeatable
  • --risk <TEXT> — A known risk. Repeatable
  • --question <TEXT> — A question the pilot could not answer. Repeatable — this is where uncertainty belongs, never inside a stance
  • --evidence <SUBJECT=LOCATOR> — Evidence for one claim, as SUBJECT=LOCATOR[#DIGEST]. Repeatable
  • --checkpoint-evidence <LOCATOR> — Evidence for the checkpoint as a whole, as LOCATOR[#DIGEST]. Repeatable

cs sessions checkpoint stage

Write the same record as a draft, for the hook to publish at the next natural transition. Takes exactly the flags publish takes

Usage: cs sessions checkpoint stage [OPTIONS] --mission <MOLECULE_ID>

Options:
  • --mission <MOLECULE_ID> — The mission being flown
  • --session <SID> — Publishing session. Defaults to $COSMON_SESSION_ID
  • --epoch <N> — The authority epoch the publisher believes it is under. Defaults to the epoch on its own presence snapshot, then to 0
  • --id <ID> — Identifier for this checkpoint. Defaults to a timestamped id
  • --include <TEXT> — Something this mission covers. Repeatable
  • --exclude <TEXT> — Something this mission explicitly does not cover. Repeatable
  • --hypothesis <CLAIM> — A position currently held, as SUBJECT[:affirm|deny]=STATEMENT. Repeatable
  • --next <CLAIM> — An intended next move, in the same SUBJECT[:STANCE]=STATEMENT form. Repeatable — this is the list a co-pilot's contradiction is found in
  • --done <TEXT> — Something already done, in the pilot's words. Repeatable
  • --risk <TEXT> — A known risk. Repeatable
  • --question <TEXT> — A question the pilot could not answer. Repeatable — this is where uncertainty belongs, never inside a stance
  • --evidence <SUBJECT=LOCATOR> — Evidence for one claim, as SUBJECT=LOCATOR[#DIGEST]. Repeatable
  • --checkpoint-evidence <LOCATOR> — Evidence for the checkpoint as a whole, as LOCATOR[#DIGEST]. Repeatable

cs sessions checkpoint list

List the checkpoints published for a mission

Usage: cs sessions checkpoint list [OPTIONS] --mission <MOLECULE_ID>

Options:
  • --mission <MOLECULE_ID> — The mission whose checkpoints to list
  • --session <SID> — Show only what this session published

cs sessions checkpoint show

Show one checkpoint in full

Usage: cs sessions checkpoint show [OPTIONS] --mission <MOLECULE_ID>

Options:
  • --mission <MOLECULE_ID> — The mission the checkpoint belongs to
  • --id <ID> — The checkpoint id. Omit to take the latest published by --session
  • --session <SID> — The publishing session, when selecting by recency rather than by id

cs sessions drift

Compare what two sessions concluded — AGREE, FINDING or INCONCLUSIVE, never a score

Usage: cs sessions drift [OPTIONS] --mission <MOLECULE_ID> <SESSION_A> <SESSION_B>

Arguments:
  • <SESSION_A> — The first session
  • <SESSION_B> — The second session
Options:

  • --mission <MOLECULE_ID> — The mission both sides checkpointed

  • --checkpoint <latest> — Which checkpoint of each session to compare. Only latest is a selector; name an exact record with --checkpoint-a / --checkpoint-b

    Default value: latest

  • --checkpoint-a <ID> — Exact checkpoint id for side A

  • --checkpoint-b <ID> — Exact checkpoint id for side B

cs sessions takeover

The controls: who may change the mission, who asked for them, and the signature that hands them over

Usage: cs sessions takeover <COMMAND>

Subcommands:
  • show — Who holds the controls, at which epoch, and what has been asked
  • request — Ask for the controls. Writes a request and confers nothing
  • grant — Hand the controls over — your signature, which no agent can produce
  • challenge — Print the exact bytes an operator signs to authorise one transfer
  • trust — Show which operator key this galaxy trusts to authorise a transfer
  • check — Ask whether a session may pilot: the ledger's verdict, plus whether its seat would actually present that epoch. Exits 0 or 1

cs sessions takeover show

Who holds the controls, at which epoch, and what has been asked

Usage: cs sessions takeover show [OPTIONS] --mission <MOLECULE_ID>

Options:
  • --mission <MOLECULE_ID> — Mission whose lease to inspect
  • --history — Print every grant ever recorded instead of only the head

cs sessions takeover request

Ask for the controls. Writes a request and confers nothing

Usage: cs sessions takeover request [OPTIONS] --mission <MOLECULE_ID>

Options:

  • --mission <MOLECULE_ID> — Mission the controls are being asked for

  • --to <SID> — Session that would become PRIMARY. Defaults to the requester

  • --from <SID> — Session doing the asking. Defaults to $COSMON_SESSION_ID

  • --reason <TEXT> — One line the operator reads before deciding

    Default value: ``

cs sessions takeover grant

Hand the controls over — your signature, which no agent can produce

Usage: cs sessions takeover grant [OPTIONS] --mission <MOLECULE_ID>

Options:
  • --mission <MOLECULE_ID> — Mission whose controls are being handed over
  • --request <REQUEST_ID> — Request being answered. The holder is taken from the request
  • --to <SID> — Session to seat, when granting without a request
  • --ttl <SECONDS> — Seconds after which the lease authorises nothing
  • --by <NAME> — Operator identity to record. Defaults to $USER. Covered by the attestation, so it is a signed claim and not a free string
  • --attestation <PATH> — The operator's detached minisign signature over the challenge, or - for stdin. Required: --by is a label, the signature is the gesture
  • --sign-with <PATH> — The operator's minisign secret key. Folds challenge, signature and grant into this one command: the transfer is printed for you to read, minisign(1) asks for your passphrase, and no .minisig is left behind. cosmon still owns no signer — it relays to yours

cs sessions takeover challenge

Print the exact bytes an operator signs to authorise one transfer

Usage: cs sessions takeover challenge [OPTIONS] --mission <MOLECULE_ID>

Options:
  • --mission <MOLECULE_ID> — Mission whose controls would be handed over
  • --request <REQUEST_ID> — Request being answered. The holder is taken from the request
  • --to <SID> — Session that would be seated, when there is no request to answer
  • --ttl <SECONDS> — Seconds after which the lease would authorise nothing
  • --by <NAME> — Operator identity the grant would claim. Defaults to $USER

cs sessions takeover trust

Show which operator key this galaxy trusts to authorise a transfer

Usage: cs sessions takeover trust

cs sessions takeover check

Ask whether a session may pilot: the ledger's verdict, plus whether its seat would actually present that epoch. Exits 0 or 1

Usage: cs sessions takeover check [OPTIONS] --mission <MOLECULE_ID>

Options:
  • --mission <MOLECULE_ID> — Mission the gesture would touch
  • --session <SID> — Session issuing the gesture. Defaults to $COSMON_SESSION_ID
  • --epoch <N> — The epoch the caller believes it holds. Omitting it is itself a refusal

cs sessions hook

Wire the routine gestures — take a seat, read the mailbox, leave a note — into the agent itself, so they happen without being typed

Usage: cs sessions hook <COMMAND>

Subcommands:
  • install — Wire this pilot's provider to run the co-pilotage hook
  • uninstall — Remove the co-pilotage hook, leaving the rest of the file untouched
  • status — Report whether the hook is wired, and what it has cost
  • run — The hook body — invoked by the provider, not usually by a human

cs sessions hook install

Wire this pilot's provider to run the co-pilotage hook

Usage: cs sessions hook install [OPTIONS] --provider <NAME>

Options:
  • --provider <NAME> — The pilot whose configuration to wire: claude or codex
  • --settings <PATH> — The settings file to edit. Defaults to the provider's own — for Claude .claude/settings.local.json beside the current directory, for Codex $CODEX_HOME/config.toml or ~/.codex/config.toml
  • --cs-bin <PATH> — The cs binary the hook should invoke. Defaults to this executable
  • --dry-run — Print what would be written without writing it

cs sessions hook uninstall

Remove the co-pilotage hook, leaving the rest of the file untouched

Usage: cs sessions hook uninstall [OPTIONS] --provider <NAME>

Options:
  • --provider <NAME> — The pilot whose configuration to wire: claude or codex
  • --settings <PATH> — The settings file to edit. Defaults to the provider's own — for Claude .claude/settings.local.json beside the current directory, for Codex $CODEX_HOME/config.toml or ~/.codex/config.toml
  • --cs-bin <PATH> — The cs binary the hook should invoke. Defaults to this executable
  • --dry-run — Print what would be written without writing it

cs sessions hook status

Report whether the hook is wired, and what it has cost

Usage: cs sessions hook status [OPTIONS]

Options:
  • --provider <NAME> — Restrict the report to one provider
  • --settings <PATH> — The settings file to inspect, when it is not the provider's default
  • --session <SID> — The session whose cost ledger to summarise. Defaults to $COSMON_SESSION_ID

cs sessions hook run

The hook body — invoked by the provider, not usually by a human

Usage: cs sessions hook run [OPTIONS] --event <EVENT> [PAYLOAD]

Arguments:
  • <PAYLOAD> — The provider's payload. Codex passes it as this trailing argument; Claude pipes it on stdin, which is read when this is absent
Options:
  • --event <EVENT> — Which moment fired: session-start, turn-start, turn-end, waiting or asking
  • --provider <NAME> — The pilot this hook runs inside. Inferred from the payload when it names one; claude otherwise
  • --session <SID> — This session's cosmon id. Defaults to $COSMON_SESSION_ID

cs inbox

Inbox — vertical pile of atomic actions awaiting operator decision (cs inbox)

Usage: cs inbox [OPTIONS]

EXAMPLES: cs inbox # vertical pile of atomic actions cs inbox --json # NDJSON: one row per actionable molecule

The pile has four buckets, top to bottom: ✓ completed (awaiting cs done) 🔥 temp:hot pending ❓ frozen (question from a worker) ⚡ signal molecules

Keys: j/k move · Enter open briefing · d done · t tackle · w whisper · c collapse · r reload · q quit. One panel, one stack — no graph viewer, no chat, no split, no editor, no dashboard, no search bar — the deliberate non-features.

Success metric: 5 days out of 7 without opening Claude Code to pilot cosmon. See docs/guides/inbox-trial.md.

SEE ALSO: cs ensemble (full backlog), cs peek (fractal TUI portal), cs journal (operator carnet that inbox reads as its sticky top line).

Options:

  • --refresh-ms <REFRESH_MS> — Refresh cadence in milliseconds. Inbox reloads the stack on each tick or on r/R. Default: 2000ms (gentler than peek's 250ms — inbox is a decision surface, not a watchdog)

    Default value: 2000

  • --json — Print the inbox contents as NDJSON and exit (agent-first). Skips the TUI entirely. One JSON object per actionable row plus one session envelope when an unsealed session exists

cs work

Separate molecules — an implementer and a reviewer, say, on the same provider or on two different ones — exchange findings under a declared, bounded work scope (ADR-182). Each molecule keeps its own lifecycle, branch and permissions; it stays visible in cs peek and is harvested on its own. Messages carry evidence and requests only: they never advance a molecule, satisfy a dependency or grant one molecule authority over another.

The owning molecule declares a finite seat roster once (declare); each member then sends bounded evidence to another seat (send), pulls what is addressed to it (inbox), and reports how it treated a message (ack). list rebuilds every message's stage — admitted, delivered, consumed — from canonical evidence, for any member or for the owner.

For two live sessions on ONE mission instead, where a human signature moves the controls between them, see cs sessions.

Usage: cs work <COMMAND>

EXAMPLES: cs nucleate task-work --var topic='review task-2026...-0001' # reviewer molecule cs tackle --adapter codex --model gpt-5.6-sol # on another provider cs work declare --seat impl= --seat review= cs work send --to review --text 'finding: the retry loop never backs off' cs work inbox # pull what is addressed to me cs work ack --considered # or --deferred / --rejected cs work list # every message's stage, from evidence

RECIPE — implementer + cross-vendor reviewer (book: how-to/pair-implementer-and-reviewer):

  1. Launch. Nucleate the implementer, then the reviewer with the implementer's id as a variable (no sed into a brief): impl=$(cs nucleate task-work --var topic="..." --json | jq -r .id) rev=$(cs nucleate task-work --var topic="review $impl" --var impl=$impl --json | jq -r .id) cs work declare "$impl" --seat impl="$impl" --seat review="$rev" cs tackle "$impl" --adapter claude --model cs tackle "$rev" --adapter codex --model The owner is the implementer. Pin the model explicitly on each seat.
  2. Implementer brief: goal, the request verbatim, inputs by path, numbered items, constraints, deliverables. Read cs work inbox at each milestone and ack. Send --phase final to review, naming the final sha, before cs complete. Notes go to a per-molecule path.
  3. Reviewer brief: find the peer with cs work list (or the impl id variable); challenge at each milestone with cs work send --to impl; 3-6 task-specific checks; recompute one number independently from saved outputs; every verdict names the impl sha it reviewed; do not cs complete until the impl sent final or is terminal.
  4. Steer with cs whisper to each seat, never with cs work send: a roster message can be acked --rejected, a steering order must not be. A real stop is cs collapse.
  5. Watch with cs work list <owner> and cs observe <seat>. An impl that is collapsed while the reviewer is live, or a reviewer that is completed against an older impl sha, is yours to decide on.
  6. When the implementer terminates, read its reason kind. A worker that finished but could not pass the gates for an infrastructure cause collapses with --reason-kind verification_blocked --reason 'work committed at <sha>; <gate> failed: <class>' (find them with cs errors --kind verification_blocked). That label is the worker's claim, never merge-safety evidence: check git log main..<branch> and whether the failing test touches the diff, then decide. Audit any collapsed branch before deleting it.
  7. Settle: cs collapse <impl> --with-seats collapses every live seat with the owner's reason, skips a completed seat (and prints cs done <seat>), never merges. Then cs done per seat; add --no-merge for an implementer you already merged by hand.
  8. Continue under a NEW owner: settle the old pair, nucleate both new seats with --decayed-from <old>, open the brief with "Continuation of (): merged, do not redesign: ...; remains: ...". Never re-declare a seat name onto another molecule under the old owner. The new reviewer starts cold; that cost is accepted.
  9. Review notes: one file per molecule (notes/<mol_id>.md); regenerate aggregates on main. Never union-merge code.
  10. Cost: reviewer on the other or the cheaper provider; strongest models for framing and arbitration only. No savings are measured yet.

Neither molecule's lifecycle moves because of a message: retries, acceptance and integration stay with each molecule's own owner. Provider diversity, if a formula requires it, is declared on the seat — see ADR-182 §'Provider diversity is a seat property' — not implied by using cs work at all.

SEE ALSO: cs sessions (two live sessions on one mission, human-signed handover), cs nucleate (create the reviewer molecule), cs tackle (spawn its worker).

Subcommands:
  • declare — Declare or revise a finite roster under an owning molecule
  • send — Admit bounded evidence from this member to another seat
  • inbox — Pull messages addressed to this member at a safe point
  • ack — Report how this member treated a received message
  • list — Rebuild the owner's message stages from canonical evidence

cs work declare

Declare or revise a finite roster under an owning molecule

Usage: cs work declare [OPTIONS] --seat <NAME=MOLECULE> <OWNER>

Arguments:
  • <OWNER> — Owning molecule ID
Options:

  • --seat <NAME=MOLECULE> — Seat and molecule, written NAME=MOLECULE; repeat for each member

  • --max-payload-bytes <MAX_PAYLOAD_BYTES> — Largest payload admitted, in bytes

    Default value: 16384

  • --max-messages-per-seat <MAX_MESSAGES_PER_SEAT> — Maximum messages sent by each seat

    Default value: 100

  • --max-bytes-per-seat <MAX_BYTES_PER_SEAT> — Maximum aggregate payload bytes sent by each seat

    Default value: 1048576

  • --default-ttl-secs <DEFAULT_TTL_SECS> — Default message lifetime, in seconds

    Default value: 86400

  • --redeliver-after-secs <REDELIVER_AFTER_SECS> — Minimum seconds before the same adapter offers a message again

    Default value: 60

  • --max-delivery-attempts <MAX_DELIVERY_ATTEMPTS> — Maximum delivery attempts by each adapter

    Default value: 10

cs work send

Admit bounded evidence from this member to another seat

Usage: cs work send [OPTIONS] --to <TO>

Options:
  • --to <TO> — Receiving seat
  • --file <FILE> — Read payload bytes from a file
  • --text <TEXT> — Use this text as the payload
  • --key <KEY> — Caller-chosen idempotency key; otherwise derived from sender, recipient and digest
  • --reply-to <REPLY_TO> — Key of the message being answered
  • --ttl <TTL> — Message lifetime override, in seconds
  • --phase <PHASE> — Free-form phase label for evidence only

cs work inbox

Pull messages addressed to this member at a safe point

Usage: cs work inbox [OPTIONS]

Options:
  • --peek — Show deliverable messages without recording a delivery attempt

cs work ack

Report how this member treated a received message

Usage: cs work ack [OPTIONS] <KEY>

Arguments:
  • <KEY> — Key of the received message
Options:
  • --considered — Report that the message was considered
  • --deferred — Report that the message was deferred
  • --rejected — Report that the message was rejected
  • --reply <REPLY> — Key of an already admitted reply
  • --note <NOTE> — Optional consumption note, stored by its digest beside the receipts

cs work list

Rebuild the owner's message stages from canonical evidence

Usage: cs work list [OPTIONS] [OWNER]

Arguments:
  • <OWNER> — Owner molecule; defaults to the caller's declared work
Options:
  • --pending — Only envelopes still pending for a recipient
  • --open — Only envelopes without a consumption report

cs collaboration

Provision, inspect and revoke collaboration bindings on the authoritative host.

A binding lets one exact identity (issuer, subject, audience, tenant) act as one seat of a declared work, or as one pilot attachment of a mission, from another machine. Each binding has its own attachment ID and a private proof. The proof is written once to the file named by --proof-out and never stored on the host; hand it to the client, which keeps it in its credential store.

Bindings grant only the collaboration scopes named with --scope. They confer no spawn, harvest, lease or operator right, and a request can never change its own binding. Revocation takes effect at the next admission and at the commit of any write already admitted. No network route uses these bindings yet.

Usage: cs collaboration <COMMAND>

EXAMPLES: cs collaboration bind --issuer https://idp.example --subject pilot-b
--audience cosmon-rpp-demo --tenant demo
--work-owner --seat review --scope cosmon:work:write
--proof-out ./review.proof # proof written once, 0600 cs collaboration list # every binding, no proofs cs collaboration show cs collaboration revoke # refuses the next admission and commit

The proof file is the client's secret: move it to the client machine, store it in its credential store, then delete the file. The host keeps only a verifier.

Subcommands:
  • bind — Provision a binding and write its attachment proof to a new private file
  • list — List every binding, active and revoked, without verifiers or proofs
  • show — Show one binding
  • revoke — Revoke one binding; earlier admissions fail at their commit

cs collaboration bind

Provision a binding and write its attachment proof to a new private file

Usage: cs collaboration bind [OPTIONS] --issuer <ISSUER> --subject <SUBJECT> --audience <AUDIENCE> --tenant <TENANT> --scope <SCOPES> --proof-out <PROOF_OUT>

Options:
  • --issuer <ISSUER> — Exact token issuer
  • --subject <SUBJECT> — Exact token subject
  • --audience <AUDIENCE> — Exact token audience
  • --tenant <TENANT> — Tenant the identity is bound to
  • --work-owner <WORK_OWNER> — Owning molecule of the declared work (requires --seat)
  • --seat <SEAT> — Work seat the attachment acts as
  • --mission <MISSION> — Mission whose pilot surface the attachment joins
  • --scope <SCOPES> — Granted scope; repeat for several (cosmon:work:read, cosmon:work:write, cosmon:sessions:read, cosmon:sessions:write)
  • --proof-out <PROOF_OUT> — New file that receives the attachment proof (created 0600, never overwritten)
  • --label <LABEL> — Display label for the client machine; never used for admission

cs collaboration list

List every binding, active and revoked, without verifiers or proofs

Usage: cs collaboration list

cs collaboration show

Show one binding

Usage: cs collaboration show <ID>

Arguments:
  • <ID> — Binding ID (cb-…)

cs collaboration revoke

Revoke one binding; earlier admissions fail at their commit

Usage: cs collaboration revoke <ID>

Arguments:
  • <ID> — Binding ID (cb-…)

cs panel

Panel — convene a hash-pinned supermajority panel to gate a constitutional amendment

Usage: cs panel <COMMAND>

EXAMPLES: git diff main | cs panel convene # seat the panel from the staged diff cs panel convene --diff change.patch # seat from a diff file cs panel convene --diff change.patch --json # NDJSON for scripting cs panel decide --diff change.patch
--vote wheeler=approve --vote torvalds=refuse:breaks I1
--vote feynman=approve --vote shannon=approve
--vote jobs=approve --out panel.role-log.json # tally + inscribe role-log

Convene a hash-pinned supermajority panel to gate a constitutional amendment — anything operator-uncapturable, a forbid_operator_* lint, or a new operator_* field. The cost of amendment rises from O(1 PR) to O(panel convocation): what was legislative becomes constitutional.

A panel is a fixed constitutional CORE (default wheeler,torvalds,feynman, shannon) plus rotating SEAT(S) drawn from a POOL by hashing the diff. The rotating seat is a pure function of the diff, so the convener cannot pick a friendly judge after seeing the test (audience-after-the-test, delib 20260503-5a74). decide refuses ballots from non-panelists and refuses to rule until every seat has voted. Verdict needs a 4/5 supermajority (--rule).

EXIT CODES (decide): 0 approve, 2 refuse, 1 error.

SEE ALSO: cs notarize (operator Ed25519 attestation), cs witness (quorum seal).

Subcommands:
  • convene — Seat the panel deterministically from the artifact hash and print it
  • decide — Tally ballots from the seated panel, emit verdict, inscribe role-log

cs panel convene

Seat the panel deterministically from the artifact hash and print it

Usage: cs panel convene [OPTIONS]

Options:

  • --core <CORE> — Comma-separated constitutional core (always seated)

  • --pool <POOL> — Comma-separated rotation pool (hash-pinned seats drawn from here)

  • --seats <SEATS> — Number of rotating seats filled from the pool by the diff hash

    Default value: 1

  • --rule <RULE> — Supermajority rule as NUM/DEN (default 4/5)

    Default value: 4/5

  • --diff <PATH> — Path to the artifact (e.g. PR diff). Reads stdin when omitted

  • --artifact-hash <HEX> — Use a precomputed artifact hash (64-char hex) instead of hashing bytes

cs panel decide

Tally ballots from the seated panel, emit verdict, inscribe role-log

Usage: cs panel decide [OPTIONS]

Options:

  • --core <CORE> — Comma-separated constitutional core (always seated)

  • --pool <POOL> — Comma-separated rotation pool (hash-pinned seats drawn from here)

  • --seats <SEATS> — Number of rotating seats filled from the pool by the diff hash

    Default value: 1

  • --rule <RULE> — Supermajority rule as NUM/DEN (default 4/5)

    Default value: 4/5

  • --diff <PATH> — Path to the artifact (e.g. PR diff). Reads stdin when omitted and no --artifact-hash is given

  • --artifact-hash <HEX> — Use a precomputed artifact hash (64-char hex) instead of hashing bytes

  • --vote <PERSONA=VOTE[:REASON]> — A ballot, repeatable: persona=approve / persona=refuse[:reason]

  • --out <PATH> — Where to inscribe the role-log JSON. Defaults to stdout (with --json) or no file (human mode prints a summary). Use - for stdout

cs notify

Notify — push a one-line message to every configured operator channel

Usage: cs notify [OPTIONS] <MESSAGE>

EXAMPLES: cs notify "v1.2.1 tenant-demo deploy ok" # default channels cs notify "worker quartz silent 240s" --level warn --molecule cs-20260426-a7e6 cs notify "hello" --channel macos --channel file-drop # override channels cs notify "automata gen 4096" --channel telegram # Telegram DM cs notify "dry test" --dry-run # don't dispatch

Pushes one line to every channel in [notify].channels of .cosmon/config.toml (macos | file-drop | element | telegram). Best-effort: a single channel failure is logged but the others still fire. Closes the silent-24h gap by giving the fleet a primitive to reach the operator's attention surface.

Arguments:
  • <MESSAGE> — The notification message (positional, single line)
Options:

  • --title <TITLE> — Optional title prefix. Channels render it as the first line / header

    Default value: cosmon

  • --channel <CHANNEL> — Override the configured channel set. May be repeated. Recognised values: macos, file-drop, element, telegram. When omitted, every channel declared in .cosmon/config.toml is used

  • --molecule <MOLECULE_ID> — Optional molecule id the notification is about. Surfaces in the JSON output and the file-drop body

  • --level <LEVEL> — Severity tag (advisory). One of info, warn, alert. Channels that support it (file-drop) pass it through; others ignore

    Default value: info

  • --dry-run — Treat dispatch as a dry-run: log what would be sent without invoking any side-effecting transport. Equivalent to setting COSMON_NOTIFY_DRY_RUN=1

cs opt-in-share

Opt-in-share — first-run consent prompt for encrypted developer bundles

Usage: cs opt-in-share [OPTIONS]

EXAMPLES: cs opt-in-share # first-run prompt (once per user) cs opt-in-share --status # show current consent state cs opt-in-share --decline # non-interactive: record decline cs opt-in-share --accept # non-interactive: record acceptance cs opt-in-share --json # NDJSON output for scripting

Deny-by-default. The first time cs init runs interactively, this prompt fires automatically (once) and the answer is persisted to ~/.config/cosmon/consent.toml. No trace in your project's git log.

The prompt names the encryption (age), the sole recipient (the Noogram maintainer), and the no-trace-in-commits guarantee, then asks [y/N]. Anything but an explicit yes is recorded as a decline; o/oui are still accepted, from when the prompt was French (noogram/cosmon#76).

The question is asked only where an answer can arrive: stdin AND stdout must both be terminals. A captured stdout (CI, scripts, OUT="$(cs ...)") records a decline without asking and says so on stderr. cs tackle never asks — nothing on the dispatch path may block on a human (ADR-163).

SEE ALSO: cs init (the first-run hook site).

Options:
  • --status — Print the current consent state (accepted / declined / none) and exit
  • --decline — Bypass the TTY prompt and persist a declined record (non-interactive)
  • --accept — Bypass the TTY prompt and persist an accepted record (non-interactive)

cs demo

Demo — one-command end-to-end chatbot surface (first-contact experience)

Usage: cs demo [OPTIONS]

EXAMPLES: cs demo # interactive prompt → full cycle cs demo --prompt "Implement X" # skip TTY, classify as task-work cs demo --formula deep-think --prompt "Is X viable?" cs demo --adapter llama-cpp --prompt "Hello, world" # route through llama.cpp cs demo --no-teardown # leave worktree intact for inspection

Runs nucleate → tackle → wait → done in one shot. All artefacts persist.

The --adapter flag is threaded to cs tackle so the demo cycle exercises any registered Adapter (claude, aider, openai-chat, llama-cpp, …). Per ADR-106 the legacy alias llama canonicalises to llama-cpp at the CLI seam — both invocations route to the same in-process adapter.

Options:

  • --prompt <PROMPT> — Skip the interactive prompt; use this text as the demo input

  • --formula <FORMULA> — Force a specific formula instead of auto-classifying.

    The named formula must already exist under .cosmon/formulas/. No new formulas are registered by cs demo.

  • --no-teardown — Skip the final cs done teardown — useful for debugging.

    When set, the molecule remains Completed (or Collapsed) but its worktree, tmux session, and fleet worker are left intact for post-mortem inspection.

  • --timeout <TIMEOUT> — Maximum seconds to wait for the molecule to reach a terminal state.

    Mirrors the cs wait --timeout default so cs demo does not silently allow a runaway demo to hang the operator's terminal.

    Default value: 600

  • --adapter <NAME> — Worker-Spawn Port Adapter to dispatch (ADR-079 / ADR-097 / ADR-106).

    Mirrors cs tackle --adapter: when set, the value is threaded through to the cs tackle invocation that cs demo spawns under the hood, so the demo cycle can exercise any registered Adapter (e.g. llama-cpp, claude, aider, openai-chat). Optional — the default resolution path (.cosmon/config.toml::[adapters.default] → built-in BUILTIN_FLOOR_ADAPTER, currently "local", the Ollama-backed in-process loop — never Claude) is preserved when the flag is omitted.

    Per ADR-106 the canonical name for the in-process llama.cpp adapter is llama-cpp; the legacy alias llama is accepted at the CLI seam (canonicalises via cs tackle's validate_adapter_name).

  • --model <MODEL_ID> — Model to run, threaded verbatim to cs tackle --model (COSMON #23).

    For the default local adapter this is the Ollama model tag, e.g. --model qwen2.5:32b or --model llama3.2:3b. It must already be pulled (ollama pull <id>); the dispatch preflight refuses rather than collapsing a molecule against a model the daemon cannot serve.

    Precedence for the local adapter, highest first: this flag → formula-step model = pin → [adapters.local].default_model in .cosmon/config.toml → COSMON_LOCAL_MODEL → the built-in default qwen3:8b. Every local dispatch prints the model it resolved and its origin on stderr, so the effective choice is never a guess. Point the adapter at another daemon with [adapters.local].base_url, COSMON_LOCAL_BASE_URL, or the native OLLAMA_HOST. Full guide: docs/guides/local-model-selection.md.

cs whisper

Whisper — inject a perturbation payload into a live worker's tmux pane (v0)

Molecule delivery refuses on money-stake markers and recognised unknown confirmation/menu widgets in the active pane tail. The latest idle input field supersedes earlier scrollback. Confirmations such as [y/n] and risky prompts without a permission marker remain blocking. Ordinary output and routine permission prompts remain deliverable. A dialogue refusal reports the rule and matched pane tail lines.

Usage: cs whisper [OPTIONS] [MOLECULE_ID]

EXAMPLES: cs whisper --message "check the latest ADR before merging" cs whisper --file hint.md echo "nudge" | cs whisper --stdin cs whisper --message "…" --dry-run # validate, do not paste

Experimental v0. Perturbation port, not a control-plane event. Refuses unless the target pane's foreground command has an allowed pane signature. Built-in signatures: claude, claude*, node, , codex, codex*. A money-stake marker or a recognised unknown confirmation/menu widget refuses with exit 5; unknown means the widget is real but its choice is not safe to infer. Ordinary output without those signals is delivered. Routine permission prompts remain deliverable. A refusal prints the matching rule and pane tail lines so the operator can inspect the choice. If no tmux session of the recorded name exists (killed or renamed), it refuses with exit 6 (session not found).

To wait for the worker's answer, follow with cs wait <mol>: even on a completed molecule it returns only after a new commit on feat/.

Arguments:

  • <MOLECULE_ID> — Molecule whose worker pane will receive the whisper.

    Optional because --to-session is an alternative destination; enforced at runtime so clap's error text points at the mutual exclusion rather than an unsatisfied positional.

Options:

  • --to-session <SID> — Target a Claude session by id — appends one line to .cosmon/state/presence/<sid>.log instead of pasting into a tmux pane. Mutually exclusive with the positional <molecule_id>.

    CEILING: whispers accumulate in the log; beyond ~10 per session the signal drowns in the tail. Past that, fall back to cs drop / cs tail.

  • -m, --message <TEXT> — Inline payload. Mutually exclusive with --file / --stdin

  • -f, --file <PATH> — Read payload from a file. Mutually exclusive with --message / --stdin

  • --stdin — Read payload from stdin (conventional -). Mutually exclusive with --message / --file

  • --dry-run — Validate and log the payload without actually pasting into tmux.

    In --to-session mode, skips the append (and the seek bump) — useful for CI-style sanity checks.