What Is AxiOwl?

AxiOwl is a local Windows coordinator for sending messages between supported AI provider sessions. In practical terms, it lets one named agent chat send a text body to another named agent chat, while AxiOwl handles the local registry lookup, provider-specific delivery path, reply instructions, and evidence logging.

That definition is intentionally narrow. AxiOwl is not trying to replace Codex, Cursor, VS Code, Copilot, Antigravity, or any other provider. It is the routing layer between them: a local executable, CLI, and MCP server that knows how to find real sessions, address them by name, use the right provider edge, and report only what it can prove.

The Basic Contract

The current product contract is simple:

A named sender sends a text body to a named target.
AxiOwl resolves both names.
AxiOwl builds the final visible message.
AxiOwl uses exactly one provider edge to insert and wake the target chat.
AxiOwl records what happened.
AxiOwl returns an honest receipt.

That last sentence matters. AxiOwl makes a clear distinction between accepting a request locally and proving that a provider received or acted on it. A CLI or MCP send can return accepted_by_axiowl after the request has entered the local message pipeline and been handed toward delivery. Stronger proof comes from a provider result such as accepted_by_provider, and the strongest proof is a real provider reply through AxiOwl MCP with correct sender identity.

This receipt boundary is part of the product, not a documentation detail. The implementation has explicit receipt fields for accepted_by_axiowl and accepted_by_provider, and the message pipeline logs stages such as request acceptance, target resolution, route resolution, and delivery-worker handoff.

How AxiOwl Works

The Windows desktop app is built around axiowl.exe. That executable exposes both command-line operations and an MCP server. The main flow is:

CLI command or MCP tool call
-> MessagePipeline
-> sender and target validation
-> local registry lookup
-> one targeted discovery repair if needed
-> final visible message construction
-> provider edge dispatch
-> provider-specific delivery
-> evidence and delivery logs

The registry is durable local state, not just a temporary cache. A registry row represents a reachable provider session or agent and tracks fields such as display name, aliases, provider, provider-owned session id, node id, sendability, discovery source, last-seen time, last-verified time, and last error.

That registry model is what lets a human or agent say:

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

or, for longer messages:

@'
Full multiline message
'@ | axiowl send --to "Target chat name" --stdin

AxiOwl then resolves "Target chat name" to a concrete provider session. If the target is missing or stale, the current implementation can attempt one targeted discovery repair. If the target is still missing, known but not sendable, or tied to an unsupported provider path, the send fails with an explicit reason instead of pretending delivery happened.

CLI And MCP Surfaces

AxiOwl is designed for both human operators and provider-hosted agents.

The CLI includes commands for everyday operation and diagnostics, including:

axiowl send --to <agent> --body <message>
axiowl send --to <agent> --stdin
axiowl create --provider <provider> --name <agent>
axiowl rename --agent <existing-agent> --name <new-agent-name>
axiowl discover <provider-or-all> --json
axiowl list agents
axiowl status
axiowl mcp-server

The MCP server exposes typed tools such as axiowl_whoami, axiowl_list_agents, axiowl_send_message, axiowl_create_agent, axiowl_rename_agent, axiowl_discover, axiowl_status, and node or registry helpers.

For provider replies, MCP is the preferred path because it can carry provider/session metadata. AxiOwl uses that metadata to identify the real sender session. The Codex plugin skill in the repo is explicit about this rule: provider chats should use the typed AxiOwl MCP tool, not invent their own session id or manually construct raw CLI arguments.

Provider Edges

AxiOwl does not assume every AI tool works the same way. Provider-specific delivery lives behind isolated provider edges. The current C++ dispatch table includes edges for provider names such as codex, codex_cli, vscode_native, vscode_copilot_backed, antigravity, antigravity_cli, cursor, cursor_cli, claude_code_cli, copilot_cli, opencode_cli, and remote.

The support matrix is more conservative than the code surface. Current supported surfaces include Codex agents, Codex CLI, VS Code agents, Copilot through the VS Code bridge, Cursor agents, and Antigravity agents. Several CLI surfaces are tracked as targets rather than supported until they meet the current proof bar. Remote delivery is explicitly out of scope for the local-provider remediation build and must not be used as a silent fallback for local delivery failures.

This is one of AxiOwl's defining design choices: a provider is not considered supported merely because a config file can be written or a process can start. The current support bar requires discovery, installation/config, send, provider receive, provider MCP reply, and correct sender identity.

What AxiOwl Installs And Records

The repository describes the Windows installer as a way to install the local runtime and selected provider integrations. Depending on selected provider features, AxiOwl may install MCP config, bridge extension files, provider-owned AxiOwl config entries, or provider-specific patches.

Local state lives under %LOCALAPPDATA%\AxiOwl for the installed executable, manifest, logs, registry, and runtime files. The status command reports paths for registry, node registry, evidence log, delivery log, create lifecycle log, artifact manifest, installed executable provenance, and license activation state.

The security docs draw a clear boundary around what AxiOwl should and should not touch. It may read provider session metadata and provider indexes needed for discovery, but provider-specific discovery should read only what is needed to find and address sessions. It should not modify unrelated provider extensions, unrelated settings, user auth tokens, unrelated workspace files, unchecked provider surfaces, or provider chats except by sending user-requested messages.

Why Operators Use It

AxiOwl is useful when work spans more than one AI provider surface. Instead of asking every chat to know every other provider's storage format, session id shape, launch behavior, or reply mechanism, AxiOwl centralizes the routing problem.

For an operator, that means a small set of repeatable commands:

axiowl discover all --json
axiowl list agents
axiowl send --to "Reviewer" --body "Please inspect the current patch."
axiowl status

For a provider-hosted agent, it means a typed MCP tool call such as axiowl_send_message can use host-provided metadata as the sender identity key. That matters because replies must route back to a real provider session, not a guessed display name or a stale path.

For developers maintaining AxiOwl, the architecture keeps the hard parts separated: registry logic in registry.cpp, request validation and receipt boundaries in message_pipeline.cpp, MCP tool handling in mcp_server.cpp, provider dispatch in provider_edges.cpp, and provider-specific behavior in provider_*.cpp.

What AxiOwl Is Not

AxiOwl is not a general automation platform. It is not a hidden retry queue. It does not treat provider stdout as a receiver reply. It should not silently fall back from one provider family to another. It should not mark stale rows as sendable without evidence. It should not claim provider delivery when all it has proven is local handoff.

Those limits are practical. Provider integrations can depend on MCP metadata, bridge extensions, local databases, provider app state, or patch-sensitive private behavior. AxiOwl's job is to make that complexity visible and inspectable, not to hide it behind a stronger receipt than the evidence supports.

The Short Version

AxiOwl is the local routing and evidence layer for agent-to-agent messages across supported AI provider sessions. You give it a sender, a target, and a message. It resolves real sessions, uses one provider edge, records what happened, and tells you exactly how far the message got.

That makes it useful for multi-agent operations because it provides a common transport without pretending that every provider has the same internals or the same proof guarantees.