FocusFix/CLAUDE.md

CLAUDE.md

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

Purpose

Windows utility that forces a game window into the foreground after launch. Works with Steam (automatic process name extraction from %command%) and Sunshine/Moonlight (manual --process argument).

Architecture

• launch.vbs — VBScript entry point called from Steam launch options. Extracts the game executable name from %command% via FileSystemObject.GetBaseName(), passes it as --process to foreground_fix.py, then launches the actual game. No console window is created.
• foreground_fix.py — Python script that 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. Runtime logging goes to foreground_fix.log.

Setup

py -m venv .venv
.venv\Scripts\activate
pip install psutil pywin32

Steam Launch Options

wscript "C:\Projekte\Steam_backgroud_fix\launch.vbs" %command%

Same launch option works for all Steam games — process name is extracted automatically.

Sunshine / Moonlight

Use as command preparation in Sunshine (full venv path required):

"C:\Projekte\Steam_backgroud_fix\.venv\Scripts\pythonw.exe" "C:\Projekte\Steam_backgroud_fix\foreground_fix.py" --process "ProcessName"

Running Manually (for testing)

.venv\Scripts\python foreground_fix.py --process CrimsonDesert
.venv\Scripts\python foreground_fix.py --process CrimsonDesert --timeout 180

--process is required (no default). Runtime logging goes to foreground_fix.log. 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.

Key Constants in foreground_fix.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.
• VBScript WshShell.Run with window style 0 ensures no console window appears.
• Window selection prefers titled windows over titleless ones (prevents overlay issues like in Wuthering Waves).