Cross-OS Runbook

CodeLoop runs the same verification loop on macOS, Windows, and Linux. This page is the public version of docs/RUNBOOK_CROSS_OS.mdin the repo and tells you exactly what to install, what to expect on each OS, and how to troubleshoot the differences.

Capability matrix

Every capability is auto-detected at runtime via os.platform() and checkToolAvailable() (where on Windows, which on macOS / Linux). Missing tools surface install hints instead of crashing.

Capability	macOS	Windows	Linux
Build / lint / test	Yes	Yes	Yes
Web (Playwright Chromium)	Yes	Yes	Yes (`--with-deps`)
Flutter desktop	`flutter run -d macos`	`flutter run -d windows`	`flutter run -d linux`
Native desktop	Xcode / Swift	.NET / WPF / WinUI via UI Automation	Use Flutter or web
Android emulator	Yes	Yes	Yes
iOS Simulator	Yes	No	No
Video capture	ffmpeg avfoundation	ffmpeg gdigrab	ffmpeg x11grab
Mouse / keyboard	Swift CGEvent	`user32.dll` via PowerShell	`xdotool`
App logs while recording	`log stream`	`Get-WinEvent` / app stdout	`flutter logs` / journald

First-time setup

macOS

brew install node ffmpeg android-platform-tools
xcode-select --install
npm i -g codeloop
codeloop auth
codeloop doctor

Grant Screen Recording, Accessibility, and Automationpermissions to your terminal (and to Cursor / Claude Code if you launch CodeLoop from inside the IDE) under System Settings > Privacy & Security. Without these, screenshots, video recording, and codeloop_interact fail with permission errors.

Windows

Open an elevated PowerShell:

winget install OpenJS.NodeJS.LTS
winget install Gyan.FFmpeg
winget install Google.PlatformTools
npm i -g codeloop
codeloop auth
codeloop doctor

For WPF / WinUI / .NET apps CodeLoop runs short PowerShell snippets via UI Automation. The default RemoteSigned execution policy is sufficient. Project paths with spaces (C:\Users\me\My Project) are handled automatically.

Linux (Ubuntu / Debian / Fedora)

sudo apt update
sudo apt install -y nodejs npm ffmpeg xdotool x11-utils xvfb android-tools-adb
npm i -g codeloop
codeloop auth
codeloop doctor

For headless CI hosts (no real display), wrap verification in xvfb-run:

xvfb-run -a npx codeloop verify

For Wayland, install xdotool AND make sure XWayland is enabled.

Verifying the install

codeloop doctor — every required check should be green; optional checks may be yellow.
codeloop --version — must match the version in npm view codeloop version.
From a sample project:
```
mkdir /tmp/cl-smoke && cd /tmp/cl-smoke
npx codeloop init
npx codeloop verify
```
Expect a RunArtifact JSON, no errors, and a non-empty artifacts/runs/<id>/ directory.

(UI projects only) Run the visual loop:

npx codeloop screenshot
npx codeloop video --start
# interact with the app …
npx codeloop video --stop
npx codeloop replay

Run codeloop_gate_check via your AI agent. It must report ready_for_review with confidence_score >= 94.

What CI guarantees

Every CodeLoop release is exercised by the pipelines in .github/workflows:

Build + unit + smoke on macOS / Windows / Linux on every PR (cross-platform.yml).
Live integration on macOS / Windows / Linux weekly (scheduled-e2e.yml > weekly-* jobs).
Playwright Chromium browser smoke on all three OSes weekly + on demand.
Cross-platform interaction routing tests run every PR with mocked os.platform()so each host exercises every other host's command-construction branch.

Live integration jobs are intentionally skipped on PRs to keep PR feedback under 10 minutes. Trigger them on demand with Run workflow > tier=quarterly in the GitHub UI.

Troubleshooting

Symptom	OS	Fix
`screencapture` returns blank PNG	macOS	Grant Screen Recording permission to the parent process, then reboot.
`ffmpeg` records but video is 0 bytes	Windows	Make sure no group policy blocks `gdigrab`; run as the same user that owns the target window.
`xdotool` cannot find the window	Linux	XWayland not enabled. `echo $XDG_SESSION_TYPE` should print `x11` or `wayland` with XWayland active.
`codeloop_interact target_type: desktop` no-ops on Windows	Windows	Install PowerShell 7 or ensure Windows PowerShell 5.1 is on `PATH`.
`adb devices` lists nothing	All	`adb kill-server && adb start-server`; on macOS allow the binary in Privacy & Security.
`codeloop verify` cannot find project	All	Set `CODELOOP_PROJECT_DIR=/abs/path/to/project` or run inside a directory that contains `.codeloop/config.json`.
Web tests pass locally but fail in CI	All	Reinstall Playwright deps with `npx playwright install --with-deps`.
Backend reachability red in `codeloop doctor`	All	Check corporate proxy / VPN; CodeLoop hits `https://api.codeloop.tech/health`.

If codeloop doctor does not surface your problem, open an issue with the full output of codeloop doctor plus npx codeloop verify --debug.