Agent Bridge

Problem & Operational Bottleneck

Terminal-based AI agents and CLI copilots typically operate in isolated session silos. Passing state, sub-task delegations, and execution context between disparate agent runtimes required cumbersome manual copying or fragile temporary files.

Constraints & Requirements

• Zero cloud service dependencies—must run entirely offline and locally
• A structured primary transport with tmux available only as a compatibility fallback
• Python standard-library-only runtime dependencies
• Bounded messages, inboxes, retries, and explicit acknowledgement states

System Architecture & Ownership

Designed a Python CLI and protocol with SQLite-backed messages and tasks, Unix-domain socket inbox delivery as the primary transport, and explicit tmux prompt injection as a fallback. Runs, policies, delivery states, acknowledgements, and task claims remain durable locally.

Engineering Decisions & Rationale

• Used SQLite for the durable queue and atomic task claims instead of introducing a hosted relay.
• Made Unix-domain sockets the structured primary delivery path and kept tmux injection explicit and optional.
• Published under the permissive MIT license on GitHub to foster community adoption and extensible tooling integration.
• Kept runtime dependencies within the Python standard library.

Reliability, Retries & Safeguards

• Messages are stored before delivery and claimed atomically so concurrent workers cannot inject the same message twice.
• Sender-scoped idempotency, bounded payloads, inbox limits, rate limits, and reply-hop limits constrain coordination loops.
• Queued, held, delivered, acknowledged, failed, and refused outcomes remain distinct and inspectable.

Reflection & Engineering Learnings

The implementation showed that SQLite plus local sockets can provide durable, inspectable coordination while keeping provider-specific adapters outside the core protocol.