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 archive outlives worktree teardown and branch deletion — a fresh clone sees every merged molecule's canonical snapshot.

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.

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 or turn-end
--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 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

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 French prompt names the encryption (age), the sole recipient (the Noogram maintainer), and the no-trace-in-commits guarantee, then asks [o/N]. Anything but an explicit yes is recorded as a decline.

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)

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 is in [whisper] allowed_commands (default: ["claude"]).

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.

Keyboard shortcuts

noogram / cosmon