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 — never pip 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 remain pneumatic.)

(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

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.