Go to file
Krzysztof kuhy Rudnicki 5d5aa3e773
Some checks are pending
dependency freshness / dependencies on newest stable (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (mypy, mypy, ) (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (pylint, pylint, ) (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (rest, , mypy,pylint) (push) Waiting to run
Tests / test (push) Waiting to run
Tests / web-coverage (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
Add Librarian-only research window to total block
kuhy 2026-11-11: game-design research needs Librarian (app 4197610)
actually played during the 6-day total block. New root command
total-block-research --until T opens ONE window per lock: <= 48 h,
never past the lock end, a rerun never extends it.

The command only validates and records (/var/lib/steam-backlog-
enforcer, root 0700; lock id + deadline + two latches). The daemon
opens and closes everything: Steam hosts names, the store block, the
total-block chain (IP cache kept) and the steam package, reinstalled
with only guard-lib's package-block hook masked for that one pacman
call (--hookdir, proved in a guest). Lock file, hook and end date are
never touched. Browser-game sites stay null-routed.

Only Librarian may run: loop-local allowed set, strict mode (no
whitelist exceptions, no zero-achievement games), launchers and
counted games killed; state.json is never read or written.

Expiry latches the record, then the ordinary tick re-applies hosts
(now reconciled each tick), chain, uninstall and purge; the normal
store block is restored once, unconditionally.

Failure modes: missing/corrupt/unparseable record = no window and a
corrupt one also refuses a new window (fail closed); a clock set
back cannot reopen a latched window.

Checked: 3290 tests at 100% coverage; whole-tree pylint 10/10 run in
three parts (the hook exceeds the 60 s cap, so SKIP=pylint here); vmbox
guest with real guardctl package-block and the real unit, window
opened, Librarian-only enforced, clock moved past the deadline and the
full block re-applied. Not verified on the host.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWWzuCEg1m87jpKyRrw
2026-11-11 14:29:58 +01:00
.github/workflows CI: web-coverage installs with pnpm 2026-11-11 12:50:58 +01:00
docs/explanations feat(enforcer): raise manual pick cap from 2 to 3 concurrent games 2026-07-23 18:05:29 +02:00
pacman-hooks Add a daily gaming-time budget with a binary-level cutoff 2026-08-04 20:00:08 +02:00
scripts Add todo app git hooks 2026-11-02 13:55:18 +01:00
steam_backlog_enforcer Add Librarian-only research window to total block 2026-11-11 14:29:58 +01:00
web deps(web): @testing-library/user-event 14.6.9 2026-11-11 12:14:12 +01: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 Pylint gate 10 over the whole package 2026-11-10 16:57:35 +01:00
AGENTS.md repo contract: CLAUDE.md commands, test_changed, CI gate 2026-10-04 17:18:00 +02:00
CLAUDE.md Adopt the four markdown namespaces and gate them 2026-08-24 15:54:34 +02:00
DOCS-ctl-socket.md playtime: drop the Fri-Mon carry-over; log budget on change only 2026-10-18 21:37:29 +02:00
DOCS-web-control-api.md Migrate steam-backlog-enforcer/web to Astro (no R… 2026-11-09 08:36:38 +01:00
install.sh web control UI: all 24 commands in React, ctl.sock daemon, jobs, library browser; earned_time 0.7.0 2026-10-10 16:07:42 +02:00
LICENSE chore: add MIT LICENSE 2026-10-11 18:12:51 +02:00
pyproject.toml Pylint gate covers tests, no suppressions 2026-11-11 12:17:07 +01:00
README.md Add Librarian-only research window to total block 2026-11-11 14:29:58 +01:00
requirements.txt HLTB rate limit (429) wipes confidence data in hl… 2026-11-09 08:02:55 +01:00
run.sh web control UI: all 24 commands in React, ctl.sock daemon, jobs, library browser; earned_time 0.7.0 2026-10-10 16:07:42 +02:00
steam-backlog-enforcer-web.service Stop the web UI serving numbers the enforcer is not applying 2026-08-29 23:39:40 +02:00
steam-backlog-enforcer.desktop web control UI: all 24 commands in React, ctl.sock daemon, jobs, library browser; earned_time 0.7.0 2026-10-10 16:07:42 +02:00
steam-backlog-enforcer.service web control UI: all 24 commands in React, ctl.sock daemon, jobs, library browser; earned_time 0.7.0 2026-10-10 16:07:42 +02:00

Steam Backlog Enforcer

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

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 (at most 48 h): Steam and the store open, only Librarian may be played; the daemon re-applies the full block at T
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.