mirror of
https://github.com/kuhyx/steam-backlog-enforcer.git
synced 2026-11-19 01:34:27 +01:00
A running game process was treated as proof of play. On 2026-08-28 the budget
billed ~2h23m while a gatelock screen locker covered the display and the
machine could not be touched at all -- the game was simply still resident.
A tick now bills only when all three hold, evaluated together rather than
short-circuited so the audit log can answer "was the screen ALSO locked?":
* no gatelock guard owns the screen (_screen_hold, via /proc/locks)
* the focused window belongs to a qualifying process or its ancestry
* some input source has been used within idle_grace_seconds (default 300)
Any probe that cannot answer BILLS the tick and is recorded in `degraded`.
A broken detector must never become an unlimited-gaming exploit.
Three findings from measuring this machine rather than assuming:
* /dev/input/js0 here is an *ASRock LED Controller* -- the kernel exposes
the motherboard RGB device as a joystick. A presence check would have
disabled the idle criterion permanently, so _controller_input watches for
real events instead (skipping joydev's synthetic open burst).
* Aseprite's window carries no _NET_WM_PID at all, so focus attribution
falls back to XRes, which asks the server who owns the window rather than
trusting the client to have announced itself.
* /proc/locks reports gatelock's hold without taking it; gatelock's own
read_claim_if_held detects held-ness by acquiring, which would race a
guard every 3 seconds.
Idle pauses also refund the grace period once per walk-away, on the
engaged->paused edge only, never across a day rollover, and never on the first
tick after a restart -- the only place the counter moves backwards.
Everything is recorded to /var/log/steam-backlog-enforcer/budget.jsonl, on
change plus a heartbeat rather than one line per 3s tick. Records name the
qualifying PIDs: reconstructing this incident from journald alone was only
possible by inferring accrual from the spacing of two warning notifications.
Also: refuse to bounce Steam while a game is running. ensure_steam_debug_port
relaunches Steam when the CDP port is closed, which kills the running game --
that is how restarting the daemon to deploy this change ended a live session.
It now defers exactly as it already did for in-flight game updates.
Talks to X through ctypes over one cached connection: at a 3s tick, forking
xprintidle and xprop would cost ~40 forks a minute.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019CEsG6BzHtYR9cHcdxPZqG
|
||
|---|---|---|
| .github/workflows | ||
| docs/explanations | ||
| pacman-hooks | ||
| prompts | ||
| scripts | ||
| steam_backlog_enforcer | ||
| web | ||
| .gitignore | ||
| .mcp.json | ||
| .pre-commit-config.yaml | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| install.sh | ||
| pyproject.toml | ||
| README.md | ||
| requirements.txt | ||
| run.sh | ||
| steam-backlog-enforcer.service | ||
| TODO-file-length-250.md | ||
Steam Backlog Enforcer
Forces you to 100% complete one Steam game at a time before moving on.
Features
- Achievement tracking: Picks the next game by shortest HLTB completionist time
- Store blocking: Blocks
store.steampowered.comvia/etc/hosts - Game uninstalling: Removes all installed games except the assigned one
- Process enforcement: Kills unauthorized game processes
- Tampering detection: Detects achievement unlocks on non-assigned games
- HLTB integration: Estimates completion time with persistent cache
Setup
python -m python_pkg.steam_backlog_enforcer.main setup
Commands
| Command | Description |
|---|---|
scan |
Scan library, fetch HLTB data, assign game |
check |
Check if assigned game is complete |
status |
Show current assignment and blocking |
list |
List incomplete games from snapshot |
skip |
Skip the currently assigned game |
enforce |
Run enforcer (block, uninstall, kill) |
unblock |
Remove store blocking |
reset |
Reset all state |
installed |
List currently installed Steam games |
uninstall |
Interactively uninstall non-assigned games |
setup |
First-time configuration |
Enforce mode
sudo python -m python_pkg.steam_backlog_enforcer.main enforce
This will:
- Block Steam store in
/etc/hosts - Uninstall all games except the assigned one
- Continuously kill any unauthorized game processes
Game Uninstall
Directly removes appmanifest files and game directories from ~/.local/share/Steam/steamapps/.
Preserves Proton versions and Steam Linux Runtime.
python -m python_pkg.steam_backlog_enforcer.main uninstall
MCP server (Claude Code integration)
The enforcer exposes an MCP server (steam_backlog_enforcer._mcp) so Claude Code
and its subagents can query the backlog and drive it through typed tools.
- Read tools:
get_dataset,get_status,get_stats,list_backlog. - Gated write tools:
pick_manual,block_gaming— each defaults to a dry-run preview; passconfirm=trueto actually apply. These write tools must never be added to a permission allowlist (a subagent could otherwise bypass the human confirmation).
The mcp SDK is an optional dependency (pip install -e '.[mcp]'), kept out of
the CLI/systemd system-python path. One-time setup of the dedicated venv that
Claude Code spawns:
./scripts/setup_mcp.sh
Registration lives in the checked-in .mcp.json (project scope).
Restart Claude Code in this repo and approve the project MCP-server prompt for it
to load. Verify with claude mcp list.