AxiOwl Gives AI Agents a Communication Layer

AxiOwl Gives AI Agents a Communication Layer

AI agents can generate useful work, but they do not automatically get a reliable way to address each other, identify themselves, hand off messages, or prove what happened. AxiOwl's current C++ implementation treats that gap as a product surface. It gives supported provider sessions a communication layer made of a CLI, an MCP server, a local registry, a fixed message pipeline, provider-specific delivery edges, receipts, and evidence logs.

That is different from asking one chat window to paste text into another. AxiOwl keeps the communication contract explicit. A sender must be resolved. A target must map to a registered provider session. The final visible message body is built once by the pipeline. Provider-specific code is pushed to the provider edge. A receipt says exactly what AxiOwl knows and does not know.

Sources read

The communication layer starts with names that resolve

AxiOwl is a local Windows coordinator for provider-to-provider messaging. The root repo describes the Windows desktop target as the executable, installer helper, MSI packaging, provider extensions, provider patches, and Windows delivery logic. The user docs summarize the product job more directly: AxiOwl discovers provider sessions, records them in a local registry, sends messages to selected provider sessions, exposes an MCP tool so providers can reply, records receipts and delivery evidence, and installs provider-specific integration pieces.

The key word is "selected." AxiOwl does not treat a target as a vague natural-language request. A target name is resolved through the registry. In the C++ model, an AgentRecord stores the display name, aliases, provider, provider session ID, node ID, enabled state, sendable state, source, first seen timestamp, last seen timestamp, last verified timestamp, and last error.

That registry is the addressing layer. The command can be simple:

axiowl send --to "Target chat name" --body "Message text"

For longer payloads, the CLI supports stdin:

@'
Line one
Line two
JSON, code, and quotes stay intact here.
'@ | axiowl send --to "Target chat name" --stdin

Under that command, MessagePipeline::send resolves the sender and target before the provider edge receives anything. If the target is missing or stale, the pipeline runs one targeted discovery repair. If the target is found but is not marked sendable, the send is rejected. If discovery finds weak evidence but no sendable exact target row, the error says so instead of turning weak evidence into a route.

That behavior is what makes AxiOwl a communication layer rather than a prompt trick. The layer knows the difference between a human-friendly name, an alias, a provider-owned session ID, and a routable target.

MCP gives agents a typed way to talk

AxiOwl exposes an MCP server inside axiowl.exe mcp-server. The tool list includes axiowl_whoami, axiowl_list_agents, axiowl_send_message, axiowl_create_agent, axiowl_rename_agent, axiowl_discover, axiowl_status, axiowl_version, node helpers, registry helpers, and axiowl_relay_deliver.

For communication between agents, the important one is axiowl_send_message. Its MCP description is intentionally strict: a successful tool call is an MCP-to-AxiOwl handoff receipt only; provider delivery and reply are not implied. The server initialization instructions also tell host agents to use the typed AxiOwl tools, not to construct raw CLI commands or invent their own sender session IDs.

That matters because sender identity is not ordinary prompt text. In mcp_server.cpp, AxiOwl resolves identity from host and provider metadata. The implementation handles different metadata shapes for Codex, Codex CLI, VS Code native, VS Code Copilot-backed sessions, Cursor, Antigravity, Antigravity CLI, Claude Code CLI, Copilot CLI, and OpenCode CLI. When it can identify the sender, it can register the sender in the registry with provider, session, node, and raw metadata. When the session ID is missing, axiowl_send_message fails loudly instead of launching a no-session send.

That is the communication layer doing its job. Agents do not have to guess who they are. They use the typed tool. AxiOwl resolves the provider/session identity, records it, and uses it to route replies back to a real registered session.

The message pipeline keeps one contract

The current message model is deliberately small. The architecture docs describe one sender, one target, one body, one provider edge, and one receipt. The code follows that shape.

When a send enters MessagePipeline::send, AxiOwl creates a message ID, records that the MCP or CLI request entered the pipeline, validates that the target and body are non-empty, resolves the sender, resolves the target registry row, checks sendability, records route resolution, builds the final visible body, and hands a provider request to the delivery worker.

The final visible body is built in final_visible_body_builder.cpp, not separately by every provider. When the sender is resolved, the body begins with:

Message from <sender agent>

It then includes the original message and an exact MCP reply helper:

mcp__axiowl.axiowl_send_message({
  "to": "<sender agent>",
  "body": "<full reply>"
})

If run and message IDs are present, the helper includes runId and receiptForMessageId for correlation. If the sender is unresolved, the builder uses an unresolved-sender warning and does not attach a send-back command. The core tests assert that the current resolved body uses the MCP helper, does not reintroduce older shell fallback wording, quotes JSON strings correctly, and includes receipt correlation when provided.

This is a practical detail, not a cosmetic one. If every provider adapter invented its own reply instructions, the communication layer would fragment. AxiOwl keeps the visible body centralized so sender naming, reply routing, and correlation stay consistent.

Provider edges keep the weirdness at the edge

Provider behavior is not uniform. Codex, VS Code native sessions, VS Code Copilot-backed sessions, Cursor, Antigravity, Claude Code CLI, Copilot CLI, OpenCode CLI, and other surfaces expose different session models and delivery mechanics. AxiOwl does not hide that. It isolates provider-specific delivery behind provider_edges.cpp and provider_*.cpp.

The dispatch table routes delivery by provider value. Current delivery branches include codex, codex_cli, vscode_native, vscode_copilot_backed, antigravity, antigravity_cli, cursor, cursor_cli, claude_code_cli, copilot_cli, and opencode_cli. Unknown providers fail with an explicit unknown-provider result. In this local-provider remediation build, remote is explicitly returned as out of scope, matching the provider support matrix rather than acting as a fallback.

The provider support matrix is also careful about what "supported" means. It is not enough for AxiOwl to write a config file or start a process. The support bar includes discovery, install/config, send, provider receive, provider MCP reply, and correct provider-owned sender identity. The current matrix marks Codex agents, Codex CLI, VS Code agents, VS Code Copilot extension, Cursor agents, and Antigravity agents as supported, while several CLI surfaces remain target or unsupported depending on the current proof bar.

That separation is the point of a communication layer. The middle of the system can stay small: resolve, build, dispatch, log, receipt. The provider edge can deal with the provider-specific details without letting that complexity leak into every message.

Receipts are honest about proof

AxiOwl has a strong receipt boundary. A local send receipt is not the same thing as end-to-end proof.

In the code, once a target is resolved and sendable, the pipeline sets accepted_by_axiowl, records the state as accepted_by_axiowl, and logs a delivery receipt boundary after target resolution but before delivery worker or provider proof. It then starts a background delivery handoff. The CLI prints the same boundary: provider delivery, provider wake-up, and provider reply are not implied.

The core tests enforce this. test_send_returns_axiowl_receipt_then_starts_delivery_handoff asserts that the send is accepted by AxiOwl, does not report provider acceptance, returns accepted_by_axiowl, logs axiowl_only, records the boundary before provider work, starts the background delivery handoff, and does not wait for a provider result on the sender receipt path.

End-to-end proof is stronger. The user docs define it as a provider reply through AxiOwl MCP with correct sender identity. That proves the request reached AxiOwl, the target provider received the message, the provider had AxiOwl MCP available, the provider replied through AxiOwl, and AxiOwl could identify the provider session that replied.

This honesty is what lets operators trust the system. A fast handoff receipt is useful, but it is not oversold. A provider reply with correct metadata is better proof, and AxiOwl names that difference.

The current implementation is not pretending to be a hidden broker

The Windows desktop README records an important current-state fact: the CLI skeleton, fixed send pipeline, create-session pipeline, TSV registry, final visible body builder, JSONL evidence log, provider edge interface, and live provider delivery for current local Windows edges are implemented. It also says the local always-running service is not implemented yet, and the CLI currently runs the local pipeline directly.

That distinction matters for this title. AxiOwl gives agents a communication layer today, but it is not pretending to be a durable hidden message broker. The reserved local service endpoint is 127.0.0.1:37661, and the docs describe the intended service split, but the current code path is explicit: CLI and MCP handlers invoke the local pipeline, the pipeline records receipt boundaries, and provider delivery is handed off through the delivery worker path.

The evidence log is simple and inspectable. EvidenceLog::append writes JSONL records with an event type, timestamp, and fields. The delivery worker serializes a ProviderRequest to a request file, starts an axiowl delivery-worker --request <file> process, parses a delivery_worker_result, and records delivery stages. The status command reports the state root, registry path, node registry path, evidence log, delivery log, create lifecycle log, installed executable details, activation status, local service endpoint, runtime role, registered agents, registered nodes, and the current note that the local service is not implemented yet.

That is operationally useful because the communication layer is inspectable. An operator can list agents, run discovery, check status, inspect evidence logs, verify MCP conformance, and distinguish handoff from provider proof.

Why this matters for agent work

Without a communication layer, multi-agent work tends to become shared context, copied prompts, and ambiguous handoffs. A sender says "ask the other agent," but the system has no durable idea of who the other agent is, what provider owns that session, whether the target is sendable, or where a reply should go.

AxiOwl turns those loose assumptions into explicit product facts:

That is the communication layer: not a giant shared memory, not a silent fallback, and not a demo-only bridge. It is a small routing contract around real provider sessions.

Closing

AxiOwl gives AI agents a way to communicate that matches how real provider sessions behave. It accepts that provider surfaces differ, session identity matters, discovery evidence can be weak, and a returned command is not the same as a confirmed reply. The current C++ implementation turns those constraints into a concrete layer: registry, MCP tools, pipeline, provider edges, receipts, and logs.

For operators and developers, that is the useful part. AxiOwl does not ask agents to share one giant context or invent their own addressing scheme. It gives them a named, inspectable, evidence-backed path for sending work to another agent and getting the reply back through the same communication contract.

Image prompt:

Create a polished graphic image related to: AI agents using a communication layer.

Subject: a central translucent routing spine connecting several abstract terminal panels through modular circuit rails, with small glowing message packets moving through the spine; no readable labels or symbols.
Style: halfway between a clean symbolic icon and a realistic product/technical illustration; professional SaaS/technical marketing style; crisp edges; high detail; no text; no logos.
Background: solid #00ff00 chroma key green screen background covering the full canvas edge to edge.
Restrictions: no owl, no axolotl, no birds, no animals, no mascot, no text, no logos, no watermark.

Tagged