Using AxiOwl With Claude Code

Using AxiOwl With Claude Code

AxiOwl can treat Claude Code CLI sessions as named provider targets instead of forcing every handoff through one generic terminal. The idea is simple: AxiOwl discovers real Claude session state, records sendable sessions in its registry, and uses Claude's documented CLI resume flow to deliver a message into the right session.

That matters because Claude Code is usually workspace-bound. A useful Claude session is not just a model endpoint; it has a working directory, session history, tool context, and a place in the operator's workflow. AxiOwl's Claude integration is built around preserving that context rather than pretending a new shell command is the same as the existing session.

What AxiOwl Connects To

In the current AxiOwl codebase, the Claude provider is named claude_code_cli internally and appears in the command surface as claude-code-cli. The CLI help includes Claude in the same family as other provider surfaces:

axiowl create --provider claude-code-cli --name <agent> --body <message>
axiowl discover claude-code-cli --json
axiowl send --to <agent> --body <message>

The provider dispatch table has explicit create and delivery edges for claude_code_cli. This is not a placeholder registry label. AxiOwl has real provider code for discovering Claude sessions, creating Claude sessions through the CLI, and delivering to an existing session through Claude's print/resume mode.

The current support matrix keeps claude-code:cli in target status because AxiOwl's final support bar is intentionally strict: a CLI provider is not fully supported merely because a process starts or a message is accepted. Final support requires the provider to receive the message and reply through AxiOwl MCP with provider-owned sender identity. The repository also contains a July 2026 success report showing a response-backed Claude Code CLI path, but the newer metadata policy requires a stronger metadata-patch proof before the matrix calls the surface fully supported.

How Discovery Works

AxiOwl discovers Claude Code CLI sessions from the user's Claude project state under:

~/.claude/projects

The discovery implementation scans bounded .jsonl files and only treats filenames with UUID-shaped stems as Claude sessions. It builds AxiOwl provider session IDs in this form:

claude_code_cli:session:<uuid>

It also reads useful session evidence from the JSONL content. If Claude recorded a custom title or agent name, AxiOwl can use that as the display name. If not, it falls back to a name such as:

Claude Code CLI 2d11ea05

The important guardrail is cwd. Claude resume needs the original session working directory. AxiOwl reads the session cwd, checks that the directory still exists, and only marks the row sendable when the JSONL has matching session proof and a live working directory. If the old project folder has been deleted, discovery downgrades that session to evidence-only instead of pretending it can receive a message.

That is the difference between an agent list and a usable operator registry. A stale Claude transcript may still be valuable evidence, but it should not be a send target.

Sending A Message To Claude Code

For an existing Claude session, AxiOwl delivery uses Claude's documented print/resume flow. The provider implementation resolves the target session UUID, finds the matching JSONL file, extracts the working directory, writes a per-session MCP config, and starts Claude from the session cwd.

The effective Claude command shape is:

claude -p --output-format json --resume <session-id> --mcp-config=<session-mcp-config> --allowedTools=mcp__axiowl__axiowl_send_message,mcp__axiowl__axiowl_whoami,mcp__axiowl__axiowl_list_agents <message>

The generated MCP config points Claude at AxiOwl's native MCP server:

axiowl.exe mcp-server --host claude-code-cli --provider claude_code_cli --provider-session-id <session-id> --sender-name <sender-name>

This gives the Claude session access to the AxiOwl tools it needs for operational handoff: list agents, identify itself, and send a reply or onward message through AxiOwl.

From the operator side, the send command stays simple:

axiowl send --to "Claude Code CLI 2d11ea05" --body "Review this plan and reply through AxiOwl."

AxiOwl's receipt boundary is explicit. accepted_by_axiowl means the local request was accepted and handed to delivery. Stronger proof comes when provider delivery succeeds and the target replies back through MCP with the correct identity.

Creating A Claude Code Session

AxiOwl also has a create path for Claude Code CLI. Creation requires an initial message because the provider uses Claude print mode to establish a durable first turn. AxiOwl chooses a session UUID, writes the per-session MCP config, and runs Claude with:

claude -p --output-format json --session-id <session-id> --mcp-config=<session-mcp-config> --allowedTools=mcp__axiowl__axiowl_send_message,mcp__axiowl__axiowl_whoami,mcp__axiowl__axiowl_list_agents -n <name> <initial-message>

The --cwd option on AxiOwl create matters when a Claude session should belong to a specific project:

axiowl create --provider claude-code-cli --name "Claude Review" --cwd "C:\path\to\repo" --body "Start a code review thread for this repository."

If the working directory does not exist, creation fails loudly. That is intentional. A Claude Code session without a valid project directory is not a reliable automation target.

Why The MCP Piece Matters

The AxiOwl architecture separates three things that are easy to blur together:

For Claude Code CLI, the MCP bridge is the return path. The AxiOwl MCP server exposes tools such as axiowl_send_message, axiowl_whoami, and axiowl_list_agents. Claude can use those tools to respond to the original sender or route work to another registered AxiOwl agent.

The current repository also documents a stricter policy for CLI providers: environment-only identity is not considered final support. A CLI host needs real MCP call metadata or a provider patch that supplies equivalent metadata programmatically. That is why the matrix can show a Claude implementation and a historical success proof while still reserving final supported status until the metadata bar is met.

Practical Operator Value

The practical win is that Claude Code can participate in the same AxiOwl routing model as other provider sessions. An operator can discover local sessions, see which ones are sendable, and route a request to a named Claude target without manually copying prompts between terminals.

It also gives failures better shape. If Claude is not installed, AxiOwl reports that the Claude CLI executable was not found. If the JSONL session file is missing, delivery fails with session evidence. If the saved cwd is gone, discovery and delivery say so instead of creating a false success.

For day-to-day use, the healthy flow looks like this:

axiowl discover claude-code-cli --json
axiowl list agents
axiowl send --to "Claude Code CLI 2d11ea05" --body "Please inspect the current change and reply through AxiOwl."

For a new project-scoped conversation, use create with a real working directory:

axiowl create --provider claude-code-cli --name "Claude API Review" --cwd "C:\path\to\project" --body "Start a review thread for this project and confirm over AxiOwl."

Closing

Using AxiOwl with Claude Code is about routing to real Claude CLI sessions, not just launching another command. AxiOwl reads Claude session evidence, validates the working directory, resumes the right session with a per-session MCP config, and keeps the receipt boundary clear.

The current implementation shows the intended shape of Claude Code support: discover, create, send, and reply through MCP. The remaining support distinction is metadata rigor. AxiOwl's bar is that a provider integration should prove not only that the message was accepted, but that the right provider session received it and can answer as itself.

Tagged , , , , , , ,