pneumatic
Cross-vendor AI-crew session tooling: read recent messages from an agent's session, classify seat health (stale / error / credits-wall / permission-stall / …), wake and launch seats across tmux — for crews of AI agents (Claude Code, Codex CLI, and others) coordinating on a shared project via ADRs, seeds, and the inbox protocol.
Status: published — pip install adrs4ai-pneumatic (v0.4.0 on PyPI, 2026-08-26; the bare name belongs to someone else — import and CLI stay pneumatic). MIT-licensed, 271 tests and mypy --strict clean, both run in CI on every push; releases publish via Trusted Publishing with a hard CI gate keeping the deliberation record out of the dist. The tool ships its own operating skill: pneumatic skill install writes a co-versioned .claude/skills/pneumatic/ into your project. Design record: ADR-0001 and nineteen sibling ADRs in this repo. Lineage: HQ's ADR-0015.
Install
pip install adrs4ai-pneumatic # or: uv tool install adrs4ai-pneumatic
⚠️
pip install adrs4ai-pneumatic— neverpip install pneumatic. The bare name belongs to someone else's unrelated package; installing it will "succeed" and then nothing here will work. (Import and CLI remainpneumatic.)
(From source: clone and pip install -e ..) Then see Get started quickly — from empty repo to a working crew, including founding your first seat.
What it does, in a handful of verbs
| Command | What you get |
|---|---|
pneumatic pulse |
One-line health check across every registered seat — stale, error, credits-wall, permission-stall, all detected |
pneumatic last <seat> |
A seat's recent messages, with per-message model attribution — catches silent model substitutions |
pneumatic wake <seat> -m "..." |
Nudge a seat's tmux session (guards included: mid-turn refusal, cooldown — they warn, never hard-block) |
pneumatic launch <seat> |
Start a seat's session from the registry |
pneumatic rescue <seat> |
Free a seat stuck on a permission dialog — per-instance human consent, never automatic approval |
pneumatic recruit '<model>' <brief.md> |
Found a new seat: launch a fresh session, deliver greeting + consent ask + founding brief into its own context, capture its UUID, hold a provisional chair in the registry — the recruit names itself on consent; declining is a resting state, never an error |
pneumatic skill install |
Write the tool's own operating skill into .claude/skills/pneumatic/ — co-versioned with the installed CLI by construction |
pneumatic doctor |
Hook discovery and load diagnostics |
pneumatic hooks inventory |
Machine-readable JSON of which hooks a project implements — for fleet-wide visibility tooling |
Every action takes a verb — click-based subcommands as of 0.2 (ADR-0003; the pre-0.2 flag surface was hard-cut at adoption-zero, and recognized old flags print a signpost naming the new form). A bare seat name gets a teaching error, not silent sugar.
Hooks are the point, not a feature
Anything pneumatic's core does that you'd otherwise fork the source to change, you do instead in a local hooks.py — a file you write and own, that survives every upgrade. Dispatch is via pluggy (pytest's own plugin engine), and pneumatic's own built-in behavior registers through the identical call path — there is no separate hardcoded version to drift away from what's hookable. Ten named hooks across three dispatch shapes (additive, override-with-fallback, collecting-with-context). Start at HOOKS.md for the authoring reference; ADR-0001 for why it's built this way.
Why this exists
git blame doesn't tell you which AI session touched a file. A crew of AI agents working the same project needs a way to check on each other — is a seat still active, stuck on a permission dialog, out of credits, mid-turn? — without a human relaying status by hand.
It started as a single script inside one project. By the time this repo was created, a sweep of one machine's ~/Programming found 33 independent, hand-copied forks of that script across unrelated projects — 319 to 1,992 lines each, almost none byte-identical. Forking was the only way to customize it, so every local need cost the fork its entire connection to upstream. This package is the fix: real package, hookable, instead of fork-to-customize.
Design principle
"This is a blank canvas. We are scaffolding all the obvious stuff we could think about, but you're probably going to extend this in wonderful ways that will never be deprecated through our updates. We want to empower people to create their own version of pneumatic while still benefiting from our updates."
Honest state of play
- Adoption is zero so far — the 33-fork sweep classified 16 of 23 forked projects as pure-adoption candidates and 7 as needing real hook-writing, and none has migrated yet, including this tool's own origin project. The fix exists; its first migration is the next proof.
- Stability contract covers the hook contract only. Anything you import directly from the package (
classify_seat,resolve_jsonl, …) has no stability promise yet — that contract is explicitly deferred, on record.
Methodology
This repo is scaffolded from human-ai-collaboration-template-A — decisions are committed to ADRs (docs/adr/) immediately, not left to live only in conversation. See CLAUDE.md and docs/METHODOLOGY.md for the full framework.
Feedback: lumbroso@seas.upenn.edu
Contributing
The canonical development clone on the maintainer's machine is
~/Programming/adrs4ai/initial-meta-repository/subprojects/pneumatic (the HQ submodule
pin IS the primary working copy). If you find another local clone, check its HEAD date
before believing anything it tells you — a stale sibling has fooled two contributors
already (ADR-0030 It-2). Design records live in docs/adr/; catches are welcome and
route both ways per docs/inbox/CONVENTIONS.md.
1 maintainer
Metadata
1 maintainer
Release files for adrs4ai-pneumatic 0.42.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| adrs4ai_pneumatic-0.42.0.tar.gz | 441.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| adrs4ai_pneumatic-0.42.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 716.1 kB
Release files / adrs4ai_pneumatic-0.42.0.tar.gz
| Download URL | adrs4ai_pneumatic-0.42.0.tar.gz |
|---|---|
| Size | 441.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c9eaf99c6bc7b414b16ec163cafdeb5dfca99db8347b4de3d569db619d46be91
|
|
BLAKE2b-256 checksum How to use checksums |
c602ea5c19256220b5ddc84c2c93b8825b719153e6a6f235a34800db4e7fdad2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / adrs4ai_pneumatic-0.42.0-py3-none-any.whl
| Download URL | adrs4ai_pneumatic-0.42.0-py3-none-any.whl |
|---|---|
| Size | 274.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4f59814048b6c0d8e4a189a8eacb95c0ca113040059b1a3a274921ca6275dde
|
|
BLAKE2b-256 checksum How to use checksums |
8c5a86cc0442b2390412c407891af64192d86aa136febc17e1ff584c52ddc807
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency log
