Go to file
Krzysztof kuhy Rudnicki eb1472a433 feat(enforcer): add 4-day grace period to undo a manual pick
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>
2026-07-19 17:04:08 +02:00
.github/workflows chore: set up as standalone repo 2026-05-28 07:21:29 +02:00
docs/explanations Add change explanation: defer-steam-restart-during-update 2026-07-18 16:15:54 +02:00
scripts Add CI-mirror pre-push gate + requirements-sync check 2026-07-11 17:47:14 +02:00
steam_backlog_enforcer feat(enforcer): add 4-day grace period to undo a manual pick 2026-07-19 17:04:08 +02:00
web feat: add pick-manual command with 2-week enforcement lock 2026-05-30 17:15:37 +02:00
.gitignore Add CI-mirror pre-push gate + requirements-sync check 2026-07-11 17:47:14 +02:00
.mcp.json Add MCP server exposing the enforcer to Claude Code 2026-07-10 21:05:17 +02:00
.pre-commit-config.yaml Add CI-mirror pre-push gate + requirements-sync check 2026-07-11 17:47:14 +02:00
CLAUDE.md feat: add block-gaming command (Stage 4) + guard-lib migration cleanup 2026-07-04 11:45:54 +02:00
install.sh fix(enforcer): Steam CDP restart never worked (root+no-display, port collision) 2026-07-18 06:49:10 +02:00
pyproject.toml Add MCP server exposing the enforcer to Claude Code 2026-07-10 21:05:17 +02:00
README.md Add MCP server exposing the enforcer to Claude Code 2026-07-10 21:05:17 +02:00
requirements.txt Add CI-mirror pre-push gate + requirements-sync check 2026-07-11 17:47:14 +02:00
run.sh feat: add block-gaming command (Stage 4) + guard-lib migration cleanup 2026-07-04 11:45:54 +02:00
steam-backlog-enforcer.service fix(enforcer): Steam CDP restart never worked (root+no-display, port collision) 2026-07-18 06:49:10 +02:00

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.com via /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:

  1. Block Steam store in /etc/hosts
  2. Uninstall all games except the assigned one
  3. 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; pass confirm=true to 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.