mirror of
https://github.com/kuhyx/steam-backlog-enforcer.git
synced 2026-11-18 20:34:26 +01:00
A manual pick had no escape hatch: once locked in, every command except done/check/status/enforce/setup/serve exited 1 for 14 days or until 100% achievements. A wrong pick meant two weeks stuck with it. Adds a short mistake-correction window: - MANUAL_GRACE_DAYS = 4 — within 4 days, 'abandon-pick <app_id>' backs out of the pick. Outside it the command refuses and exits 1. - The app_id must be passed explicitly and must match the active pick, so an abandon cannot be triggered by muscle memory. - 'abandon-pick' joins _MANUAL_LOCK_EXEMPT_COMMANDS — the pre-dispatch lock check would otherwise block the only way out. It is dropped from the advertised command list once the window closes. - Abandoning clears the lock and the assignment, uninstalls the game, and reuses the existing skipped_until cooldown for ABANDON_COOLDOWN_DAYS=30 so 'scan' does not hand it straight back. - _actions.abandon_manual_pick is state-only (no uninstall cascade), matching apply_manual_pick, so the gated MCP abandon_pick tool reuses it. Also fixes a crash surfaced while picking a replacement game: the SteamUnavailableError family (including SteamUpdateInProgressError, raised when a game update defers a Steam restart) was only caught in the enforce loop. cmd_hide, cmd_pick, cmd_pick_manual and both cmd_done reconciliation points called hide_other_games bare, so an undrivable Steam aborted the command with a traceback — after the pick had already been saved. All six sites now go through the new stdout-free try_hide_other_games wrapper and report "Library hiding: skipped (<reason>)" instead. Verified live: lock message advertises the window, expired/wrong-id/no-arg paths exit 1, and abandoning released the AoE2 lock, uninstalled it and recorded the 30-day cooldown. 1030 tests pass at 100% coverage. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .github/workflows | ||
| docs/explanations | ||
| scripts | ||
| steam_backlog_enforcer | ||
| web | ||
| .gitignore | ||
| .mcp.json | ||
| .pre-commit-config.yaml | ||
| CLAUDE.md | ||
| install.sh | ||
| pyproject.toml | ||
| README.md | ||
| requirements.txt | ||
| run.sh | ||
| steam-backlog-enforcer.service | ||
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.