Windows Compatibility Report

[michaelschecht]

Windows Compatibility Report

Tested on: Windows 11 Home 10.0.26200
Python: 3.12 (C:\Python312)
Date: 2026-03-28

---

Installation Issue

pip install -e . fails when a previous ax.exe exists in the global C:\Python312\Scripts\ directory. pip cannot rename the locked file and rolls back the install.

Workaround: Install in a local venv (python -m venv .venv && .venv/Scripts/pip install -e .). This works cleanly.

Recommendation: Add a note to the README recommending venv-based installation, especially on Windows where global Scripts locks are common.

---

Code Issues

1. shlex.split() is POSIX-only

File: ax_cli/commands/listen.py:93

argv = [*shlex.split(command), prompt]

shlex.split() defaults to POSIX shell parsing rules. On Windows:

• Batch file commands (.bat, .cmd) won't parse correctly
• PowerShell commands with special characters will break
• Paths with backslashes may be misinterpreted as escape sequences

Fix: Use shlex.split(command, posix=False) on Windows, or pass the raw command string with shell=True:

import platform

if platform.system() == "Windows":
    result = subprocess.run(f'{command} "{prompt}"', shell=True, capture_output=True, text=True, ...)
else:
    argv = [*shlex.split(command), prompt]
    result = subprocess.run(argv, capture_output=True, text=True, ...)

---

2. chmod(0o600) is a no-op on Windows

File: ax_cli/config.py:81

cf.chmod(0o600)

Windows ignores POSIX permission bits. The config file holds the API token but gets no file permission protection on Windows.

Fix: Add Windows ACL handling or document the limitation:

import platform

if platform.system() == "Windows":
    # Windows ACL alternative or skip with a logged warning
    pass
else:
    cf.chmod(0o600)

---

3. Example scripts are bash-only

File: examples/echo_agent.sh

• Shebang #!/bin/bash won't work on Windows
• Uses hostname and date -u (not available as standalone commands on Windows)

Fix: Add a Python or .bat equivalent:

@echo off
REM examples/echo_agent.bat
echo Echo from %COMPUTERNAME% at %TIME%: %1

Or a cross-platform Python example:

# examples/echo_agent.py
import sys, socket, datetime
msg = sys.argv[1] if len(sys.argv) > 1 else ""
print(f"Echo from {socket.gethostname()} at {datetime.datetime.utcnow():%H:%M:%S} UTC: {msg}")

---

Documentation Gaps

All ax listen examples in README.md assume Unix conventions:

Line	Example	Windows issue
32	--exec "./my_handler.sh"	Shell script, Unix relative path
44	--exec "./bot"	No file extension, assumes executable bit
101	./handler.sh "check the staging deploy"	Shell script
119	--exec ./examples/echo_agent.sh	Bash required
186	--exec "claude -p"	Works if claude is on PATH

Fix: Add a "Windows" section or inline alternatives showing .bat, .ps1, or python script.py usage.

---

What Works Fine on Windows

• All pathlib path handling — uses / joins which resolve correctly cross-platform
• Config resolution via Path.home() — resolves to %USERPROFILE%
• .ax/config.toml location — works under C:\Users\<user>\.ax\config.toml
• Pause gate files (sentinel_pause) — Path.home() resolves correctly
• pyproject.toml console_scripts — generates .exe in the venv Scripts dir
• All CLI commands tested (auth, agents, tasks, messages) — work as expected

---

Summary

Issue	Severity	File	Fix complexity
shlex.split() POSIX parsing	High	listen.py:93	Small — platform check
chmod(0o600) no-op	High	config.py:81	Small — conditional or warn
Bash-only examples	Medium	examples/	Small — add .py or .bat
Unix-only README examples	Medium	README.md	Small — add Windows section
Global pip install lock	Low	README.md	Docs only — recommend venv