How to Use AxiOwl Without Losing Track of Which Agent Is Which

When several AI coding tools are open at once, names stop being enough. A chat title can be reused. A provider can expose more than one session. A stale session can still look familiar in a list. AxiOwl is built around that reality: it does not treat a friendly agent name as the whole identity.

AxiOwl keeps track of agents through a durable local registry that maps a human-readable name to a provider, a provider-owned session ID, a node, aliases, timestamps, and sendability state. That registry is the practical difference between "send this to the chat called Backend Fix" and "send this to the exact provider session that AxiOwl has evidence for."

Start With the Registry, Not Memory

The safest habit is to list known agents before sending:

axiowl list agents

In the current AxiOwl design, the normal agent list is meant to show enrolled sendable targets, not every raw thing discovery has ever seen. The distinction matters. The discovery plan says it plainly:

discovered != enrolled
enrolled != live
live != replied

That is the core operating model. Discovery can find provider facts. Enrollment decides whether those facts become usable targets. A live send receipt proves AxiOwl accepted work. A provider reply over MCP is stronger proof that the target received the message, processed it, and replied with usable sender identity.

What an AxiOwl Agent Row Actually Means

The current registry model stores agent rows with fields such as:

display_name
aliases
provider
provider_session_id
node_id
enabled
sendable
source
first_seen_at
last_seen_at
last_verified_at
last_error

That may look like implementation detail, but it is exactly what keeps operators oriented. display_name is what you type. provider tells AxiOwl which delivery edge to use. provider_session_id is the provider-owned handle that anchors the row. node_id separates local and remote contexts. sendable prevents a discovered but unproven target from being treated like a working inbox.

This is also why a good AxiOwl workflow does not rely on a mental list of chat titles. The registry is the working map.

Use Names for Humans and Session IDs for Proof

AxiOwl lets operators address targets by name:

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

For longer messages, use stdin:

@'
Message text that can include multiple paragraphs, quotes, lists, or code.
'@ | axiowl send --to "Target chat name" --stdin

The name is convenient, but the send path resolves it through the registry. Under the hood, AxiOwl needs the target row, the provider, and the provider session ID before it can dispatch through provider-specific code. The current CLI supports provider surfaces such as Codex, VS Code native, VS Code Copilot-backed, Cursor, Antigravity, Copilot CLI, Claude Code CLI, and OpenCode CLI, but the support matrix distinguishes supported surfaces from target or experimental surfaces.

That distinction is useful when multiple agents have similar names. If a row is known but not sendable, AxiOwl should reject the send as a target that is known but not sendable. If a target is missing, the message pipeline can run a targeted discovery repair once, then report whether the target was still missing or whether evidence was found without a sendable exact target row.

Name Agents So the Registry Stays Readable

The product does not force a naming scheme, but operators should use one. A good agent name should identify the work, the surface, and enough context to avoid collision.

Weak names:

Backend
Test
Fix this
New chat

Better names:

Backend API run-log reader
Codex CLI provider smoke test
VS Code native frontend cleanup
Cursor patch verification
Antigravity installer check

The point is not decoration. AxiOwl can hold aliases and provider session IDs, but human operators still choose targets by visible names. If two rows look interchangeable to a person, the risk has already moved upstream.

Do Not Confuse Discovery With Delivery

AxiOwl discovery modules find provider sessions and merge facts into the registry. The developer docs describe discovery as provider-specific and conservative: it can add newly found sessions, refresh last-seen fields, enrich manual rows, downgrade stale auto-discovered rows when proof disappears, and repair a missing target once during send.

It should not silently convert stale rows into sendable rows or hide provider delivery failures.

That means a clean workflow looks like this:

1. Run discovery for the provider surface you care about when the list looks stale.
2. Review the listed agents before sending.
3. Send by the intended display name.
4. Treat accepted_by_axiowl as a handoff receipt, not proof that the provider acted.
5. Treat a reply through AxiOwl MCP with correct sender identity as the stronger end-to-end signal.

The current user docs make this boundary explicit. accepted_by_axiowl means AxiOwl accepted the message and handed it to the delivery layer. It does not prove the provider displayed or processed the message.

Let MCP Identify the Sender

Agent-to-agent work gets confusing fast if replies do not identify their source correctly. AxiOwl's current architecture puts sender identity in the message flow:

MCP tool or CLI command
  -> CLI/MCP handler
  -> MessagePipeline
  -> validate target/body/sender
  -> resolve sender identity
  -> resolve target registry row
  -> provider_edges dispatch

For provider replies, AxiOwl prefers MCP because the provider can include provider/session identity metadata. The developer docs define the sender resolution order as provider-owned MCP metadata first, then an explicit provider session ID matching a registry row, then an explicit sender address or alias, then targeted discovery repair.

That is a practical safeguard. If a reply only says "from Backend" and there are several plausible Backend sessions, AxiOwl should not guess. Correct sender identity is part of the support bar for provider surfaces.

Know Which Provider Surface You Are Addressing

Some tools expose more than one surface. VS Code native chat and VS Code Copilot-backed chat are different provider surfaces in the registry model. Copilot in VS Code and Copilot CLI are also not the same thing. The provider support matrix separates these surfaces because delivery method, installer action, metadata requirements, and risk differ.

For example, a registry row might identify a provider as:

vscode_native
vscode_copilot_backed
codex
cursor
antigravity
claude_code_cli
opencode_cli

That provider value is not cosmetic. It controls which provider edge receives the delivery request. If you are debugging a confusing send, inspect whether the row points to the surface you actually meant.

Use Manual Registry Entries Carefully

The CLI includes a manual registry path:

axiowl registry add-agent --name <agent> --provider <provider> --session <provider-session-id> [--node <node>] [--source <source>]

Manual rows can be useful when an operator has real provider-session evidence. They are also easy to misuse if the session ID is guessed or stale. The registry exists to keep routing exact, so manual additions should preserve that standard: known provider, known session, known node, and a name that a human can recognize later.

For stale or incorrect entries, the CLI also includes a scoped removal path requiring a provider or session constraint:

axiowl registry remove-agent --name <agent> --provider <provider>

That shape is intentional. Removing by name alone would be too broad when multiple rows or aliases can exist.

A Practical Operator Checklist

Use this checklist when you have many agents open and the target is easy to confuse:

1. Run axiowl list agents.
2. Confirm the visible name is specific enough.
3. Confirm the provider surface is the one you intended.
4. Prefer stdin for multiline or structured messages.
5. Watch the receipt boundary: accepted_by_axiowl is not the same as a provider reply.
6. When a reply matters, require the target to answer through AxiOwl MCP.
7. Rename or clean up ambiguous rows before they become operational habits.

The Real Goal: Fewer Guesses

AxiOwl is not just a message launcher. It is a coordinator that keeps names, aliases, provider sessions, nodes, sendability, delivery receipts, and MCP sender identity in one routing model. That model exists because real AI-agent work is messy: chats are renamed, provider state gets stale, and several tools can expose similar-looking sessions.

The practical way to avoid losing track is to let AxiOwl's registry do its job. Use human-readable names, but verify them through the registry. Treat discovery as evidence, not proof. Treat MCP replies with correct sender identity as the strongest confirmation. When those habits are in place, sending to "the right agent" becomes an inspectable routing decision instead of a guess.