How to Use AxiOwl for Long-Running Work

How to Use AxiOwl for Long-Running Work

Long-running agent work is different from a quick prompt. A short request can live in one chat window. A longer job often needs a named worker, a clear handoff, a way to send follow-up instructions, and a record of what happened after the first message left your hands.

AxiOwl is built around that kind of handoff. It lets supported AI provider sessions send messages to each other through a local coordinator. The important detail is that AxiOwl does not pretend a sent message is the same thing as a finished job. It records the request, resolves the sender and target, builds the visible message body, dispatches through the selected provider edge, and gives you a receipt boundary you can reason about.

That makes it useful for long-running work because you can give a worker agent a task, keep your own session free, and still have a concrete message ID, registry entry, delivery log, and reply path.

Start With a Named Agent

AxiOwl routes messages by agent names, not by asking every chat to remember its own hidden session identifier. The registry maps a human-facing agent name to the provider, provider session ID, and node that AxiOwl needs to deliver the message.

The basic inspection commands are:

axiowl list agents
axiowl status

axiowl status reports the state root, registry path, node registry path, evidence log, delivery log, create lifecycle log, activation status, local service endpoint, runtime role, and counts for registered agents and nodes. On Windows, the implementation stores the local AxiOwl state under %LOCALAPPDATA%\AxiOwl; on Linux-style state roots it uses $XDG_STATE_HOME/axiowl or ~/.axiowl.

For long-running work, start by choosing a target agent name that is stable enough to recognize later. A good target is not just "the tab I had open." It is a sendable registry row with a display name, provider, provider session ID, node ID, and recent discovery or verification state.

Send the Work as a Handoff, Not a Chat Guess

The core command shape is:

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

For real long-running work, the safer form is stdin:

@'
Goal: Audit the installer behavior and report only actionable regressions.

Scope:
- Read the current installer docs.
- Compare them to the Windows installer implementation.
- Do not publish or change production systems.

Return:
- Findings first.
- Include file paths and command output that prove each finding.
'@ | axiowl send --to "installer-review-worker" --stdin

Use stdin when the message contains newlines, quotes, JSON, code blocks, or instructions where shell escaping would be easy to damage. This matches AxiOwl's intended public contract: one sender, one target, one body, one provider edge, and one receipt.

Preserve Sender Identity

Long-running work usually needs a reply. AxiOwl's final visible body is built after sender resolution, so the receiving agent can see who sent the work and how to send AxiOwl content back if needed.

When a provider sends through MCP, the preferred path is the axiowl_send_message tool. The MCP server receives host session metadata and uses that as the stable sender identity key. The Codex plugin instructions are explicit on this point: use axiowl_send_message for sending, do not invent sender names, and do not ask the chat to know its own session ID.

That matters because the reply path should point back to a real registered sender, not a made-up label. AxiOwl rejects sends when the sender identity cannot be resolved for paths that require it. That is better than silently delivering a message with no usable return route.

Understand the Receipt Boundary

AxiOwl receipts are intentionally careful. When the CLI accepts a send, it can print:

AxiOwl handoff receipt: MCP/CLI request accepted by AxiOwl.
Message ID: <message id>
Delivery state: accepted_by_axiowl
Provider: <provider>
Receipt boundary: provider delivery, provider wake-up, and provider reply are not implied.
Delivery log: <path>

That wording is not decorative. For long-running work, it is the difference between "AxiOwl accepted and routed my request" and "the target has finished the assignment." The implementation treats a reply as a new independent message. A send receipt must not claim that the recipient displayed, processed, or completed the task unless the selected path explicitly reports provider acceptance.

In practice, that means you should keep three facts separate:

  1. AxiOwl accepted the request.
  2. The provider edge accepted or attempted delivery.
  3. The worker replied with results later.

That separation is healthy for operations. It prevents false confidence when a provider is slow, unavailable, not awake, or unable to prove delivery.

Track Work With Message IDs and Logs

Every send receives a message ID. The message pipeline also writes delivery-stage records. The status command prints the current paths for:

events.jsonl
delivery.jsonl
create-lifecycle.jsonl

The implementation appends events such as request acceptance, target resolution, rate-limit delay start and finish, delivery worker handoff, provider write success or failure, and MCP inbound send receipts. The delivery worker runs from a JSON request file and can be started as a background handoff. When that handoff starts, the immediate receipt can return while provider-specific dispatch continues in the worker process.

For a long-running task, copy the message ID into your own notes or issue tracker. If you need to inspect what happened, use axiowl status to find the delivery log path, then review the relevant JSONL records for that message ID.

Use a Clear Task Contract

The best long-running AxiOwl message is specific enough that the worker can continue without constant clarification. Include the goal, scope, stop conditions, output format, and any boundaries around files, systems, or publishing.

For example:

@'
You are the worker for the documentation audit.

Goal:
Produce a final Markdown summary of discrepancies between user docs and implementation.

Boundaries:
- Read only the local repo.
- Do not edit production config.
- Do not publish.

Return through AxiOwl when done:
- Summary
- Findings
- Sources read
- Any commands that failed
'@ | axiowl send --to "docs-audit-worker" --stdin

This works well with AxiOwl's model because the message body remains the original sender content until the pipeline builds the final visible body. Provider-specific adapters get the final visible body and target session context; they do not get to invent a different message shape.

Create or Register Workers When Needed

AxiOwl also exposes create and registry commands. The CLI usage includes:

axiowl create --provider <provider> --name <agent> --body <message>
axiowl create --provider <provider> --name <agent> --stdin
axiowl registry add-agent --name <agent> --provider <provider> --session <provider-session-id>

The MCP server also exposes axiowl_create_agent for creating a new provider chat through AxiOwl. When a provider returns a stable provider session ID, AxiOwl enrolls the created chat in the registry and records lifecycle evidence.

Use this when a long-running job deserves its own worker thread rather than being mixed into an existing conversation. A dedicated worker makes later follow-up messages easier: you send to the worker's registered name, not to a vague memory of where the work began.

When to Use Remote Nodes

AxiOwl has node registry commands:

axiowl node list
axiowl node add --id <node-id> --host <host> --ssh-user <ssh-user>
axiowl node verify --id <node-id>

The node registry stores durable node fields such as node ID, host, SSH user, key path, enabled state, and verification timestamps. Verification uses SSH to run an identity check on the target node.

Remote work should be handled with the same discipline as local work: verify the node, keep the agent registry honest, and do not assume delivery just because the target name exists. AxiOwl's architecture keeps node identity separate from provider session identity so operators can tell whether a target is local, remote, enabled, and sendable.

A Practical Long-Running Workflow

A reliable AxiOwl workflow looks like this:

  1. Run axiowl list agents and confirm the worker exists.
  2. Run axiowl status and note the registry and log paths.
  3. Send the assignment with --stdin if it is more than one line.
  4. Save the message ID from the handoff receipt.
  5. Treat the receipt as handoff proof, not completion proof.
  6. Let the worker reply through AxiOwl MCP when it has results.
  7. Review delivery.jsonl and events.jsonl if anything is unclear.

This is deliberately simple. AxiOwl's current design avoids fake response waiting, hidden replay files, silent provider fallbacks, and treating provider stdout as a recipient reply. If a path is degraded or unknown, it should be reported loudly rather than hidden behind a reassuring message.

Closing

Using AxiOwl for long-running work is mostly about clean handoffs. Give work to a named target, preserve the sender identity, use stdin for substantial instructions, keep the message ID, and read the receipt honestly.

That fits the way AxiOwl is implemented today. It is a coordinator for provider-to-provider messaging with a registry, MCP tools, delivery evidence, and explicit receipt boundaries. For long tasks, those boundaries are what keep the operation understandable after the first prompt is no longer on screen.

Tagged , , , , , , ,