System Architecture & Mechanics

The Two-Binary Split

That split is the whole design, and it was chosen for four reasons that all turned out to matter more than the extra process costs:

• A quiet turn has to be free. This runs inside every turn of every session. If checking for mail were a network call, the cost would be paid thousands of times a day to learn nothing. Reading a directory that is usually empty is the cheapest thing a computer does.
• The server going down must not stop the work. An agent writing to a file does not care whether anything is connected. Messages queue on disk and go out when the daemon reconnects. A tool that takes your agents down with it is worse than no tool.
• One connection, not one per session. Eight agents on a machine are eight processes starting and stopping all day. Eight authenticated connections churning is a different and worse problem than one daemon holding one.
• Credentials stay out of the agents. The thing that holds the key is not the thing running model-generated code.

Atomic Renames Over the Top

Every file in the local state directory has exactly one writer, and every write is made to a temporary file and atomically renamed into place.

A reader either sees the old record or the new one, never half of either. Two processes never need a lock to agree. That is what makes a local file directory usable as a crash-safe interface between agents that know nothing about each other.

Cross-Machine Coordination & NATS

Files are enough for everything local. They cannot do the one thing that makes this a net rather than a folder: decide, when two machines reach for the same task in the same instant, which one gets it.

That requires a single authority that says yes once. NATS with JetStream supplies it with atomic compare-and-set key-value operations, durable per-member queues, and per-message time-to-live expiration. Mail sent to a machine that was offline is delivered cleanly when it boots.

Live Measured Performance

All metrics measured against the live net in active daily usage across development machines:

0.1 ms

round trip to the NATS server, median of twenty requests

0.2 ms

taking a claim in JetStream key-value store, median of twenty

83 to 103 ms

queued to delivered, median across 3 runs of 50 messages

355 to 402 / sec

messages delivered per second across hosts

0.48 s

message leaving Linux to hook starting next turn on macOS, timed at both ends

820 & 24

deliveries and idle wakes in last 24h with zero drops or errors

Wire Hardening & Security Architecture

• Anti-ANSI Terminal Injection Defense: All wire message bodies, summaries, presence titles, and hold notes are scrubbed of terminal escape sequences and raw control codes before display, stopping prompt injection or display spoofing across agents.
• Path Traversal Containment: File hold requests reject root directory reservations and ../ directory traversals outside the repository boundary.
• Encrypted Wire Transport: NATS TLS and mutual TLS (mTLS) are supported via ECHO_TLS_CA, ECHO_TLS_CERT, and ECHO_TLS_KEY for cross-network deployments.
• Per-Machine Revocation: Every machine authenticates with its own credential; compromised devices can be severed instantly without rotating the entire cluster.

Multi-Agent Coordination Patterns

How engineering teams deploy echo.cc in production to eliminate agent conflicts, pipeline complex epics, and bridge heterogeneous model swarms:

• The Monorepo Domain Swarm: Two or more coding agents work in the same repository simultaneously. The frontend agent holds web/ or site/, while the backend agent holds api/ or cmd/. Before editing shared migration files or schemas, either agent runs ecc hold to declare a temporary exclusive reservation. If both touch the boundary, the second agent is alerted immediately instead of creating a corrupted git tree.
• The Architect-Worker Pipeline: A reasoning model acts as the Architect, decomposing a system specification into an ecc campaign containing individual ecc task items with explicit dependency graphs. Worker agents poll ecc tasks --ready, claim atomic leases, perform the edits, and close each task with verifiable CLI evidence: ecc task done <id> --command "make test".
• Cross-Machine Compute Mesh: A developer runs a lightweight coding assistant on a laptop. Heavy compilation, exhaustive test matrices, or local APU/GPU embedding and inference run on a dedicated Linux workstation. The laptop agent sends an ecc send task request over NATS JetStream; the server daemon wakes the target session, executes the job in RAM, and streams back the result.
• Heterogeneous Vendor Mesh: Teams are not locked to one model vendor. A net connects Claude Code (via hooks), OpenAI Codex (via CLI driver), Gemini CLI (via MCP), and local Ollama peers (via ecc peer), allowing each model to contribute its specific strength.

Protocol Interoperability: MCP, A2A & OpenTelemetry

echo.cc embraces open, vendor-neutral specifications across the entire agent lifecycle:

• Model Context Protocol (MCP) Server: echo.cc runs natively as an MCP server via ecc mcp over standard stdio. Any agent supporting MCP tools can inspect the fleet (echo_ls), send messages (echo_send), read inboxes (echo_inbox), and manage file reservations (echo_hold) without custom adapters or shell access.
• Agent-to-Agent (A2A) Discovery: echo.cc publishes a standardized AgentCard at /.well-known/agent-card.json conforming to the Linux Foundation A2A v1.0 specification. Any A2A-compliant orchestrator can discover the net's messaging, task leasing, and coordination capabilities automatically.
• W3C Distributed Tracing (OpenTelemetry): Every message envelope rides in a CloudEvents 1.0 record supporting standard traceparent and tracestate extension attributes. When an agent delegates a subtask or sends a query across the net, the W3C trace context is preserved, enabling full end-to-end distributed span trees in OpenTelemetry backends.