How to Diagnose AxiOwl PATH and Installer Problems

How to Diagnose AxiOwl PATH and Installer Problems

When AxiOwl fails right after installation, the first question is usually simple: did Windows find the right axiowl.exe, and did the installer actually install the pieces for the provider you are trying to use? Those are related problems, but they are not the same problem. PATH tells the shell which executable it will run. The installer controls the local runtime, provider integrations, MCP configuration, bridge extensions, patches, cleanup, and discovery.

A good diagnosis keeps those layers separate. Start by proving the command that runs, then prove the installed state under the AxiOwl directory, then prove provider-specific setup, and only then test live message delivery.

The Installed Shape

The current Windows installer contract places the AxiOwl runtime under:

%LOCALAPPDATA%\AxiOwl

The core executable should be here:

%LOCALAPPDATA%\AxiOwl\bin\axiowl.exe

The same install root also holds the durable state that helps you diagnose problems:

%LOCALAPPDATA%\AxiOwl\logs
%LOCALAPPDATA%\AxiOwl\registry
%LOCALAPPDATA%\AxiOwl\runtime

In source, AxiOwl resolves its Windows state root from LOCALAPPDATA, then appends AxiOwl. Registry records live under registry, and the primary runtime logs include events.jsonl, delivery.jsonl, create-lifecycle.jsonl, and activation.jsonl.

That matters because a missing axiowl command is not automatically a failed provider install. It may be only a shell PATH issue. Conversely, a working axiowl --version does not prove that Codex, VS Code, Cursor, Antigravity, or any CLI provider is ready to receive and reply.

Step 1: Prove Which Executable Windows Will Run

Open a new PowerShell window after installing. PATH changes often do not affect shells that were already open before installation.

Run:

Get-Command axiowl -ErrorAction SilentlyContinue

If PowerShell finds AxiOwl, check the source path. It should point to the installed bin directory under %LOCALAPPDATA%\AxiOwl, not to an old development build, stale extracted ZIP, or unrelated checkout.

Then run:

axiowl --version
axiowl status

If Get-Command axiowl fails, try the full expected path:

& "$env:LOCALAPPDATA\AxiOwl\bin\axiowl.exe" --version
& "$env:LOCALAPPDATA\AxiOwl\bin\axiowl.exe" status

There are three useful outcomes:

  1. Full path works, bare axiowl does not. The runtime is present, but PATH is not visible to this shell.
  2. Neither works. The core runtime probably did not install, was removed, or is installed under a different user context.
  3. Bare axiowl works, but points somewhere unexpected. You are testing the wrong binary.

For the first case, open a fresh terminal and test again. If it still fails, inspect the user PATH and confirm whether %LOCALAPPDATA%\AxiOwl\bin is present. For the third case, remove stale PATH entries before testing provider behavior. Otherwise you can spend an hour debugging yesterday's executable.

Step 2: Inspect the Install Root Before Reinstalling

Before rerunning the installer, inspect the local state:

Test-Path "$env:LOCALAPPDATA\AxiOwl\bin\axiowl.exe"
Get-ChildItem "$env:LOCALAPPDATA\AxiOwl"
Get-ChildItem "$env:LOCALAPPDATA\AxiOwl\logs"
Get-ChildItem "$env:LOCALAPPDATA\AxiOwl\registry"

The important distinction is whether the installer failed to place files or whether provider setup failed after the core runtime landed. The AxiOwl installer docs call out the main diagnostic locations: logs, registry, and runtime. Use them before assuming a clean reinstall is the right fix.

The registry is especially important because AxiOwl routes messages to named provider sessions through durable rows, not through a throwaway memory cache. A stale registry row can make a provider look broken even when the binary is fine. A missing registry row can make a working provider invisible to axiowl send.

Run:

axiowl list agents

If needed, use the full executable path while PATH is still being diagnosed:

& "$env:LOCALAPPDATA\AxiOwl\bin\axiowl.exe" list agents

Step 3: Separate Core Install From Provider Install

The Windows MSI installs AxiOwl once, but provider checkboxes are supposed to behave like separate install units. The installer behavior matrix is explicit about this: unchecked provider features should not be installed, patched, closed, restarted, or removed as collateral damage.

That design gives you a clean troubleshooting rule:

If the core command is missing, diagnose the core install and PATH.

If the core command works but one provider fails, diagnose that provider's selected feature, config, extension, patch, discovery, and registry rows.

The installer can configure several provider surfaces, including Codex, VS Code native, VS Code Copilot-backed, Cursor, Antigravity/Gemini, Claude Code CLI, Copilot CLI, and remote features. But support status differs by surface. The provider support matrix treats Codex agents, Codex CLI, VS Code agents, VS Code Copilot-backed, Cursor agents, and Antigravity agents as supported when their message path has response-backed proof. Several CLI surfaces are still target status until provider-owned MCP metadata and current response proof meet the bar.

That means an installer checkbox or config file is not the same as support proof. It is only one part of the chain.

Step 4: Read the Right Logs

For ordinary install diagnosis, start here:

Get-ChildItem "$env:LOCALAPPDATA\AxiOwl\logs" | Sort-Object LastWriteTime -Descending

Useful runtime logs include:

events.jsonl
delivery.jsonl
create-lifecycle.jsonl
activation.jsonl

For Windows Installer level diagnosis, collect a verbose MSI log:

msiexec /i path\to\axiowl-activation-windows-installer.msi /l*v install.log

Use the MSI log to answer installer questions: Did the custom action run? Did the provider feature schedule? Did Windows Installer report an error? Did a rollback happen? Use AxiOwl's JSONL logs and registry to answer runtime questions: Did discovery run? Did the registry get rows? Did message delivery stop at AxiOwl acceptance or reach the provider?

That distinction is central to AxiOwl's own CLI output. When axiowl send accepts a request but the provider has not proven delivery, the CLI prints a receipt boundary: provider delivery, provider wake-up, and provider reply are not implied. The delivery log path is printed so the next step is evidence, not guesswork.

Step 5: Check Provider Discovery

After install, AxiOwl runs lightweight local discovery for local provider surfaces. You can also run discovery directly:

axiowl discover all --json
axiowl list agents

For a narrower check:

axiowl discover codex --json
axiowl discover vscode-native --json
axiowl discover vscode-copilot --json
axiowl discover antigravity --json
axiowl discover cursor --json

Discovery should add or refresh real provider sessions without turning stale paths into sendable truth. The developer docs state the registry rule plainly: do not mark a row sendable unless discovery or direct proof justifies it.

If discovery finds nothing for a provider, look for the provider's own prerequisite first. Is the app installed? Is the CLI installed? Is the expected provider state present? Is the selected provider actually supported on this platform? AxiOwl should fail loudly when selected provider installation cannot be done safely; it should not silently pretend a missing provider is ready.

Step 6: Test the Message Path, Not Just the Installer

A successful MSI install proves selected install actions completed. It does not prove all provider message paths work.

For a real validation, send to a current discovered provider session and ask for a response through AxiOwl MCP. Include a run ID so the reply can be tied to the test:

$runId = [guid]::NewGuid().ToString()
axiowl send --to "<agent name>" --body "Reply through AxiOwl MCP with this run id: $runId" --run-id $runId

Then inspect the delivery evidence:

Get-Content "$env:LOCALAPPDATA\AxiOwl\logs\delivery.jsonl" -Tail 20
Get-Content "$env:LOCALAPPDATA\AxiOwl\logs\events.jsonl" -Tail 20

The release checklist draws a hard line here: accepted_by_axiowl is not delivery proof. A complete provider proof means the provider received the message, replied through AxiOwl MCP, and carried correct provider-owned sender identity back to AxiOwl.

Common Symptoms and What They Usually Mean

axiowl is not recognized:

The binary may be installed but not visible through PATH, or the shell was opened before PATH changed. Try the full path under %LOCALAPPDATA%\AxiOwl\bin.

axiowl --version works, but provider messages fail:

The core runtime is present. Move on to provider discovery, registry rows, provider-specific config, bridge extension state, patches, and delivery logs.

The installer succeeds, but no provider can reply:

Install success is not message-path proof. Restart or reopen the target provider app where required, then run discovery and a response-backed send test.

A provider checkbox is selected even though the provider is missing:

That points to a discovery or default-selection bug. Provider checkboxes should default from discovery and support gates, not stale assumptions.

An unchecked provider was patched, closed, or removed:

That violates the installer feature isolation contract. The safety checks explicitly guard against unchecked providers scheduling provider removal or unrelated mutation.

An old folder or chat appears after install:

That can be stale provider workspace or session state, stale config, or provider default behavior. Diagnose before assuming AxiOwl delivery failed.

When Building the MSI

For developers building the Windows installer, use the current repo script:

.\apps\windows-desktop\installer\build-windows-msi.ps1

The build path validates toolchain dependencies, builds native artifacts, runs tests, stages payloads, writes manifest/provenance, compiles WiX, verifies the MSI, and writes proof under release. The script also forbids -SkipBuild, because the MSI is not supposed to be rebuilt from stale native artifacts.

Run the safety check against the generated WiX source when installer behavior is under review:

.\apps\windows-desktop\installer\check-installer-safety.ps1

That check looks for important installer guarantees: provider checkbox UI, disabled generic Restart Manager behavior, AxiOwl process close rules, stale payload cleanup, selected-only provider feature actions, remote unchecked by default, no old feature-tree UI, and explicit progress labels for provider setup actions.

The Practical Debugging Order

Use this order when the install feels broken:

  1. Open a new PowerShell window.
  2. Run Get-Command axiowl.
  3. Run axiowl --version and axiowl status.
  4. If PATH fails, run %LOCALAPPDATA%\AxiOwl\bin\axiowl.exe directly.
  5. Inspect %LOCALAPPDATA%\AxiOwl\logs, registry, and runtime.
  6. Run axiowl list agents.
  7. Run targeted discovery for the provider you care about.
  8. Send a response-backed test with a run ID.
  9. Read delivery.jsonl and events.jsonl.
  10. Use a verbose MSI log only when the question is about Windows Installer actions.

This order prevents the most common mistake: treating every failure as an installer failure. AxiOwl has a local executable, durable registry, provider discovery, provider bridges, MCP configuration, and provider delivery edges. The fix depends on which layer failed.

Closing

AxiOwl installer diagnosis works best when it is evidence-first. The binary should be under %LOCALAPPDATA%\AxiOwl\bin, PATH should resolve to that binary, logs and registry should live under the same AxiOwl state root, and provider support should be proven with discovery plus a real reply. Once those facts are separated, PATH issues become quick shell problems, installer issues become MSI evidence problems, and provider issues become message-path problems you can test directly.

Tagged , , , , , , ,