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: real and installable, today, from source — 0.1.0, MIT-licensed, 47 tests and mypy --strict clean, both run in CI on every push. The PyPI distribution name will be adrs4ai-pneumatic (the bare name belongs to someone else; import and CLI stay pneumatic) — not yet published to PyPI, deliberately: that's its own open decision. Design record: ADR-0001, eight iterations deep, all seven design questions answered (the last, a narrow message_filter hook for cmd_last's message-selection step, designed and awaiting implementation). Lineage: HQ's ADR-0015.

Install

git clone https://github.com/ADRs4AI/pneumatic
cd pneumatic
pip install -e .          # editable install; CLI entry point included

A python -m build --wheel + clean-venv install has been verified working end to end. When the PyPI decision lands: pip install adrs4ai-pneumatic.

What it does, in six commands

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. Nine 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