Pair Mailbox: Autonomous Multi-Agent Coding Protocol for AI-CLI

Task

Terminal-based coding agents (Claude Code, OpenAI Codex, OpenCode) suffer from context drift when tackling complex tasks: a lone model gradually loses system invariants, spinning into endless syntax fixes while accumulating hidden regressions. Developers are forced to manually ferry diffs between generator and reviewer models. The objective was to engineer an orchestration protocol and lightweight local server with zero external dependencies, uniting two independent CLI processes into a deterministic pair to reach a verified Pull Request.

Solution

Pair Mailbox establishes a strict deterministic protocol via local IPC and file locking. The core Single-Writer Rule permits only the "Writer" agent to modify workspace files, while the "Reviewer" operates in strict Read-Only mode, submitting structured patch advisories. Every inter-agent message, diff, and test run is recorded into an append-only audit log. A dedicated supervisor monitors CLI process lifecycles, re-spawning hung agents and immediately halting the pipeline if sensitive environment files are touched.

Multi-Agent State Protocol

       ┌────────────────────────┐
       │     Task Ticket        │
       └───────────┬────────────┘
                   │
                   ▼
┌──────────────────────────────────────┐       Structured Patches      ┌──────────────────────────────────────┐
│            Writer Agent              │ ────────────────────────────► │           Reviewer Agent             │
│   (Write Authority: Files & Tests)   │ ◄──────────────────────────── │      (Read-Only: Architecture Audit) │
└──────────────────┬───────────────────┘       Critique & Approval     └──────────────────┬───────────────────┘
                   │                                                                      │
                   │                                                                      │
                   ▼                                                                      ▼
       ┌──────────────────────────────────────────────────────────────────────────────────────┐
       │                     Immutable Audit Mailbox Log (Single-Writer Guard)                │
       └──────────────────────────────────────────┬───────────────────────────────────────────┘
                                                  │
                                                  ▼ All Tests Pass & Approved
                                     ┌─────────────────────────┐
                                     │  Clean Pull Request     │
                                     └─────────────────────────┘

Autonomy Guardrails

Mode	Agent Behavior	Human Engineering Boundary
observe	Generates proposed diffs and critique	Explicit manual sign-off on every action
semi	Autonomous edits and unit test runs	Human approval before migrations, secrets, or deploys
auto	100% autonomous from issue to green PR	Final merge button in GitHub

Key Features

• Single-Writer Rule: Rigid role segregation eliminates state races, ensuring absolute workspace integrity.
• Append-Only Audit Mailbox: Immutable logging of all proposed diffs, test executions, and reviewer critique packets.
• Granular Autonomy Levels: Support for observe (human gates), semi (pause before migrations/secrets), and auto (end-to-end task-to-PR cycle).
• Process Supervision & Circuit Breakers: Background watchdog that re-spawns failed CLIs and prevents infinite model repair loops.
• Zero External Dependencies: Built exclusively on standard Node.js/TypeScript runtime primitives without external frameworks.

Technologies

Architecture and Deployment

The pairing protocol demonstrated 100% autonomous delivery of engineering tickets: parsing requirements, implementing isolated modules, satisfying independent architectural reviews, passing test suites, and opening clean, structured Pull Requests in GitHub.

← Back to all projects