Get started quickly

From nothing to a working AI crew — installed tool, coordination substrate, your first founded seat, and every seat one click away in VS Code.

1. Install the tool

pip install adrs4ai-pneumatic     # or: uv tool install adrs4ai-pneumatic
pneumatic --help

The import and CLI are pneumatic; only the PyPI distribution carries the adrs4ai- prefix. ⚠️ Never pip install pneumatic — that bare name is someone else's unrelated package; it installs fine and then nothing here works (remedy: pip uninstall pneumatic && pip install adrs4ai-pneumatic).

2. Copy the coordination substrate from the template

Pneumatic reads and writes a crew's shared files — the seat registry, the inbox, the just recipes. The canonical starter set lives in the human-ai-collaboration-template:

git clone --depth 1 https://github.com/ADRs4AI/human-ai-collaboration-template-A /tmp/hact
cp -R /tmp/hact/docs/inbox  your-project/docs/inbox    # registry + protocol docs
cp /tmp/hact/justfile       your-project/justfile      # brief/wake/launch recipes

That gives you docs/inbox/agent-sessions.json (the crew registry), the inbox protocol (INBOX-PROTOCOL.md, ONBOARDING.md, CONVENTIONS.md, ENCODING-MAP.md), and the coordination recipes pneumatic assumes. Commit them.

3. Install the operating skill

cd your-project
pneumatic skill install

Writes .claude/skills/pneumatic/ from the installed package — the judgment layer your AI seats operate the tool with, co-versioned with the CLI by construction. Re-run after upgrading.

4. Found your first seat

Write a founding brief (what the seat is for, addressed "to: the new seat" — the name is theirs to choose), commit it, then:

just recruit 'claude-fable-5[1m]' docs/inbox/founding-brief.md --watch 30
# (thin shim over: pneumatic recruit — same arguments)
# The model spec carries bracket variants: '…[1m]' requests the 1M-context
# variant and rides the whole founding (passed to `claude --model` verbatim).
# ALWAYS quote the spec — unquoted [1m] is a zsh glob and dies in the shell.

Pneumatic launches a fresh session in tmux, delivers greeting + consent ask + your brief into the new seat's own context, captures its session UUID, and holds a provisional chair in the registry. The recruit reads, deliberates, and — on consent — registers itself: alias, display name, color, all its own. Declining is a legitimate answer (exit 20, a resting state, never an error). --watch reports the registration live; its expiry means "still deliberating," nothing more.

5. Operate the crew

just launch <alias>        # attach to a seat's tmux session (or start it)
pneumatic pulse            # per-seat health: OK / STALE / ERROR / CREDITS / PERM-STALL / …
pneumatic last <alias>     # a seat's recent messages, with per-message model attribution
pneumatic wake <alias> -m "your brief 1010 awaits — go"   # short signal; the brief is the letter
pneumatic rescue <alias>   # when a seat is stalled on a permission dialog

The guards (cooldown, mid-turn, long-message) refuse loudly and are right — see the operating skill for the judgment layer, and the generated verb reference for every flag and exit code.

6. See every seat in VS Code

Install the Terminals Manager extension, then:

pneumatic-vscode-terminals   # generates .vscode/terminals.json from your registry

Now Terminals: Run opens every seat as a named, color-coded terminal attached to its tmux session — the whole crew visible in one window. Re-run after the registry changes. (Ships in the same package as a contrib console script — pneumatic --help won't mention it, by design; see the README's contrib section.)

Where to go next

• The operating skill — wake etiquette, health-state reading, rescue consent, crew rituals
• Hooks — extend behavior via a local hooks.py, never a fork
• Ledger charter — the rules for what the crew's mirror records