steam-backlog-enforcer/README.md
Krzysztof kuhy Rudnicki a76e726e36 Merge steam-game-installer into the repo
The installer ships as the steam_installer package beside
steam_backlog_enforcer, with its tests, docs and Proton lock. The
enforcer's fast install now starts the installer from this checkout.

Both appinfo.vdf readers share one key-value decoder
(steam_installer.appinfo_kv), and the duplicated test fixtures and
helpers are folded into conftest and _cli_helpers so the whole-tree
duplicate-code check is clean. check_requirements_sync treats sibling
packages as first-party.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWZCxnNWLtpVwFLVk9w
2026-11-22 20:25:39 +01:00

98 lines
4.1 KiB
Markdown

# Steam Backlog Enforcer
This repo is also an alternative Steam frontend: it installs games faster than the
Steam client (`steam_installer`, see [DOCS-steam-installer.md](DOCS-steam-installer.md)).
Forces you to play one Steam game at a time: earn at least one new
achievement in the assigned game before moving on to the next.
Requiring 100% completion kept you locked onto one game for weeks, which proved
ineffective. A game released after one new achievement stays in the backlog
(it is not counted as finished) and comes round again later.
## Features
- **Achievement tracking**: Picks the least-recently-assigned game next, then the
shortest HLTB completionist time; a released game sits out a 7-day cooldown
- **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
```bash
python -m python_pkg.steam_backlog_enforcer.main setup
```
## Commands
| Command | Description |
| ----------- | ------------------------------------------ |
| `scan` | Scan library, fetch HLTB data, assign game |
| `check` | Check assigned game for a new achievement |
| `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 [minutes]` | Unblock the store for a window (default 15, max 30); the daemon keeps it open and re-blocks after |
| `buy-dlc` | Same 15-minute store window, to buy a game or DLC |
| `reset` | Reset all state |
| `total-block-research --until T` | Root. One window per total block, up to its end, extendable once: Steam and the store open, only Librarian may be played; the daemon re-applies the full block at `T` and keeps `~/.local/share/Steam` |
| `installed` | List currently installed Steam games |
| `uninstall` | Interactively uninstall non-assigned games |
| `setup` | First-time configuration |
## Enforce mode
```bash
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.
```bash
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:
```bash
./scripts/setup_mcp.sh
```
Registration lives in the checked-in [`.mcp.json`](./.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`.
## Steam game installer
`steam_installer` (merged in from steam-game-installer) downloads an owned game
with depotdownloader and makes Steam accept it as installed. The daemon runs it
as `python3 -m steam_installer.cli`; by hand use `steam_installer/run.sh <appid|url|name>`.
Dependencies: `steam_installer/install_deps.sh` (run by `install.sh`). Details in
[DOCS-steam-installer.md](DOCS-steam-installer.md).