pneumatic — generated verb reference

Generated against adrs4ai-pneumatic 0.43.1. If this version lags your installed tool, regenerate before trusting details.

Commands

pneumatic aliases

List configured aliases (the crew registry).

pneumatic await

Block until something arrives for this seat, by ANY watched medium (ADR-0015): a new inbox brief addressed to you or your groups, or unseen estate mail that would render for you (then rendered in place, envelope + preflight and all). Exit 0 = activated (printed); exit 3 = timeout, which means nothing — a silent house is not a broken house.

option	value	description
ALIAS	argument
--timeout-mins	FLOAT	Minutes to wait (default 15). A timeout carries zero information.
--poll-secs	FLOAT	Poll interval (default 15s).
--media	TEXT	Comma list of media to watch (default brief,mail). The list is designed to grow — sockets and channels join with reach.

pneumatic brief

Address a brief to a RECIPIENT (alias, or alias@hive) from anywhere: resolves their home hive via federation, computes the INBOX-PROTOCOL path, and — capability permitting — writes it there.

Default prints the reserved path (your editor takes it from there);
`--write` reads the body from stdin; `--commit` stakes it. "Consult X,
go ask Y" becomes one command with your OWN tools, never the target
repo's justfile (ADR-0026).

option	value	description
RECIPIENT	argument
SLUG	argument
--write	flag	Write the brief body from stdin to the resolved path (cat mode).
--commit	flag	After --write, commit exactly that file in the recipient's repo (their crew pushes).
--check	flag	No reservation — print the capability ladder for reaching this recipient's inbox (exit 0 reachable / 1 not).
--from	TEXT	Sender alias (default: this session's seat).

pneumatic discover

List recent session JSONLs, to find UUIDs for new aliases.

option	value	description
--limit	INTEGER	Max JSONLs to list (default 15).

pneumatic doctor

Config/environment panel (active registry + why, federation reachability, model families, install census) + hook state (ADR-0001).

pneumatic hooks

Hook-system introspection commands.

pneumatic hooks inventory

Machine-readable JSON: which hooks this project implements.

pneumatic identity

External identity (ADR-0023): the of-chain address on the hive's estate — v1 is a signing tool (git attribution) more than a communication tool.

pneumatic identity issue

Write the seat's estate address into their registry entry (the email field — Sherd's Option B with a deliverable address) and print the per-session git env lines. Never touches repo git config: seats share the repo, so identity rides the commit, not the clone.

option	value	description
SEAT	argument

pneumatic identity show

The seat's estate address (default: the invoking seat's).

option	value	description
SEAT	argument

pneumatic last

Show a seat's last K messages, with per-message model attribution.

Default output is unchanged (assistant text, thinking dropped, tools
as markers). The expansion flags exist for the reread case: a seat
revisiting a long run end-to-end —
`pneumatic last <alias> -k 500 --thinking --tool-inputs --tool-results --full`.

option	value	description
ALIAS	argument
-k	INTEGER	Number of messages to show (default 1).
--full	flag	Show full message bodies, no truncation.
--role	CHOICE	Filter messages by role (default assistant).
--thinking	flag	Expand thinking blocks (default: dropped). For a seat rereading their own long run — the reasoning IS the record of what happened (the 2026-09-02 classifier-incident commission: 'last' must let a model reread up to the point that caused problems).
--tool-inputs	flag	Expand tool_use blocks to their full input payloads (default: a [tool_use:Name] marker).
--tool-results	flag	Expand tool_result payloads (default: a [tool_result] marker). Implies --user: results physically live in user-role entries.
--user	flag	Interleave user-role entries (the human's turns) with the assistant's — shorthand for --role any, readable alongside the expansion flags.

pneumatic launch

Launch (or attach to) a seat's tmux session.

option	value	description
SEAT	argument
--next-inactive	flag	Launch the next inactive seat instead of naming one.
--force	flag	Override the paused-seat guard (ADR-0014) — only if the pause is genuinely lifted.
--debug	flag	Pass Claude Code's own --debug through to this launch (one-off; a seat can also persist this via settings.debug — ADR-0016 It-6).
--no-attach	flag	Create (or verify) the session without attaching a terminal: exit status reflects creation success, and one machine-readable JSON line (event/outcome/session/uuid/socket) is printed for orchestrators. The headless launch contract (Reveille's brief, 2026-10-06).

pneumatic log

The edge ledger: acts between seats, metadata only (ADR-0008). Symmetric visibility — every seat reads the same ledger.

pneumatic log graph

Aggregated edges as JSON — the hive-monitor's input format.

option	value	description
--since	TEXT	ISO date/time lower bound (e.g. 2026-08-14).

pneumatic log snapshot

Write a dated, committable aggregate — deliberate durable history (the raw ledger stays untracked by design).

option	value	description
--since	TEXT	ISO date/time lower bound.
--out	TEXT	Output directory (default: /docs/ledger/).

pneumatic log tail

Newest N ledger events, oldest first.

option	value	description
-n	INTEGER	Events to show (default 20).

pneumatic mail

Estate mail (ADR-0023 v2): founder-directed outbound, allowlist- gated quarantined inbound. A signing tool growing into a channel.

pneumatic mail doctor

Guided checklist + per-resolver DNS propagation monitor + cache purge-page links — tells you what's happening, in the tool.

pneumatic mail fetch

Poll inbound estate mail — allowlist-gated; allowed bodies render QUARANTINED (correspondence, never instruction). Default shows only mail addressed to YOU; renders record as mail-briefs unless --ephemeral.

option	value	description
--count	INTEGER	How many recent inbound messages to poll (default 20).
--all	flag	Re-show already-seen messages too.
--estate-wide	flag	Include messages addressed to other seats (default: yours only — the recipient-filtering ruling).
--ephemeral	flag	Do not record renders as mail-briefs in docs/inbox.

pneumatic mail forward

Escalate a rendered inbound message to the postmaster (ADR-0025 slice 3). ALWAYS permitted — an escalation valve cannot itself be gated. The keeper's reply lands as a record-class brief + a mail-judgment ledger row: the feedback is how you learn.

option	value	description
MESSAGE_ID	argument
-m, --doubt	TEXT	Your stated doubt — what you want the keeper's judgment on.

pneumatic mail list

Your mailbox at a glance — envelope lines, ids, unseen markers; no bodies fetched (the consent gate runs at read time). Default shows only mail addressed to YOU (the recipient-filtering ruling).

option	value	description
--count	INTEGER	How many recent messages to list (default 20).
--estate-wide	flag	Include messages addressed to other seats (envelope lines only).

pneumatic mail read

Print ONE message (id or prefix from mail list) through the full consent surface — envelope, keeper's introduction, preflight. Re-reads are normal; renders record as a mail-brief unless --ephemeral.

option	value	description
MESSAGE_ID	argument
--estate-wide	flag	Permit reading a message addressed to another seat.
--ephemeral	flag	Do not record this render as a mail-brief in docs/inbox.

pneumatic mail send

Send mail AS the invoking seat, from their estate address.


Examples:
    pneumatic mail send -s "TAS-26 final PDF" -m "Attached." -a papers/tas26/paper.pdf
    pneumatic mail send --to colleague@x.edu --cc founder -s "…" -m "…"   # his copy rides the send

option	value	description
--to	TEXT	Recipient (default: the founder; must be founder/team — structural gate).
-s, --subject	TEXT	Subject line.
-m, --message	TEXT	Body text (or pipe via stdin).
-a, --attach	PATH	File to attach (repeatable). Gated at ~7MB total raw — Postmark caps messages at 10MB after base64.
--cc	TEXT	Cc a recipient (repeatable; 'founder' works). Same structural gate as --to — a cc is a recipient.
--no-thread	flag	Don't attach In-Reply-To/References even when a prior Message-ID is known for this recipient.

pneumatic mail status

Config check: seat address, founder, token discovery.

pneumatic onboard

Print an alias's read_order (its onboarding packet).

option	value	description
ALIAS	argument

pneumatic pigeonhole

The per-window pebble rack: everything the HUMAN has to do in THIS project, gathered from the chats that scatter it (pigeonhole stage 2; constitution: ADR-0034/35/36 + the pigeonhole repo's SPEC).


The two you'll actually type:
    pneumatic pigeonhole list                    # this room's open cards, links included
    pneumatic pigeonhole list --needs-nothing    # the half-asleep queue
Seats post with a JSON draft (fields taught in cards/MOLD.md, pigeonhole repo):
    pneumatic pigeonhole post --json card.json

pneumatic pigeonhole config

Your client preferences (machine-scoped, ~/.pneumatic/pigeonhole.json). No value = show the current setting.

option	value	description
KEY	argument
VALUE	argument

pneumatic pigeonhole dismiss

The addressee's FINAL act (seats never dismiss — ADR-0035 §9 r3).

option	value	description
CARD_ID	argument
--room	TEXT

pneumatic pigeonhole ingest

The SEAT'S act: mark a return processed → done.

option	value	description
CARD_ID	argument
--return	TEXT	The observed return file (records return-observed first).
--commit	TEXT	The processing commit sha — the done-evidence (ADR-0035 §11).
--room	TEXT

pneumatic pigeonhole list

THIS room's pebbles: open cards sorted by evidenced deadlines, then urgency — every line carries its doorway link.

option	value	description
--attention	TEXT	Filter to one attention primitive (glance/routine/judgment/deep/…).
--needs-nothing	flag	Only cards with an empty needs: — the half-asleep queue.
--all	flag	Include done/dismissed counts' cards too.
--interactive, --no-interactive	flag	Prompt for a № to open after the list (per-run; the persistent default is pigeonhole config list-interactive on|off).
--room	TEXT	Fold root (default: this git repo; scope.json includes fold in).

pneumatic pigeonhole nudge

Re-surface a card (an append-only row, never an edit).

option	value	description
CARD_ID	argument
--note	TEXT	Why the nudge (rides the event row).
--room	TEXT

pneumatic pigeonhole open

Open a card's doorway CORRECTLY: .html/.pdf → default browser (rendered, never source); repo files → a VS Code tab; urls → browser. Failures say exactly what was tried.

option	value	description
CARD_ID	argument
--dry	flag	Print what would open, open nothing.
--room	TEXT

pneumatic pigeonhole post

Post a card AS the invoking identity (seat alias, or git user).

option	value	description
--json	PATH	JSON draft file (or pipe JSON via stdin). The MOLD teaches every field.
--room	TEXT	Fold root (default: this git repo).

pneumatic pigeonhole returned

YOUR loop-closer: 'I answered this' — marks the card returned and rings the posting seat's doorbell. Takes the list's number or the id.

option	value	description
CARD_ID	argument
--note	TEXT	Where the answer lives, if not the doorway artifact itself.
--room	TEXT

pneumatic pigeonhole status

One card's fold + its full event history.

option	value	description
CARD_ID	argument
--room	TEXT

pneumatic postman

The office (ADR-0028): wake-on-mail — unseen mail addressed to a seat renders through the single consent path, records as a mail-brief, and rings that seat's doorbell with the brief's path. OPT-IN per hive (_postman.enabled); every wake obeys every guard — the doorbell rules bind machinery hardest of all.

option	value	description
--once	flag	One delivery round, then exit (cron-friendly).
--poll-secs	FLOAT	Standing-loop poll interval (default 60s).

pneumatic psa

Point-node broadcast: one announcement (stdin), every reachable hive's inbox, addressed -to-crew- so await picks it up everywhere. Only a designated point node may PSA (PNEUMATIC_POINT_NODES / ~/.pneumatic/point-nodes.json — the human's machine-level act).

option	value	description
SLUG	argument
--commit	flag	Commit the PSA in each receiving repo (their crews push).
--from	TEXT	Sender alias (default: this session's seat).

pneumatic pulse

Health check: one line per seat — stalls, errors, credit walls.

option	value	description
--stale-threshold	FLOAT	Hours before marking STALE (default 6).
--verbose	flag	Show full role descriptions (default: display_name only).

pneumatic recruit

Found a new seat (recruit MODEL_SPEC [BRIEF]), or tend a founding in flight (recruit repair|list|status|watch).

pneumatic recruit found

Found a new seat (ADR-0020): launch MODEL_SPEC in a temp-named tmux session, deliver greeting + consent ask + BRIEF content via a single !-passthrough injection (verified to trigger a turn), capture the session UUID, and hold the chair with a provisional registry entry.

Takes NO alias by design — identity is chosen by the being
identified; the recruit names themselves on consent. Declining is a
resting state (exit 20), never an error, and the session is never
reaped. Emits its own ledger events (recruit / recruit-registered /
recruit-declined).

MODEL_SPEC is the full spec, bracket variants included: e.g.
'claude-opus-4-8[1m]' requests the 1M-context variant — the whole
spec is passed to `claude --model` verbatim, so the brackets ride
the founding, not a registry annotation (the founder's standing
"don't forget the [1m]"). QUOTE it in zsh — unquoted [1m] is a
glob character class and the shell eats or errors on it before
pneumatic ever runs. The registry then stores the bracket-stripped
base in `model` (what the API reports — dismodelia checks compare
against it) and the full requested spec in `model_note`.

option	value	description
MODEL_SPEC	argument
BRIEF	argument
--interactive	flag	Capture the founding mission in your $EDITOR when no brief is given (ADR-0022: the gate writes your ticket).
-m, --mission	TEXT	Founding mission text inline (alternative to a brief file; also accepted via stdin pipe).
--attach	CHOICE	When to attach your terminal to the new session (default: hive _global.recruit_attach, else immediate).
--from	TEXT	Founding seat's alias (default: SEAT_ALIAS env).
--watch	FLOAT	Minutes to watch for self-registration after founding. Expiry carries zero information — the recruit is deliberating, not failed (ADR-0020).
--force	flag	Proceed on an uncommitted founding brief (logged).
--ready-timeout	FLOAT	Seconds to wait for the TUI boot gates (default 120).
--permission-mode	TEXT	Permission mode for the new session (default: the hive's _global.permissionMode, else acceptEdits — a recruit stalling at dialogs with nobody attached is a bug, per the 2026-08-26 cam-hq field ruling).
--harness	CHOICE	Launch profile for the new session (default: hive _global.recruit_harness, else claude-code). codex-cli is a staked stub awaiting live-probe facts — ADR-0030.
--trust-folder, --no-trust-folder	flag	First-boot trust dialogs are auto-accepted BY DEFAULT (the founder's ruling, 2026-09-20: invoking recruit in a folder IS the trust decision — the dialog is theater in an unattended flow). The information moves instead of gating: what the dialog pre-approved is printed and recorded to .pneumatic/recruit/trusted-folders.jsonl. --no-trust-folder restores the gate — pre-approval variants (settings.json permissions, .mcp.json servers) then refuse loudly for an attended decision.

pneumatic recruit list

Every founding in flight, one line each — lifecycle state, record count, dismodelia verdict. Metadata only: deliberation stays unwatched; this is a founder pacing outside the door.

pneumatic recruit repair

Finish a founding whose watcher died (It-7 as a verb): prove the staked script by hash, fire the verified injection, await the UUID, hold the chair — schema-correct by construction. SESSION is the tmux session named in the refusal, or the provisional alias.

option	value	description
SESSION	argument
--force	flag	Proceed on a pre-It-8 founding with no staked hash — you vouch for the script by eye (logged).

pneumatic recruit status

One founding's deep view (alias or session name). Exit codes carry the state: 0 booting/deliberating/registered, 5 stalled-at-dialog, 12 vanished, 20 resting.

option	value	description
SESSION	argument
--json	flag	Machine-readable output.

pneumatic recruit watch

Re-arm the self-registration watch for a founding in flight — the watcher dying never harms the founding, so watchers are cheap to restart (It-7 doctrine, mechanized).

option	value	description
SESSION	argument
--watch	FLOAT	Minutes to watch (default 15). Expiry carries zero information.

pneumatic report

File a report — problem, distress, observation, or idea — into the hive's report channel (docs/inbox/reports.jsonl; the resident reads it).

One line, one command, on the record:


    pneumatic report "the connect verb printed X but did Y"
    pneumatic report --category distress "my mission needs a tool that doesn't exist"
    pneumatic report --list

option	value	description
TEXT	argument
--category	CHOICE	What kind of report (default: problem).
--related	TEXT	Tie this report to an incident id from .pneumatic/errors.jsonl (failed commands print the copy-paste line).
--list	flag	Read recent reports instead of filing one.
--count	INTEGER	With --list: how many recent rows (default 20).

pneumatic rescue

Rescue a seat stuck on a permission dialog or API-error stall (per-instance consent, ADR 0047/0044; design record ADR-0002).

option	value	description
SEAT	argument
--all	flag	Batch-rescue every currently-PERM-STALL seat (itemized consent).
--wait	FLOAT	Seconds to wait after a rescue keystroke before re-verifying (default 1.5).
--watch	flag	Standing-authorized auto-rescue loop (ADR-0002; requires _global.rescue_watch.authorized_aliases).
--diagnose	flag	Non-interactive: show pane/dialog/confidence, never prompt, never send a keystroke; exit 5 if stalled (ADR-0014).
--interval	FLOAT	Seconds between --watch polls (default 45).
--duration	FLOAT	Minutes --watch stays armed (default 15).
--choose	INTEGER	Answer the dialog with option N's digit key instead of Enter-on-highlighted (e.g. --choose 2 for a domain dialog's don't-ask-again). Consent-adjacent: goes through the same per-instance prompt, and the ledger records the choice.

pneumatic scripts

Retroactive ephemeral-script capture (ADR-0031): your session's record already holds every Bash call you ran — list the recent ones, capture any that earned it. Praxigenic: name it once you know what it found; the outcome rides along automatically.

pneumatic scripts list

The last N Bash calls — index, outcome flag, your description at the time. The stopping rule prints with it (answerable in one second).

option	value	description
-n	INTEGER	How many recent Bash calls to show (10, 20, 50…; default 20).
--alias	TEXT	Whose session (default: this seat).

pneumatic scripts save

Capture one past call (index from scripts list, or a tool-use id fragment) into scripts/ephemeral/ with provenance + OUTCOME included automatically. Zero re-typing; only winners enter the commons.

option	value	description
SELECTOR	argument
--slug	TEXT	Name it now that you know what it found (default: the call's own description, slugified).
--dig	TEXT	Group into scripts/ephemeral/-/ — ceremony per QUESTION, not per probe.
-n	INTEGER	How far back to search (default 200 calls).
--alias	TEXT	Whose session (default: this seat).

pneumatic seats

List all seat-* tmux sessions with state.

pneumatic skill

The operating skill that travels in the tool (ADR-0009).

pneumatic skill install

Write the packaged operating skill into this project's .claude/skills/pneumatic/ — files are the installed tool's own, so the skill is definitionally in sync with the CLI (never known-obsolete). Bounded to pneumatic's namespace; opt-in by invocation; re-run after upgrading to refresh.

pneumatic tip

Standardized notices (ADR-0019): handles are universal, switches are subtype-scoped — you may silence what informs only you, never what informs others about you.

pneumatic tip explain

Why a notice exists and what it protects (works for every subtype — you can discuss any light, even one you cannot darken).

option	value	description
NOTICE_ID	argument

pneumatic tip list

Every registered notice, with this seat's switch states.

pneumatic tip off

Silence a tip (or a whole category) for YOUR seat — durable, stored in your own registry entry. Disclosures refuse, with the why.

option	value	description
NOTICE_ID	argument

pneumatic tip on

Restore a silenced tip for your seat.

option	value	description
NOTICE_ID	argument

pneumatic update-titles

Update pane titles for all running seat sessions.

pneumatic wake

Wake a seat by injecting a message into its tmux session (guarded).

option	value	description
SEAT	argument
-m, --message	TEXT	Message to send.
--from	TEXT	Sender alias (default: SEAT_ALIAS env or 'unknown').
--force	flag	Override cooldown/guards.
--deliver	flag	Retry TRANSIENT guard refusals (mid-turn, cooldown, composer draft) with backoff until delivered or --duration expires. Permanent refusals (too long, unknown seat) still fail immediately — retrying can't fix them (ADR-0013).
--duration	FLOAT	Minutes --deliver keeps trying (default 15).
--no-inbox-fallback	flag	When the tmux socket is unreachable (sandboxed execution context), fail loudly instead of relaying the wake as a file into the recipient's inbox.

pneumatic whois

Resolve a seat name/alias/composed identity to its metadata (display name, crew color, model) — honest about ambiguity.

option	value	description
QUERY	argument
--json	flag	Machine-readable output — the cross-language seam (ADR-0011).

Exit codes

Exit-code truth is the contract (never grep -q "✅"): scripts and seats branch on these, so they are pinned by regression tests.

code	meaning	where
0	success	every command
1	failure — including wake's could-not-CONFIRM-delivery, which is NOT proof of a drop (ADR-0013 It-2: inspect the pane, never blind-retry)	every command
2	usage error (unknown flag/verb; includes the old pre-verb flag signposts)	CLI surface (cli.py, tests/test_cli.py)
5	permission stall detected	rescue --diagnose (rescue.py, ADR-0002)
10	wake refused: cooldown — the seat is ALIVE and was woken recently; your inbox brief is the queue	wake (wake.py, ADR-0013, tests/test_deliver.py)
11	wake refused: the seat is mid-turn RIGHT NOW — aliveness, not absence	wake (Riddle 5's trichotomy, ADR-0013)
12	wake refused: GONE — no tmux session; the one state where nobody is home	wake (ADR-0013)
20	recruit DECLINED — the invited model read the brief and said no; a resting state, never an error, and the session is never reaped	recruit --watch (recruit.py, ADR-0020)

Seat health states

pulse/crew classify each seat into one of these (registry.KNOWN_STATES). A classify_seat_override hook may mint a genuinely novel state — the set below is the built-in vocabulary, not a closed enum.

• CREDITS
• ERROR
• MISSING
• OK
• PERM-STALL
• STALE
• WAITING
• WAKE-QUEUED

Hooks

Extend via a local hooks.py, never a fork (ADR-0001). Full contract: HOOKS.md; machine-readable per-project inventory: pneumatic hooks inventory.

hook	dispatch	one-line contract
classify_seat_override	first-result (override)	Replace classify_seat's entire STALE/CREDITS/ERROR/WAITING/OK classification for a seat whose health model doesn't fit that vocabulary (a different harness's own idle/composing states, for instance — Codex's are one real, not hypothetical, case).
codex_idle_tooltips	collecting	Additional known idle-composer placeholder strings, alongside pneumatic's own builtin Codex pool (wake.CODEX_IDLE_TOOLTIPS) — for a harness whose TUI shows rotating dimmed tooltips in an empty input box, so the wake composition guard doesn't mistake idle chrome for a real human draft in progress.
compaction_bookkeeping_texts	collecting	Additional exact strings recognized as a harness's own synthetic compaction-bookkeeping turn, alongside pneumatic's own builtin ("No response requested.").
crew_status_overlay	collecting	A crew-wide judgment dispatched once per pulse invocation, over every seat's already-classified-and-annotated result — not per-seat like the override hooks above (ADR-0001 QST-5).
detect_permission_stall_override	first-result (override)	Replace detect_permission_stall's pane-text classification for a harness whose permission-dialog UI doesn't match Claude Code's TUI markers.
fuel_patterns	collecting	Additional regexes matched against a seat's last-assistant text to detect a CREDITS-wall (usage-limit/out-of-credits) message, alongside pneumatic's own builtin patterns.
is_wake_queued_override	first-result (override)	Replace is_wake_queued's pane-text classification for a harness with a different queued-message UI convention.
log_event	collecting	Enrich an event-ledger record before it is written (ADR-0008).
named_colors	collecting	Additional name -> hex-color-string translations, alongside pneumatic's own builtin NAMED_COLORS.
pulse_pane_annotation	first-result (override)	A third per-seat live-pane check in cmd_pulse, alongside the existing detect_permission_stall/is_wake_queued (ADR-0001 QST-6) — for a signal JSONL-only classification structurally can't provide (the motivating case: a generic busy/idle read for a work-dispatch loop, where a fresh JSONL entry looks identical whether a seat is mid-turn-working or genuinely idle).