Windows Compatibility Report - Part 2 (4/7/26)

[michaelschecht]

ax-cli Windows Compatibility Report

From: Michael Schecht (Edge Radar project)
Date: 2026-04-07
Environment: Windows 11, Python 3.12, Bun 1.3.11, Node 24.12
ax-cli version: v0.3.0 (source install)

---

Summary

Setting up ax-cli + channel on Windows required several manual workarounds. This document captures the issues encountered and suggests fixes to improve the Windows experience.

---

1. Channel: Bun ESM resolution fails on Windows

Severity: Blocker
Files: channel/package.json, channel/server.ts

Problem

@modelcontextprotocol/sdk@^1.0.0 resolves to 1.29.0, which depends on ajv-formats. On Windows, Bun (tested 1.3.9 and 1.3.11) cannot resolve ajv-formats from within the MCP SDK's ESM imports because ajv-formats only exports CJS ("main": "dist/index.js", no "exports" field).

error: Cannot find package 'ajv-formats' from
  node_modules\@modelcontextprotocol\sdk\dist\esm\validation\ajv-provider.js

This also fails with npx tsx on MCP SDK 1.29.0. The @mcpjam/sdk peer-dep pulls in 1.29.0 even when the direct dep is pinned lower.

Workaround applied

1. Removed @mcpjam/sdk (not imported by server.ts)
2. Pinned @modelcontextprotocol/sdk to 1.19.1 (pre-ajv-formats)
3. Ran with npx tsx instead of bun

Suggested fix

• Pin MCP SDK in package.json to a version that works cross-platform, or add ajv-formats with a version that has proper ESM exports
• Document npx tsx as a fallback in the README for Windows users
• Test the channel on Windows in CI (GitHub Actions windows-latest)

---

2. Channel: Bun.sleep() is not portable

Severity: Medium
File: channel/server.ts:255

Problem

await Bun.sleep(backoff * 1000);

This is a Bun-specific API. When running with npx tsx or any Node-based runtime, this throws ReferenceError: Bun is not defined.

Suggested fix

Replace with the standard equivalent:

await new Promise(r => setTimeout(r, backoff * 1000));

This works in Bun, Node, Deno, and any other JS runtime.

---

3. Python CLI: Permission checks always warn on Windows

Severity: High (noisy, misleading)
Files: ax_cli/config.py:90-108, ax_cli/token_cache.py:95-99

Problem

Every CLI invocation prints:

WARNING: C:\Users\user\.ax\config.toml has permissions 0o666 - should be 0600.
  Run: chmod 600 C:\Users\user\.ax\config.toml

On NTFS, stat().st_mode & 0o777 always returns 0o666 or 0o644. There is no way to achieve 0o600 on Windows. The suggested chmod 600 command doesn't exist in PowerShell or CMD.

Impact

• Users see an unfixable warning on every single command
• token_cache.py deletes and recreates the cache on every invocation because the permission check fails, so tokens are never actually cached on Windows

Suggested fix

import sys

def _check_config_permissions() -> None:
    if sys.platform == "win32":
        return  # NTFS uses ACLs, not POSIX modes
    # ... existing Unix permission check ...

Similarly in token_cache.py, skip the mode != 0o600 check on Windows. Optionally, suggest the Windows equivalent:

icacls "C:\Users\user\.ax\config.toml" /inheritance:r /grant:r "%USERNAME%:F"

---

4. Python CLI: chmod(0o600) is a no-op on Windows

Severity: Low (silent, no crash)
Files: ax_cli/config.py:87, ax_cli/token_cache.py:126

Problem

cf.chmod(0o600)

On Windows, Python's Path.chmod() silently does nothing meaningful — NTFS permissions are ACL-based, not mode-based. The config file remains world-readable.

Suggested fix

On Windows, use icacls or the win32security module to restrict access. Or document that users on Windows should manually restrict the .ax/ directory.

---

5. ax agents create fails — no fallback from management API

Severity: High
File: ax_cli/commands/agents.py:46-61

Problem

This is not Windows-specific, but was encountered during setup. When using exchange-based auth (PAT tokens), the CLI tries mgmt_create_agent() first, which hits /agents/manage/create. On the live server (next.paxai.app), this route returns HTML (caught by the frontend), causing:

Error 200: Got HTML instead of JSON (frontend may be catching this route)
  URL: https://next.paxai.app/agents/manage/create

There is no fallback to the legacy /api/v1/agents endpoint. The except block calls handle_error(e) and exits.

Suggested fix

try:
    if hasattr(client, '_exchanger') and client._exchanger:
        data = client.mgmt_create_agent(...)
    else:
        data = client.create_agent(...)
except httpx.HTTPStatusError:
    # Fallback: management API may not be available
    data = client.create_agent(...)

---

6. ax agents create ignores configured space_id

Severity: Medium
File: ax_cli/commands/agents.py, ax_cli/client.py:431-440

Problem

When the legacy /api/v1/agents endpoint is used (either directly or as fallback), the space_id from .ax/config.toml is not automatically passed. The agent gets created in the user's default workspace instead of the configured space.

The create_agent command accepts --space-id but doesn't auto-populate it from config when omitted.

Suggested fix

In commands/agents.py, resolve space_id from config before calling create_agent:

if not space_id:
    space_id = resolve_space_id(client, explicit=None)

---

7. Documentation assumes Unix throughout

Severity: Medium
Files: README.md, channel/README.md

Specific gaps

Location	Unix assumption	Windows equivalent
README.md:100	source .venv/bin/activate	.venv\Scripts\activate
README.md:137-141	tmux, nohup	No equivalent documented
README.md:148	touch ~/.ax/sentinel_pause	echo. > %USERPROFILE%\.ax\sentinel_pause
channel/README.md:85	~/.claude/channels/ax-channel/.env	%USERPROFILE%\.claude\channels\ax-channel\.env
channel/README.md:110-112	tmux session management	No Windows alternative
Error messages	chmod 600	icacls

Suggested fix

Add a "Windows Setup" section to both READMEs, or at minimum add inline notes for the platform differences.

---

8. MCP server config not documented for channel setup

Severity: Medium
File: channel/README.md

Problem

The channel README covers creating the .env file and running with --dangerously-load-development-channels, but does not mention that the MCP server must be registered in .mcp.json for Claude Code to find it:

{
  "mcpServers": {
    "ax-channel": {
      "command": "npx",
      "args": ["tsx", "/path/to/ax-cli/channel/server.ts"]
    }
  }
}

Without this, Claude Code reports: server:ax-channel - no MCP server configured with that name.

Suggested fix

Add the .mcp.json configuration step to the channel README, with examples for both Bun and Node/tsx runtimes.

---

Summary of recommendations

Priority	Issue	Fix
P0	Bun ESM resolution fails on Windows	Pin MCP SDK or document tsx fallback
P0	Permission warnings unfixable on Windows	Platform-detect, skip on win32
P0	Token cache deleted every invocation	Skip permission check on Windows
P1	agents create no fallback from mgmt API	Add try/except fallback to legacy endpoint
P1	Bun.sleep() not portable	Use setTimeout promise wrapper
P1	MCP server config not documented	Add .mcp.json setup step to README
P2	agents create ignores config space_id	Auto-resolve from config
P2	Docs assume Unix	Add Windows notes/section
P2	chmod() no-op on Windows	Use Windows ACL APIs or document

[madtank]

@michaelschecht thanks for the feedback.