How Building Blocks Connect

Every building block works alone. When peers are present, they discover each other and compose — no tight coupling required.

Integration in Practice

These integrations follow the same pattern: check if a peer is present, read its state, act accordingly. If the peer is absent, the tool works fine without it. Solid lines are shipped; dashed cards show planned integrations that follow the same pattern.

Biff → Vox

Biff speaks /wall broadcasts and incoming messages aloud when Vox is installed.

Checks for .vox/config.md (L0), finds the vox binary on PATH (L1), spawns vox unmute as an async subprocess. Extracts emoticons from wall text and maps them to voice vibes. --once deduplicates fan-out across sessions.

Biff → Lux

Biff renders a live session dashboard in Lux — unread messages, active sessions, wall broadcasts.

Checks if the Lux socket exists (L0), imports LuxClient (L2). Renders a typed element tree every 5 seconds with smart patching — update() when structure is unchanged, show() for structural changes. Returns None if Lux isn’t running.

Quarry → Ethos

Quarry tags every document chunk with the active agent’s identity for scoped memory retrieval.

Walks up from CWD to find .punt-labs/ethos/config.yaml, reads the agent handle, and passes agent_handle into the embedding pipeline. Session transcripts captured before context compaction are tagged to the current agent. If Ethos isn’t configured, chunks are unscoped.

Z Spec → Lux

Z Spec displays specifications, type-check results, and model-check traces as interactive tabbed dashboards in Lux.

Imports punt_lux.protocol (L2) to build typed element trees — TabBar, Table, CollapsingHeader, Markdown elements. Five tabs: Spec, Fuzz, ProB, Partition, Audit. Falls back to text output when Lux is absent.

Ethos → Vox

An identity’s voice extension tells Vox which voice to use.

Ethos stores a voice_id extension in ~/.punt-labs/ethos/identities/<handle>.ext/vox.yaml. The SessionStart hook reads it and sets the session voice. If no binding is set, Vox uses its provider default.

Beadle → Ethos

Beadle resolves which email identity to send as from the Ethos session roster.

MCP tools whoami and switch_identity read the Ethos session roster and identity files. Per-identity email config stored separately in ~/.punt-labs/beadle/identities/. Supports multiple identities in one session.

How It Works

Every integration above follows the same four-step check. This pattern is the same whether the caller is a Python library, a shell hook, or an MCP tool — the checks are filesystem operations that any language can perform.

Presence — Is the peer's config or socket present? [[ -f ".vox/config.md" ]]

Discovery — Is the peer's CLI on PATH or its MCP tools available? command -v vox

State — What is the peer configured to do right now? grep '^speak:' .vox/config.md

Act — Use the peer, or skip if absent or disabled.

If any step fails, the tool proceeds without the peer. No error, no warning — just the tool working as if the peer doesn't exist. This is the degradation rule: every integration must be an enrichment, never a dependency.

Composable Axes

Building blocks compose along four independent axes. Any subset works. Full composition is the richest experience, but each axis degrades independently.

Domain WHAT — subject knowledge Z Spec, PR/FAQ, Use Cases

Identity & Workflow WHO & HOW — identity, roles, delegation contracts Ethos

Audio HOW — spoken delivery and ambient music Vox

Visual HOW — diagrams, dashboards, interactive applets Lux

Six Integration Layers

The four-step discovery pattern maps onto a layered model. The first four layers use only filesystem conventions and shell commands — any tool can participate, not just ours. The last two layers add tighter coupling for Punt Labs tools only.

Universal tier — open to any tool

These layers use filesystem checks, CLI availability, hook events, and shared config files. A bash script can integrate at all four layers with test -d, command -v, grep, and sed. No imports, no libraries, no shared code.

L0 Presence Sentinel file or socket check — [[ -f ".vox/config.md" ]]

L1 Discovery CLI on PATH or MCP tools available — command -v vox

L2 Events PostToolUse / PreCompact hook matchers trigger shell scripts on peer actions

L3 State YAML frontmatter in shared config files — readable by any language

Enhanced tier — Punt Labs tools

Tighter integration for our own tools. Every feature at these layers must fall back to universal-tier behavior when the shared library or peer is absent.

L4 Library Shared Python helpers for peer discovery, state reading, event emission

L5 Orchestration Agent-level prompt coordination — one tool shapes Claude's behavior for another

Shell Hooks as Integration

Shell hooks are first-class participants in this model. A PostToolUse hook is a bash script triggered when a tool call completes. That script uses the same four-step discovery pattern: check the sentinel directory (L0), verify the CLI (L1), read state (L3), and act. The Biff → Vox integration above is entirely a shell hook.

This is by design. The integration standard uses YAML frontmatter (parseable with grep), sentinel directories (checkable with test -d), and CLIs (discoverable with command -v) specifically so that shell scripts can participate at the same level as Python code. The universal tier is universal because it requires no runtime beyond a POSIX shell.