meanwhile-cli 0.1.0__py3-none-any.whl

meanwhile/meanwhile-state.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Writes meanwhile's busy/idle state file. Invoked by the coding agent's hooks
+# (Claude Code, Codex, Cursor).
+# Pure bash on purpose: this runs on every prompt submit and must be instant.
+set -euo pipefail
+
+# The agent sends a JSON payload on stdin. We do not need it, but we must
+# drain it so the writing end never blocks on a full pipe.
+cat >/dev/null 2>&1 || true
+
+# Only the two statuses meanwhile.state understands. Anything else — a typo in
+# hooks.json, say — would be written verbatim and then silently read back as
+# "idle", so refuse it loudly instead. stdout stays empty on purpose: a
+# prompt-submit hook's stdout is injected into the agent's context.
+status="${1:-}"
+case "$status" in
+  busy | idle) ;;
+  *)
+    printf 'meanwhile-state.sh: status must be "busy" or "idle", got %s\n' \
+      "${status:-<missing>}" >&2
+    exit 1
+    ;;
+esac
+
+# Optional second argument: which agent is running. Validated rather than
+# interpolated blind — this string ends up inside a JSON document.
+agent="${2:-}"
+if [ -n "$agent" ] && ! [[ "$agent" =~ ^[a-z][a-z-]{0,15}$ ]]; then
+  printf 'meanwhile-state.sh: agent must match ^[a-z][a-z-]{0,15}$, got %s\n' "$agent" >&2
+  exit 1
+fi
+
+# Normalize to match Python's Path(project_dir).resolve() (see
+# meanwhile.state.project_key): resolve symlinks and collapse "." / ".." and
+# relative or trailing-slash forms to one canonical absolute path. `pwd -P`
+# only works on a directory that exists, and resolve() normalizes paths that
+# do not, so resolve the deepest existing ancestor and fold the rest in
+# lexically — exactly what resolve() does with its non-existent tail.
+normalize_dir() {
+  local path="$1" head suffix="" part old_ifs
+  case "$path" in
+    /*) ;;
+    *) path="$PWD/$path" ;;
+  esac
+  while [ "$path" != "/" ] && [ "${path%/}" != "$path" ]; do
+    path="${path%/}"
+  done
+
+  head="$path"
+  while [ "$head" != "/" ] && [ ! -d "$head" ]; do
+    suffix="${head##*/}${suffix:+/$suffix}"
+    head="${head%/*}"
+    [ -n "$head" ] || head="/"
+  done
+  # `cd -P`, not plain `cd`: bash's default is -L, which folds a ".." that
+  # follows a symlinked component lexically instead of resolving the link
+  # first. resolve() resolves the link first, so -L would key
+  # ".../real/tolink/.." on real's parent rather than on the link's target.
+  head="$(cd -P "$head" 2>/dev/null && pwd -P)" || head="/"
+
+  # `head` is now symlink-free and canonical, so the (possibly non-existent)
+  # tail can be folded in lexically, exactly as resolve() folds its own:
+  # "." drops, ".." pops, anything else appends.
+  old_ifs="$IFS"
+  IFS='/'
+  set -f
+  for part in $suffix; do
+    case "$part" in
+      '' | .) ;;
+      ..)
+        head="${head%/*}"
+        [ -n "$head" ] || head="/"
+        ;;
+      *)
+        if [ "$head" = "/" ]; then head="/$part"; else head="$head/$part"; fi
+        ;;
+    esac
+  done
+  set +f
+  IFS="$old_ifs"
+  printf '%s' "$head"
+}
+
+# Claude Code sets CLAUDE_PROJECT_DIR to the directory the session started in.
+# Codex and Cursor set nothing, so their hooks fall back to the directory they
+# were run from — which is that same directory.
+dir="$(normalize_dir "${CLAUDE_PROJECT_DIR:-$PWD}")"
+
+if command -v sha256sum >/dev/null 2>&1; then
+  key="$(printf '%s' "$dir" | sha256sum | cut -c1-16)"
+else
+  key="$(printf '%s' "$dir" | shasum -a 256 | cut -c1-16)"
+fi
+
+state_dir="$HOME/.meanwhile/state"
+mkdir -p "$state_dir"
+tmp="$state_dir/$key.json.tmp.$$"
+if [ -n "$agent" ]; then
+  printf '{"status":"%s","ts":%s,"agent":"%s"}' "$status" "$(date +%s)" "$agent" > "$tmp"
+else
+  printf '{"status":"%s","ts":%s}' "$status" "$(date +%s)" > "$tmp"
+fi
+mv -f "$tmp" "$state_dir/$key.json"

meanwhile/pool.py

@@ -0,0 +1,101 @@
+"""Reading and validating .meanwhile/pool.json.
+
+The pool is produced by an LLM at build time, so every field is treated as
+untrusted input: the loader validates shape, not content.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+POOL_RELPATH = ".meanwhile/pool.json"
+
+
+class PoolError(Exception):
+    """The pool file is missing, unreadable, or structurally invalid."""
+
+
+@dataclass(frozen=True)
+class QuizItem:
+    q: str
+    choices: list[str]
+    answer: int
+    why: str
+    source: str
+
+
+@dataclass(frozen=True)
+class Pool:
+    built_at: str
+    head_sha: str
+    repo: str
+    items: list[QuizItem]
+    language: str = "en"
+
+
+def _require(raw: dict, key: str, kind: type, where: str):
+    value = raw.get(key)
+    if not isinstance(value, kind):
+        raise PoolError(f"{where}: field {key!r} must be {kind.__name__}, got {value!r}")
+    return value
+
+
+def _quiz(raw: dict, where: str) -> QuizItem:
+    choices = _require(raw, "choices", list, where)
+    if len(choices) < 2:
+        raise PoolError(f"{where}: needs at least 2 choices, got {len(choices)}")
+    if not all(isinstance(c, str) and c for c in choices):
+        raise PoolError(f"{where}: every entry in choices must be a non-empty string")
+    answer = _require(raw, "answer", int, where)
+    if not 0 <= answer < len(choices):
+        raise PoolError(f"{where}: answer {answer} is out of range for {len(choices)} choices")
+    return QuizItem(
+        q=_require(raw, "q", str, where),
+        choices=choices,
+        answer=answer,
+        why=_require(raw, "why", str, where),
+        source=_require(raw, "source", str, where),
+    )
+
+
+def load_pool(path: str | Path) -> Pool:
+    path = Path(path)
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise PoolError(f"pool not found at {path}") from exc
+    except (OSError, json.JSONDecodeError) as exc:
+        raise PoolError(f"pool at {path} is unreadable: {exc}") from exc
+
+    if not isinstance(raw, dict):
+        raise PoolError("pool must be a JSON object")
+
+    raw_items = raw.get("items")
+    if not isinstance(raw_items, list) or not raw_items:
+        raise PoolError("pool 'items' is empty or not a list")
+
+    items = []
+    for index, entry in enumerate(raw_items):
+        where = f"item {index}"
+        if not isinstance(entry, dict):
+            raise PoolError(f"{where}: must be an object")
+        kind = entry.get("type")
+        if kind == "quiz":
+            items.append(_quiz(entry, where))
+        elif kind == "mutant":
+            raise PoolError(
+                f"{where}: mutant cards are no longer supported — "
+                "regenerate this pool with the build command"
+            )
+        else:
+            raise PoolError(f"{where}: unknown type {kind!r}")
+
+    return Pool(
+        built_at=str(raw.get("builtAt", "")),
+        head_sha=str(raw.get("headSha", "")),
+        repo=str(raw.get("repo", "")),
+        items=items,
+        language=str(raw.get("language", "en")) or "en",
+    )

meanwhile/repo.py

@@ -0,0 +1,30 @@
+"""How far the committed pool has drifted from the working tree."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+STALE_THRESHOLD = 50
+
+
+def commits_behind(repo_dir: str | Path, head_sha: str) -> int | None:
+    """Commits added since the pool was built, or None if that cannot be known."""
+    if not head_sha:
+        return None
+    try:
+        result = subprocess.run(
+            ["git", "rev-list", "--count", f"{head_sha}..HEAD"],
+            cwd=str(repo_dir),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    try:
+        return int(result.stdout.strip())
+    except ValueError:
+        return None

meanwhile/scores.py

@@ -0,0 +1,44 @@
+"""Per-developer running totals. Gitignored: scores are local, never shared."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from .game import Session
+
+SCORES_RELPATH = ".meanwhile/scores.json"
+_ZERO = {"answered": 0, "correct": 0, "best_streak": 0}
+
+
+def _path(repo_dir: str | Path) -> Path:
+    return Path(repo_dir) / SCORES_RELPATH
+
+
+def load_scores(repo_dir: str | Path) -> dict:
+    try:
+        data = json.loads(_path(repo_dir).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return dict(_ZERO)
+    if not isinstance(data, dict):
+        return dict(_ZERO)
+    out = dict(_ZERO)
+    for key in out:
+        value = data.get(key, 0)
+        out[key] = value if isinstance(value, int) and value >= 0 else 0
+    return out
+
+
+def record_session(repo_dir: str | Path, session: Session) -> dict:
+    totals = load_scores(repo_dir)
+    totals["answered"] += session.answered
+    totals["correct"] += session.correct
+    totals["best_streak"] = max(totals["best_streak"], session.best_streak)
+
+    path = _path(repo_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.tmp.{os.getpid()}")
+    tmp.write_text(json.dumps(totals, indent=2), encoding="utf-8")
+    tmp.replace(path)
+    return totals

meanwhile/state.py

@@ -0,0 +1,66 @@
+"""Machine-local busy/idle state shared between an agent's hooks and the TUI."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+
+from .agents import SLUG_PATTERN
+
+STATE_ROOT = Path.home() / ".meanwhile" / "state"
+
+_VALID = ("busy", "idle")
+_IDLE = {"status": "idle", "ts": 0.0, "agent": None}
+
+
+def project_key(project_dir: str | Path) -> str:
+    """Short, stable id for a project directory.
+
+    Must stay byte-for-byte compatible with hooks/meanwhile-state.sh:
+    sha256 of the resolved path, no trailing newline, first 16 hex chars.
+    """
+    resolved = str(Path(project_dir).resolve())
+    return hashlib.sha256(resolved.encode("utf-8")).hexdigest()[:16]
+
+
+def state_path(project_dir: str | Path, root: Path = STATE_ROOT) -> Path:
+    return Path(root) / f"{project_key(project_dir)}.json"
+
+
+def write_state(
+    project_dir: str | Path,
+    status: str,
+    root: Path = STATE_ROOT,
+    now: float | None = None,
+    agent: str | None = None,
+) -> Path:
+    if status not in _VALID:
+        raise ValueError(f"status must be one of {_VALID}, got {status!r}")
+    if agent is not None and not SLUG_PATTERN.match(agent):
+        raise ValueError(f"agent must match {SLUG_PATTERN.pattern}, got {agent!r}")
+    path = state_path(project_dir, root=root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload_data = {"status": status, "ts": now if now is not None else time.time()}
+    if agent is not None:
+        payload_data["agent"] = agent
+    payload = json.dumps(payload_data)
+    tmp = path.with_name(f"{path.name}.tmp.{os.getpid()}")
+    tmp.write_text(payload, encoding="utf-8")
+    tmp.replace(path)  # atomic: the TUI polls this file and must never see a half-write
+    return path
+
+
+def read_state(project_dir: str | Path, root: Path = STATE_ROOT) -> dict:
+    try:
+        data = json.loads(state_path(project_dir, root=root).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return dict(_IDLE)
+    if not isinstance(data, dict) or data.get("status") not in _VALID:
+        return dict(_IDLE)
+    agent = data.get("agent")
+    if not isinstance(agent, str) or not SLUG_PATTERN.match(agent):
+        agent = None
+    return {"status": data["status"], "ts": float(data.get("ts", 0.0)), "agent": agent}

meanwhile/strings.py

@@ -0,0 +1,42 @@
+"""The interface's six strings, in the languages meanwhile ships.
+
+A dictionary, deliberately, and not an i18n framework: there is no catalog to
+extract, no compilation step and no locale negotiation. The cards themselves
+are written in whatever language the pool was built in; this is only the
+chrome around them.
+"""
+
+from __future__ import annotations
+
+DEFAULT_LANGUAGE = "en"
+
+KEYS = ("waiting", "done", "exhausted", "stale", "correct", "wrong", "agent")
+
+_TABLE = {
+    "en": {
+        "agent": "the agent",
+        "waiting": "Waiting for {agent} to start working — submit a prompt and the game begins.",
+        "done": "{agent} is done ^ — switch back to the diff; this pane keeps running.",
+        "exhausted": "Pool exhausted for this wait — the next one deals a fresh round.",
+        "stale": "pool is {behind} commits behind — run the build command for fresh questions",
+        "correct": "correct",
+        "wrong": "wrong",
+    },
+    "tr": {
+        "agent": "ajan",
+        "waiting": "{agent} çalışmaya başlayınca oyun başlıyor — bir istem gönder.",
+        "done": "{agent} bitirdi ^ — diff'e dön; bu pencere açık kalıyor.",
+        "exhausted": "Bu bekleme için havuz bitti — sonraki bekleme yeni bir tur dağıtıyor.",
+        "stale": "havuz {behind} commit geride — tazelemek için build komutunu çalıştır",
+        "correct": "doğru",
+        "wrong": "yanlış",
+    },
+}
+
+
+def text(language: str, key: str, **fields) -> str:
+    """One string, in `language` if it is shipped and in English otherwise."""
+    table = _TABLE.get(language, _TABLE[DEFAULT_LANGUAGE])
+    if key not in KEYS:
+        raise KeyError(key)
+    return table[key].format(**fields) if fields else table[key]

meanwhile_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,265 @@
+Metadata-Version: 2.5
+Name: meanwhile-cli
+Version: 0.1.0
+Summary: Play a quiz about your own repository while your coding agent works
+Project-URL: Homepage, https://github.com/ismailbayram/meanwhile
+Project-URL: Repository, https://github.com/ismailbayram/meanwhile
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: textual>=0.80
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# meanwhile
+
+Claude Code takes a while on real tasks — often ten or fifteen minutes. During
+that wait, attention drifts: a browser tab, a chat, something unrelated. When
+the diff finally lands, you no longer hold the task in your head, and the
+review that follows is slower and shallower than it should be. meanwhile fills
+that wait with a quiz built entirely from your own repository, so that
+instead of drifting away you stay warmed up on the code you're about to
+review. It works the same way alongside Codex, Cursor and OpenCode.
+
+## Install
+
+### Claude Code
+
+meanwhile is a Claude Code plugin, and this repository is also its own
+marketplace (`.claude-plugin/marketplace.json`). Add it as a marketplace,
+then install the plugin from it:
+
+```
+/plugin marketplace add ismailbayram/meanwhile
+/plugin install meanwhile@meanwhile
+```
+
+(While developing against a checkout of this repo, add the local path
+instead — `/plugin marketplace add /path/to/meanwhile`.) Restart Claude Code
+afterwards so the plugin's hooks are picked up.
+
+Installing the plugin adds two hooks and one slash command; it does not
+install the `meanwhile` command itself. That's a separate, ordinary Python
+package — see "Daily use" below.
+
+### Codex
+
+This repository is a Codex plugin and marketplace too (`plugin.json`,
+`.agents/plugins/marketplace.json`). Add the marketplace:
+
+```
+codex plugin marketplace add ismailbayram/meanwhile
+```
+
+then install `meanwhile` from the Plugins Directory. Codex does not run a
+plugin's hooks until you have reviewed and trusted them, so do that once
+after installing — until then the pane never wakes.
+
+### Cursor, OpenCode, or Codex without the plugin
+
+Cursor has no plugin system, so `meanwhile` writes the hook registration into
+the agent's config file directly. The same works for Codex if you would
+rather not install the plugin:
+
+```
+uvx meanwhile-cli hooks install --agent cursor
+uvx meanwhile-cli hooks install --agent codex
+```
+
+OpenCode has no shell hooks at all, only JavaScript plugins, so there the
+same command writes a small plugin file — `.opencode/plugins/meanwhile.js`,
+or `~/.config/opencode/plugins/meanwhile.js` with `--user` — that calls the
+hook script whenever a session goes busy or idle:
+
+```
+uvx meanwhile-cli hooks install --agent opencode
+```
+
+Restart OpenCode afterwards; plugins are loaded at startup. A file already
+at that path that `meanwhile` did not write is refused, never overwritten.
+
+(While developing against a checkout of this repo instead of the published
+package, use `uv run meanwhile hooks install --agent codex` from inside it.)
+
+Leaving off `--agent` (or passing `--agent auto` explicitly) installs for
+every agent whose config directory already exists in this project — it never
+creates one, so an agent you don't use is left alone. `meanwhile hooks status`
+reports what's registered and where — only the registrations meanwhile itself
+wrote, so a *plugin* install is invisible to it: Claude Code shows as `not
+installed (the plugin registers its own hooks separately)`, Codex as plain
+`not installed`. `meanwhile hooks
+uninstall --agent <agent>` takes a registration back out.
+
+Cursor only supports project-scope registration. `--user` is refused for it:
+Cursor runs its user-level hooks from `~/.cursor/`, while the hook keys the
+state file on its working directory, so a user-level registration could
+never wake the right pane.
+
+For Claude Code, a `hooks install` registration is written to
+`.claude/settings.local.json`, not `settings.json` — the entry embeds an
+absolute path to this machine's copy of the hook script, and `settings.json`
+is the file teams commit. A Codex, Cursor or OpenCode project registration
+has no such gitignored sibling to move to, so `hooks install` prints a note there — every
+time, whether or not git already tracks the file — saying that the path it
+just wrote is specific to this machine and that committing it would leave
+teammates running a script they do not have.
+
+If you both install the plugin *and* run `meanwhile hooks install` for the
+same agent, the two hooks fire twice per prompt. That's harmless — both copies
+are byte-identical (`hooks/meanwhile-state.sh` for the plugin,
+`~/.meanwhile/meanwhile-state.sh` for the standalone registration) and are run
+with the same arguments against the same state file, so it's one redundant
+run per event — but worth knowing so you don't go looking for a bug.
+
+`hooks` is handled before the normal argument parser is built, so it never
+appears in `meanwhile --help`. `build-prompt` (below) does appear there, but
+only as a bare choice with no explanation of what it does — so this README
+is where to learn about both.
+
+## First run
+
+In a project you want to play against, build a pool once, up front — nothing
+regenerates it in the background.
+
+**Claude Code**: run
+
+```
+/meanwhile-build
+```
+
+This asks Claude to read the repository — models, routes, the README,
+`CHANGELOG.md`, recent commits — and write `.meanwhile/pool.json`: a set of
+multiple-choice questions drawn from that project's actual code.
+
+**Codex, Cursor, OpenCode, or any other agent**: `/meanwhile-build` is a Claude Code
+slash command, so run this instead and paste the printed instructions to
+your agent:
+
+```
+uvx meanwhile-cli build-prompt --lang en --repo .
+```
+
+It prints the exact same instructions the slash command uses, so the pool
+comes out the same either way.
+
+Commit `.meanwhile/pool.json`. It's checked into the repository on purpose, so
+everyone on the team plays the same pool and nobody pays to regenerate it.
+
+`--lang` takes a short language code — `tr` or `en` — not a language name:
+`--lang Turkish` is not recognised and silently leaves the interface in
+English. Those two codes are the only ones the interface itself speaks.
+
+A pool built by the build prompt records the language it was written in, and
+the playing interface follows it, with `--lang` overriding that for just your
+pane. `--lang` on `build-prompt` controls what language the cards themselves
+get written in — any code is allowed there, so `--lang de` writes German cards
+and leaves the interface in English. `pool.json` carries the same code in a
+top-level `language` field (it defaults to `en` when absent); the playing
+interface's own chrome — the waiting banner, "correct"/"wrong", and so on —
+follows that field, in `tr` or `en` and in English for anything else.
+
+## Daily use
+
+Open a second terminal pane next to the one running your agent — a tmux
+split, an iTerm pane, or just another window — sitting in the *same directory
+you started it in*, and run:
+
+```
+uvx meanwhile-cli
+```
+
+`uvx` runs it without installing anything. To install it for good instead,
+`uv tool install meanwhile-cli` (or `pipx install meanwhile-cli`) — the
+command that leaves on your path is plain `meanwhile`, and it takes the same
+arguments everywhere this README writes `uvx meanwhile-cli`.
+
+(While developing against a checkout of this repo instead of the published
+package, use `uv run meanwhile` from inside it.)
+
+Open it whenever you like — before your first prompt is fine. The pane sits
+waiting until your agent starts working, wakes up within about a second of
+you submitting a prompt, and serves multiple-choice cards about the
+codebase one at a time. Answer with the number key for the choice you want;
+the footer only ever offers the keys the card on screen can actually take.
+Answering shows the explanation, `space` deals the next card, and a streak
+counter tracks that wait. If a wait runs long enough to reach the end of the
+pool, the pane says so and sits out the rest of it rather than repeating
+questions.
+
+The moment your agent finishes, the current card freezes and the pane shows
+`<Agent> is done ^` (or `the agent is done ^` if it can't tell which one),
+which is your cue to switch back.
+
+Then leave it open. It stays on that line — it does not clear itself or
+return to the waiting message — until your next prompt, which deals a fresh,
+re-shuffled round, so a long wait never exhausts the pool for the next one.
+You only ever press `q` when you are done for the day. Each wait is scored as
+its own session and added to your totals when it ends; a wait you answered
+nothing in is not recorded.
+
+The interface follows the language recorded in the pool. Override it for
+just your pane with `--lang` and a short code, for example `uvx
+meanwhile-cli --lang en`, regardless of what the pool says. `tr` and `en`
+are the two the interface speaks; any other code leaves it in English.
+
+## How it works
+
+meanwhile is three independent parts that only ever talk to each other
+through two files on disk — nothing imports anything else, and each part can
+be tested alone:
+
+```
+/meanwhile-build          (Claude Code slash command)
+build-prompt              (same instructions, any other agent)
+        │  writes
+        ▼
+   .meanwhile/pool.json          ← committed to the repo, shared by the team
+        │  reads
+        ▼
+   meanwhile TUI  ──watches──►  ~/.meanwhile/state/<project-hash>.json
+   (uvx, separate pane)                    ▲
+                                           │ writes
+                    hooks: plugin (Claude Code, Codex), or `meanwhile
+                    hooks install` (those two, Cursor, OpenCode)
+```
+
+- **`/meanwhile-build`** (or `meanwhile build-prompt` for every other agent) is
+  the only part that costs tokens or touches an LLM. It reads the repository
+  and writes `.meanwhile/pool.json`.
+- **The hooks** are a few lines of pure bash (`hooks/meanwhile-state.sh` for
+  the plugin; the same script, packaged inside the wheel and copied to
+  `~/.meanwhile/meanwhile-state.sh`, for `hooks install`), fired on the moment
+  each agent starts and stops working — `UserPromptSubmit`/`Stop` for
+  Claude Code and Codex, `beforeSubmitPrompt`/`stop` for Cursor, and the
+  `session.status` event for OpenCode, whose plugin file does nothing but
+  call the same script. They write nothing but a
+  `{"status": "busy"|"idle", "ts": ..., "agent": ...}` file under
+  `~/.meanwhile/state/`, keyed by a hash of the directory the agent was
+  started in (that is what `CLAUDE_PROJECT_DIR` holds for Claude Code — not
+  necessarily the git root, which is why the TUI must be launched from the
+  same directory). No interpreter, no network, no measurable delay added to
+  your prompt.
+- **The `meanwhile` TUI**, run separately as `uvx meanwhile-cli`, polls
+  that state file and renders cards from the pool. It finds
+  `.meanwhile/pool.json` at the git root above wherever you launched it. It makes no LLM calls and
+  parses no source code at play time — it only reads the two JSON files
+  above.
+
+## Refreshing a stale pool
+
+`pool.json` records the commit it was built from. If the repository has
+moved on more than about 50 commits since then, the TUI shows a banner —
+`pool is N commits behind — run the build command for fresh questions` — but
+it never regenerates the pool on its own. Silent background regeneration
+would spend tokens you didn't ask for, which is exactly what this design
+avoids. Run `/meanwhile-build` (or `meanwhile build-prompt`) again when you see
+the banner (or whenever the pool just feels stale) and commit the updated
+file.
+
+## Scores
+
+Your running total and best streak are written to `.meanwhile/scores.json`.
+That file is gitignored — scores are local to your machine and never shared
+or synced between teammates.

meanwhile_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+meanwhile/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+meanwhile/agents.py,sha256=XIslhkfyU5YuIhZ7xuSW1O6GnUXBk7PnlKAYgeLFWFE,11833
+meanwhile/app.py,sha256=gJ9ajSxEuPMhYEK_JgHqUH6Ftm3MdqPjWRTrC4zE9V4,7338
+meanwhile/app.tcss,sha256=iTWrCKqVzC1rOH2EcEPipSmxqtXAhW2WMlpp_LgJWAs,232
+meanwhile/build_prompt.md,sha256=cT1fGy8uWZJYKvq2G9Kor_hJGiV6uCzyCLp3WLFWB5k,3025
+meanwhile/cli.py,sha256=4eN2_ieUoqcvKfha-zqL2MN5bTkM-zTCgObq5kI_T-A,8491
+meanwhile/game.py,sha256=e02NsN-MaG0xMSKNPczVYC0dCpg93oYCAUuwNWnEAf4,1806
+meanwhile/hooks_cli.py,sha256=WSsLiXhQGxbwCaXOy_UxIkjh4EroOKLtJLvWTEiKUXU,13043
+meanwhile/meanwhile-state.sh,sha256=of96sFvI6YRsjQKxk0SppiM5ygJM_Irq7kmAiGLpT50,3678
+meanwhile/pool.py,sha256=CuTeAt21o3DE912I3qsWt3MO7XtCnttTg0rOrBFYUhk,3091
+meanwhile/repo.py,sha256=DppSxfJIh2Qf9I_bITLn1woI_IAc-ZHtvqL0gCoZZMs,809
+meanwhile/scores.py,sha256=FV20gDC35quy394pVu52dUrGg9euQOLZneB_vDrxEDk,1311
+meanwhile/state.py,sha256=w-dGFYVpA0uCYrEEQH4s8gTogQ0aRSX3QD6-ueowFzE,2322
+meanwhile/strings.py,sha256=unvmjwDzhUVWydLtUH3kvz5CaXqL8y6boDEZSP9Eh8s,1743
+meanwhile_cli-0.1.0.dist-info/METADATA,sha256=W98BhVrMN-wJlfwb2W_3mk-_8iqGZkZwLo0U9ZpbF1I,11961
+meanwhile_cli-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+meanwhile_cli-0.1.0.dist-info/entry_points.txt,sha256=nCcGlFSNmJouQGKky1kdjPg0k3o9r9F1jwkburnCJ98,84
+meanwhile_cli-0.1.0.dist-info/licenses/LICENSE,sha256=DvC_3jCIWi5ymiMirFd_wjXj3SwV_wMU0VKF4Txl3Nc,1070
+meanwhile_cli-0.1.0.dist-info/RECORD,,

meanwhile_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any