mirror of
https://github.com/kuhyx/steam-backlog-enforcer.git
synced 2026-11-11 16:53:50 +01:00
Krzysztof kuhy Rudnicki
05e070ca27
The enforcer allowed exactly one game: `current_app_id` was the single
"allowed" id threaded through the uninstall guard, the process killer, the
library hider and the auto-installer. Picking a second game manually meant
the first was uninstalled and hidden.
Manual picks are now a set, capped by `Config.max_manual_picks` (default 2).
Every active pick stays installed, visible and un-killed; the lock releases
only when all of them are finished or past their own 14-day deadline.
- `State.manual_picks` holds `{app_id, game_name, started_at}` entries. The
legacy single-slot `manual_pick_*` fields are still read on load, migrated
into the list and cleared, so a live lock survives the upgrade.
- `_actions.allowed_app_ids` / `allowed_games` are the single source of truth
for "may exist". `uninstall_other_games`, `hide_other_games` (incl. its
injected JS), `enforce_allowed_game` and `_guard_installed_games` now take
that set instead of one app id; every call site passes it.
- `pick-manual` joins `_MANUAL_LOCK_EXEMPT_COMMANDS` so a second game can be
added while the first holds the lock — the cap is what limits it, not the
lock check. Its post-pick cascade operates on the whole allowed set, so
adding a pick never tears down an earlier one.
- `abandon-pick <app_id>` drops only that pick; a survivor inherits the
assignment and keeps the lock. Grace and deadline are per pick.
- `cmd_done` is unchanged: it finishes `current_app_id` and auto-picks a
replacement, so two games stay queued. A finished pick leaves the active
set automatically via `finished_app_ids`.
Deployment note, learned the hard way during development: the daemon holds
the allowed set in code, so it MUST be restarted after upgrading. A
pre-upgrade daemon knows only `current_app_id` and uninstalled the other pick
as "unauthorized" within seconds of the second pick being made.
Verified live: legacy KCD2 lock migrated on load; a second pick (Vampire
Survivors) was accepted while the first was locked, with both kept by the
uninstall pass; a third was refused at the cap; abandoning one pick left the
other locked and handed it the assignment; the restarted daemon reports
"KEEPING allowed game" for both. 1060 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.