Troubleshooting

Troubleshooting

The server won't connect in Claude Code / Codex

• Confirm the launch command resolves: uv run --directory <repo> lowlevel-computer-use-mcp.
• Check claude mcp list shows ✔ Connected.
• Restart the client after any config or code change so it respawns the server.
• Make sure uv is on PATH (the GUI installer can bootstrap it).
• If connections keep failing, use the Cheap Version — run any tool directly from the command line, no MCP required:

uv run lowlevel-computer-use-cheap screenshot --monitor 1

A tool returns {"ok": false, ...}

Read the error string — it's actionable. Common cases:

Error mentions	Fix
pygetwindow / winio (Windows) not available	You're on Linux — use the Linux tools, or install the missing dep
linuxio / xdotool required	Install the X11 helpers (see Linux Support)
No matching window found	Re-run list_windows; titles/handles change; widen title_filter
WSL not available	Install WSL (wsl --install); see WSL
AutoHotkey not found	winget install -e --id AutoHotkey.AutoHotkey or set LOWLEVEL_CU_AHK

Background typing/clicking does nothing

The target app ignores synthetic input (raw input / physical key-state checks; or xterm with allowSendEvents:false). Options:

• Windows → win_set_control_text, or AutoHotkey ahk_control_send, or window_action { "action": "focus" } then foreground type_text.
• Linux → focus the window, or relaunch the app permitting send-events.

See Background Targeting for details.

screenshot(hwnd=...) is black

PrintWindow can't capture some GPU-exclusive surfaces. Capture a screen region instead (compute the window rect from list_windows):

screenshot { "region": [100, 100, 800, 600] }

A virtual display window can't be driven (Linux)

You must pass display to the input/capture tool so it targets the right X server:

type_text { "hwnd": 2097164, "display": 99, "text": "..." }

If Xvfb failed to start on :99 (already in use), a previous display is still running — stop_virtual_display { "display": 99 }, or remove the stale lock /tmp/.X99-lock.

Recording produced an empty / short file

• Only one recording runs at a time (recording_status to check).
• On Linux the recorder needs a working DISPLAY.
• Make sure you called stop_screen_recording to flush the mp4.

Leftover resources

Always pair create/start with destroy/stop/close: create_headless_desktop→close_headless_desktop, create_virtual_display→stop_virtual_display, wsl_create_temp→wsl_destroy, start_screen_recording→stop_screen_recording. An --http server keeps running until explicitly stopped.

Permission prompts despite YOLO

Ensure ~/.claude/settings.json has "mcp__lowlevel-computer-use__*" in permissions.allow (or defaultMode: bypassPermissions), and for Codex that approval_policy = "never". See Registering Clients.