mirror of
https://github.com/kuhyx/steam-backlog-enforcer.git
synced 2026-11-10 19:27:04 +01:00
Krzysztof kuhy Rudnicki
433a1d6c28
A server started as `python -c "from ..._web_server import serve; serve( port=8000)"` ran for five hours after the code beneath it changed, reporting an 8h gaming budget while the daemon enforced 6h and had already cut gaming off. Two separate holes let that happen. The staleness check only ran from cmd_serve, so a server started any other way never met it. And is_our_server matched argv containing "steam_backlog_enforcer.main", which a `python -c` process does not have -- so that server could not even be identified as ours: `run.sh serve` would have refused the port and named it as a stranger rather than replacing it. _serve_stale puts the check inside the server, where no launch path can skip it. Every route, static included, returns 503 once any package .py is newer than this process, because a fresh page fetching stale numbers is the same lie with extra steps. The answer is memoised for five seconds so it does not stat the package per request; that bounds the staleness window instead of leaving it open forever. Refusing is only half a fix -- a process that 503s forever is honest and useless -- so a refused request also stands the server down. The new steam-backlog-enforcer-web.service supplies the other half with Restart=always: it dies on stale code and returns on current code with nobody having to remember anything. A user unit, not a system one; it serves read-only views and needs no privilege. install.sh installs and enables it rather than printing instructions. is_our_server now substring-matches the joined argv, so run.sh serve, python -m ...main serve and a bare python -c are all recognised. newest_py_since moves into _serve_stale and _serve_guard delegates to it. Both needed the same scan, and two copies would have been free to disagree about whether a server is current -- which is the entire failure being fixed. Verified end to end: healthy 200, touch _budget_view.py, next request 503, systemd replaces the process, back to 200 reporting 6.0h and blocked=True. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fcwu78wk17FWMHbbfbyicc |
||
|---|---|---|
| .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-web.service | ||
| 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.