FocusFix/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Purpose

FocusFix is a Windows utility that forces a game window into the foreground after launch. Works with Steam (directly via %command%) and Sunshine/Moonlight (manual --process argument).

Architecture

• focusfix.py — Python script that supports two modes: --process Name for monitoring an already-known process, or direct Steam wrapper mode where %command% is passed as positional arguments. In wrapper mode it derives the process name from the target executable, launches the game itself, then polls for the game process, waits for its main window (filtered by size to skip splash screens, preferring windows with titles over titleless overlays), waits for the window size to stabilize, then brings the game window to foreground using Win32 API workarounds (AttachThreadInput + Alt key simulation to bypass SetForegroundWindow restrictions). Monitors for window changes (splash → main window) and re-focuses automatically. Retries up to 15 times. Debug logging is only enabled explicitly with --debug/-debug, writes to focusfix.log, and overwrites the file on each new script start.
• launch.vbs — Legacy Steam wrapper. Still supported as a fallback, but not the primary user path anymore. It resolves focusfix.py relative to its own location, prefers a sibling .venv\Scripts\pythonw.exe, falls back to pythonw.exe from PATH, and forwards -d/-debug/--debug to focusfix.py without passing those flags to the game.
• requirements.txt — Source-install dependencies for focusfix.py (psutil, pywin32).

Setup

py -m pip install -r requirements.txt

Optional for development:

py -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Steam Launch Options

Preferred for end users:

"C:\Path\To\FocusFix\FocusFix.exe" %command%

Direct Python/script usage:

"C:\Path\To\Python\pythonw.exe" "C:\Path\To\FocusFix\focusfix.py" %command%

Legacy wrapper fallback:

wscript "C:\Path\To\FocusFix\launch.vbs" %command%
wscript "C:\Path\To\FocusFix\launch.vbs" -debug %command%

All Steam variants above work generically across games with similar foreground/focus issues because the process name is derived from the target executable.

Sunshine / Moonlight

Preferred for end users:

"C:\Path\To\FocusFix\FocusFix.exe" --process "ProcessName"

Direct Python/script usage:

"C:\Path\To\Python\pythonw.exe" "C:\Path\To\FocusFix\focusfix.py" --process "ProcessName"

Running Manually (for testing)

python focusfix.py --process CrimsonDesert
python focusfix.py --process CrimsonDesert --timeout 180
python focusfix.py "C:\Games\CrimsonDesert.exe"
python focusfix.py -debug "C:\Games\CrimsonDesert.exe"

Use either --process or a game command. By default no log file is created. When started with --debug or -debug, runtime logging goes to focusfix.log and overwrites any existing file from a previous run. When started with pythonw.exe, no console window is shown; manual runs with python.exe can still print argument or interpreter errors to the console.

Working Assumptions

• End-user docs and defaults should prefer FocusFix.exe over Python or .venv-based usage.
• Source-based usage is still supported for developers and power users through requirements.txt.
• launch.vbs is legacy/fallback behavior, not the primary integration path.
• Do not assume .venv exists; wrapper behavior explicitly supports a fallback to global pythonw.exe.

Key Constants in focusfix.py

• MIN_WINDOW_WIDTH = 800 — distinguishes game window from splash screen
• FOCUS_RETRIES = 15 / FOCUS_RETRY_DELAY = 2.0 — retry parameters for foreground focus

Windows API Notes

• SetForegroundWindow is restricted by Windows unless the calling process owns the foreground. Workaround: simulate an Alt keypress + AttachThreadInput to the foreground thread.
• Alt key release is in a finally block to prevent it from staying pressed on errors.
• pythonw.exe (not python.exe) is required for invisible background execution when using the Python/script path.
• Normal user-facing guidance should point to FocusFix.exe; direct focusfix.py usage is the source/developer path.
• Window selection prefers titled windows over titleless ones (prevents overlay issues like in Wuthering Waves).