meanwhile-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{meanwhile_cli-0.1.0 → meanwhile_cli-0.1.1}/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "meanwhile",
       "source": ".",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "description": "Play a quiz about your own repository while Claude Code is working, so your context stays loaded for the diff review that follows."
     }
   ]

{meanwhile_cli-0.1.0 → meanwhile_cli-0.1.1}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "meanwhile",
   "description": "Play a quiz about your own repository while Claude Code is working, so your context stays loaded for the diff review that follows.",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "author": {
     "name": "Ismail Bayram"
   },

meanwhile_cli-0.1.1/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: meanwhile-cli
+Version: 0.1.1
+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
+
+A quiz about your own repository that you play while your coding agent works,
+so the code is still fresh in your head when the diff lands. Works with
+Claude Code, Codex, Cursor and OpenCode.
+
+<p align="center">
+  <img src="docs/images/card.svg" alt="A multiple-choice card about the repository, waiting for an answer" width="720">
+</p>
+
+<p align="center">
+  <img src="docs/images/done.svg" alt="The answered card, with a banner saying Claude Code is done" width="720">
+</p>
+
+## Quick start
+
+Three steps, once per machine and project:
+
+1. **Connect your agent** — see [Installation](#installation) for your agent.
+2. **Build the question pool**, once per project:
+   - Claude Code: run `/meanwhile-build`
+   - any other agent: run `uvx meanwhile-cli build-prompt --lang en --repo .`
+     and paste the output to your agent
+3. **Open a second terminal** in the same directory as your agent and run:
+
+   ```
+   uvx meanwhile-cli
+   ```
+
+The pane starts asking questions right away. When your agent finishes a
+prompt, the pane tells you so you can switch back to the diff.
+
+## Installation
+
+You need [uv](https://docs.astral.sh/uv/) for the `uvx` commands. Then pick
+your agent:
+
+### Claude Code
+
+```
+/plugin marketplace add ismailbayram/meanwhile
+/plugin install meanwhile@meanwhile
+```
+
+Restart Claude Code.
+
+### Codex
+
+```
+codex plugin marketplace add ismailbayram/meanwhile
+```
+
+Install `meanwhile` from the Plugins Directory, then **review and trust its
+hooks** — Codex skips plugin hooks until you do.
+
+### Cursor
+
+```
+uvx meanwhile-cli hooks install --agent cursor
+```
+
+### OpenCode
+
+```
+uvx meanwhile-cli hooks install --agent opencode
+```
+
+Restart OpenCode.
+
+### Installing the command permanently (optional)
+
+`uvx` runs the latest version without installing anything. If you prefer a
+regular command:
+
+```
+uv tool install meanwhile-cli    # or: pipx install meanwhile-cli
+```
+
+The command is then just `meanwhile` — use it wherever this README says
+`uvx meanwhile-cli`.
+
+## Usage
+
+| Key | Action |
+| --- | --- |
+| `1`–`9` | answer |
+| `space` | next card |
+| `q` | quit |
+
+- Start the pane **from the same directory you started your agent in**,
+  otherwise it cannot tell when the agent is done. The quiz itself works
+  either way.
+- Leave it open all day. Each new prompt after the agent finishes deals a
+  fresh round; when the pool runs out, `space` starts a new one.
+- The interface follows the pool's language. Override it with
+  `--lang tr` or `--lang en`.
+
+## The question pool
+
+`/meanwhile-build` (or `build-prompt`) has the agent read your repository and
+write `.meanwhile/pool.json` — 30 to 50 multiple-choice questions. An entry
+looks like this:
+
+```json
+{
+  "type": "quiz",
+  "q": "What happens to an order's reserved stock when payment fails?",
+  "choices": [
+    "It stays reserved until an admin releases it",
+    "It is released back to inventory after 15 minutes",
+    "It is released immediately and the order is cancelled"
+  ],
+  "answer": 1,
+  "why": "release_expired_reservations runs every 15 minutes and returns unpaid stock to inventory.",
+  "source": "shop/orders/tasks.py"
+}
+```
+
+- **Commit `pool.json`** so the whole team plays the same pool and nobody pays
+  to build it again.
+- **Language:** `--lang` takes a language code, not a name. `tr` and `en` are
+  the two the interface speaks; any other code (`de`, `fr`, …) writes the
+  questions in that language and keeps the interface in English.
+- **Refreshing:** when the repository is about 50 commits past the pool, the
+  pane shows a banner. Run the build step again and commit the new file.
+  Nothing is regenerated automatically.
+- Scores are kept in `.meanwhile/scores.json`, which is gitignored.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `uvx meanwhile-cli` | open the quiz pane |
+| `uvx meanwhile-cli build-prompt --lang en --repo .` | print the pool-building instructions for any agent |
+| `uvx meanwhile-cli validate --repo .` | check `pool.json` |
+| `uvx meanwhile-cli hooks install --agent <agent>` | connect an agent without its plugin (`claude`, `codex`, `cursor`, `opencode`); add `--user` for every project (not Cursor) |
+| `uvx meanwhile-cli hooks status` | show which agents are connected |
+| `uvx meanwhile-cli hooks uninstall --agent <agent>` | disconnect |
+
+`hooks install` writes an absolute path from your machine into the agent's
+config, so don't commit that file for Codex, Cursor or OpenCode.
+
+## How it works
+
+Hooks in your agent write `busy` or `idle` to a small file in
+`~/.meanwhile/state/` when you send a prompt and when the agent finishes. The
+pane watches that file and shows cards from `pool.json`. Only the build step
+uses an LLM; the pane makes no network calls.
+
+## Development
+
+From a checkout of this repository, use `uv run meanwhile` in place of
+`uvx meanwhile-cli`, and `/plugin marketplace add /path/to/meanwhile` for the
+Claude Code plugin. Tests: `uv run --extra dev python -m pytest`.

meanwhile_cli-0.1.1/README.md

@@ -0,0 +1,154 @@
+# meanwhile
+
+A quiz about your own repository that you play while your coding agent works,
+so the code is still fresh in your head when the diff lands. Works with
+Claude Code, Codex, Cursor and OpenCode.
+
+<p align="center">
+  <img src="docs/images/card.svg" alt="A multiple-choice card about the repository, waiting for an answer" width="720">
+</p>
+
+<p align="center">
+  <img src="docs/images/done.svg" alt="The answered card, with a banner saying Claude Code is done" width="720">
+</p>
+
+## Quick start
+
+Three steps, once per machine and project:
+
+1. **Connect your agent** — see [Installation](#installation) for your agent.
+2. **Build the question pool**, once per project:
+   - Claude Code: run `/meanwhile-build`
+   - any other agent: run `uvx meanwhile-cli build-prompt --lang en --repo .`
+     and paste the output to your agent
+3. **Open a second terminal** in the same directory as your agent and run:
+
+   ```
+   uvx meanwhile-cli
+   ```
+
+The pane starts asking questions right away. When your agent finishes a
+prompt, the pane tells you so you can switch back to the diff.
+
+## Installation
+
+You need [uv](https://docs.astral.sh/uv/) for the `uvx` commands. Then pick
+your agent:
+
+### Claude Code
+
+```
+/plugin marketplace add ismailbayram/meanwhile
+/plugin install meanwhile@meanwhile
+```
+
+Restart Claude Code.
+
+### Codex
+
+```
+codex plugin marketplace add ismailbayram/meanwhile
+```
+
+Install `meanwhile` from the Plugins Directory, then **review and trust its
+hooks** — Codex skips plugin hooks until you do.
+
+### Cursor
+
+```
+uvx meanwhile-cli hooks install --agent cursor
+```
+
+### OpenCode
+
+```
+uvx meanwhile-cli hooks install --agent opencode
+```
+
+Restart OpenCode.
+
+### Installing the command permanently (optional)
+
+`uvx` runs the latest version without installing anything. If you prefer a
+regular command:
+
+```
+uv tool install meanwhile-cli    # or: pipx install meanwhile-cli
+```
+
+The command is then just `meanwhile` — use it wherever this README says
+`uvx meanwhile-cli`.
+
+## Usage
+
+| Key | Action |
+| --- | --- |
+| `1`–`9` | answer |
+| `space` | next card |
+| `q` | quit |
+
+- Start the pane **from the same directory you started your agent in**,
+  otherwise it cannot tell when the agent is done. The quiz itself works
+  either way.
+- Leave it open all day. Each new prompt after the agent finishes deals a
+  fresh round; when the pool runs out, `space` starts a new one.
+- The interface follows the pool's language. Override it with
+  `--lang tr` or `--lang en`.
+
+## The question pool
+
+`/meanwhile-build` (or `build-prompt`) has the agent read your repository and
+write `.meanwhile/pool.json` — 30 to 50 multiple-choice questions. An entry
+looks like this:
+
+```json
+{
+  "type": "quiz",
+  "q": "What happens to an order's reserved stock when payment fails?",
+  "choices": [
+    "It stays reserved until an admin releases it",
+    "It is released back to inventory after 15 minutes",
+    "It is released immediately and the order is cancelled"
+  ],
+  "answer": 1,
+  "why": "release_expired_reservations runs every 15 minutes and returns unpaid stock to inventory.",
+  "source": "shop/orders/tasks.py"
+}
+```
+
+- **Commit `pool.json`** so the whole team plays the same pool and nobody pays
+  to build it again.
+- **Language:** `--lang` takes a language code, not a name. `tr` and `en` are
+  the two the interface speaks; any other code (`de`, `fr`, …) writes the
+  questions in that language and keeps the interface in English.
+- **Refreshing:** when the repository is about 50 commits past the pool, the
+  pane shows a banner. Run the build step again and commit the new file.
+  Nothing is regenerated automatically.
+- Scores are kept in `.meanwhile/scores.json`, which is gitignored.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `uvx meanwhile-cli` | open the quiz pane |
+| `uvx meanwhile-cli build-prompt --lang en --repo .` | print the pool-building instructions for any agent |
+| `uvx meanwhile-cli validate --repo .` | check `pool.json` |
+| `uvx meanwhile-cli hooks install --agent <agent>` | connect an agent without its plugin (`claude`, `codex`, `cursor`, `opencode`); add `--user` for every project (not Cursor) |
+| `uvx meanwhile-cli hooks status` | show which agents are connected |
+| `uvx meanwhile-cli hooks uninstall --agent <agent>` | disconnect |
+
+`hooks install` writes an absolute path from your machine into the agent's
+config, so don't commit that file for Codex, Cursor or OpenCode.
+
+## How it works
+
+Hooks in your agent write `busy` or `idle` to a small file in
+`~/.meanwhile/state/` when you send a prompt and when the agent finishes. The
+pane watches that file and shows cards from `pool.json`. Only the build step
+uses an LLM; the pane makes no network calls.
+
+## Development
+
+From a checkout of this repository, use `uv run meanwhile` in place of
+`uvx meanwhile-cli`, and `/plugin marketplace add /path/to/meanwhile` for the
+Claude Code plugin. Tests: `uv run --extra dev python -m pytest`.

{meanwhile_cli-0.1.0 → meanwhile_cli-0.1.1}/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "meanwhile",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Play a quiz about your own repository while Claude Code is working, so your context stays loaded for the diff review that follows.",
   "author": {
     "name": "Ismail Bayram"

{meanwhile_cli-0.1.0 → meanwhile_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meanwhile-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Play a quiz about your own repository while your coding agent works"
 readme = "README.md"
 requires-python = ">=3.10"

meanwhile_cli-0.1.1/src/meanwhile/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

{meanwhile_cli-0.1.0 → meanwhile_cli-0.1.1}/src/meanwhile/app.py

@@ -12,9 +12,9 @@ from textual.widgets import Footer, Static
 from . import agents, game, scores, strings
 from .pool import Pool, QuizItem
 
-# Lifecycle phases. The pane is opened once and left open: it waits for the
-# agent to start, plays for exactly as long as it is busy, then waits again.
-WAITING = "waiting"
+# Lifecycle phases. The pane deals cards as soon as it opens — a pool is all
+# it needs. The agent's hooks only add to that: an idle edge freezes the card
+# and says the agent is done, and the next busy edge deals a fresh round.
 PLAYING = "playing"
 DONE = "done"
 
@@ -53,7 +53,7 @@ class MeanwhileApp(App):
         self.language = language
         self.agent_source = agent_source
         self.session = game.start_session(pool)
-        self.phase = WAITING
+        self.phase = PLAYING
         self._last_status = "idle"
         self._answered = False
 
@@ -115,6 +115,10 @@ class MeanwhileApp(App):
             self._finish_playing()
 
     def _start_playing(self) -> None:
+        if self.phase == PLAYING:
+            # Already dealing — the pane was opened before the prompt. Keep the
+            # card on screen rather than reshuffling under the player.
+            return
         self.phase = PLAYING
         self.session = game.start_session(self.pool)  # re-shuffled: the cards come back
         self._answered = False
@@ -128,14 +132,24 @@ class MeanwhileApp(App):
         self.phase = DONE
         self.refresh_bindings()  # DONE takes no input: the card keys leave the footer
         self.query_one("#status").update(strings.text(self.language, "done", agent=self._agent_name()))
-        # Exactly once per session: the `phase != PLAYING` guard above is what
-        # guarantees it — the only way back into PLAYING is _start_playing,
-        # which deals a new session.
+        self._record()
+
+    def _record(self) -> None:
+        # Exactly once per session: both callers leave PLAYING first, and the
+        # only way back into it is _start_playing, which deals a new session.
         if self.repo_dir is not None and self.session.answered:
             scores.record_session(self.repo_dir, self.session)
 
     # --- actions --------------------------------------------------------
 
+    async def action_quit(self) -> None:
+        # Without hooks there is never an idle edge, so quitting is the only
+        # moment a session ends. Score it here rather than lose it.
+        if self.phase == PLAYING:
+            self.phase = DONE
+            self._record()
+        self.exit()
+
     def action_choose(self, number: int) -> None:
         item = game.current(self.session)
         if self.phase != PLAYING or self._answered or not isinstance(item, QuizItem):
@@ -146,7 +160,18 @@ class MeanwhileApp(App):
         self._resolve(game.answer(self.session, index))
 
     def action_next(self) -> None:
-        if self.phase != PLAYING or not self._answered:
+        if self.phase != PLAYING:
+            return
+        if game.current(self.session) is None:
+            # Out of cards. Without hooks no busy edge will ever come to deal
+            # another round, so `space` does it: bank this one, start afresh.
+            self._record()
+            self.session = game.start_session(self.pool)
+            self._answered = False
+            self.query_one("#feedback").update("")
+            self._render()
+            return
+        if not self._answered:
             return
         game.advance(self.session)
         self._answered = False
@@ -166,12 +191,6 @@ class MeanwhileApp(App):
         # `check_action` has too.
         self.refresh_bindings()
         card = self.query_one("#card")
-        if self.phase == WAITING:
-            self.query_one("#status").update(strings.text(self.language, "waiting", agent=self._agent_name()))
-            card.update("")
-            self.query_one("#score").update("")
-            return
-
         item = game.current(self.session)
         if item is None:
             card.update(strings.text(self.language, "exhausted"))

{meanwhile_cli-0.1.0 → meanwhile_cli-0.1.1}/src/meanwhile/strings.py

@@ -1,4 +1,4 @@
-"""The interface's six strings, in the languages meanwhile ships.
+"""The interface's 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
@@ -10,23 +10,21 @@ from __future__ import annotations
 
 DEFAULT_LANGUAGE = "en"
 
-KEYS = ("waiting", "done", "exhausted", "stale", "correct", "wrong", "agent")
+KEYS = ("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.",
+        "exhausted": "That was every question in the pool — press space for 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.",
+        "exhausted": "Havuzdaki bütün sorular bitti — yeni tur için boşluğa bas.",
         "stale": "havuz {behind} commit geride — tazelemek için build komutunu çalıştır",
         "correct": "doğru",
         "wrong": "yanlış",

{meanwhile_cli-0.1.0 → meanwhile_cli-0.1.1}/tests/test_app.py

@@ -6,7 +6,7 @@ from textual.binding import Binding
 from textual.widgets import Footer
 
 from meanwhile import game, scores, state, strings
-from meanwhile.app import DONE, PLAYING, WAITING, MeanwhileApp
+from meanwhile.app import DONE, PLAYING, MeanwhileApp
 from meanwhile.pool import Pool, QuizItem
 from meanwhile.scores import SCORES_RELPATH
 
@@ -207,7 +207,7 @@ async def test_going_idle_with_no_repo_dir_does_not_write_or_raise(tmp_path):
         assert not (tmp_path / SCORES_RELPATH).exists()
 
 
-# --- lifecycle: waiting -> playing -> done -> playing ----------------------
+# --- lifecycle: playing -> done -> playing ---------------------------------
 
 
 def lifecycle_app(items, status, tmp_path, poll_seconds=60):
@@ -222,8 +222,10 @@ def lifecycle_app(items, status, tmp_path, poll_seconds=60):
     )
 
 
-async def test_launching_while_idle_with_no_state_file_waits(tmp_path):
-    """The order the README documents: open the pane before submitting a prompt."""
+async def test_launching_with_no_state_file_deals_a_card_at_once(tmp_path):
+    """A pool is all the pane needs. Hooks that never ran — not installed yet,
+    agent not restarted, pane opened in another directory — must not leave the
+    player staring at an empty screen."""
     project = tmp_path / "project"
     project.mkdir()
     empty_state_root = tmp_path / "no-state-here"  # the hooks have never run
@@ -236,18 +238,32 @@ async def test_launching_while_idle_with_no_state_file_waits(tmp_path):
         poll_seconds=60,
     )
     async with app.run_test() as pilot:
-        poll(app, times=5)  # several polls: none of them may end the game
+        poll(app, times=5)  # several idle polls: none of them may end the game
         await pilot.pause()
-        assert app.phase == WAITING
+        assert app.phase == PLAYING
+        assert "passport_groups" in text_of(app.query_one("#card"))
         assert "done" not in text_of(app.query_one("#status")).lower()
-        assert "waiting" in text_of(app.query_one("#status")).lower()
-        assert text_of(app.query_one("#card")) == ""
 
-        await pilot.press("2")  # waiting: no card, no input
-        assert app.session.answered == 0
-        app.action_choose(2)  # and the handler refuses it too
-        assert app.session.answered == 0
-        assert not (tmp_path / SCORES_RELPATH).exists()
+        await pilot.press("2")
+        await pilot.pause()
+        assert app.session.correct == 1
+
+
+async def test_a_busy_edge_while_already_playing_keeps_the_card(tmp_path):
+    """Opened before the prompt, the pane is already dealing. The prompt that
+    follows must not reshuffle the card out from under the player."""
+    status = {"value": "idle"}
+    app = lifecycle_app([QUIZ, NARROW], status, tmp_path)
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        session, card = app.session, text_of(app.query_one("#card"))
+
+        status["value"] = "busy"
+        poll(app)
+        await pilot.pause()
+        assert app.phase == PLAYING
+        assert app.session is session
+        assert text_of(app.query_one("#card")) == card
 
 
 async def test_a_second_busy_period_plays_a_fresh_session(tmp_path):
@@ -256,15 +272,15 @@ async def test_a_second_busy_period_plays_a_fresh_session(tmp_path):
     async with app.run_test() as pilot:
         poll(app)
         await pilot.pause()
-        assert app.phase == WAITING
+        assert app.phase == PLAYING
+        first_session = app.session
 
         status["value"] = "busy"
         poll(app)
         await pilot.pause()
-        assert app.phase == PLAYING
-        first_session = app.session
         await pilot.press("2")
         await pilot.pause()
+        assert app.session is first_session
         assert app.session.answered == 1
 
         status["value"] = "idle"
@@ -291,6 +307,52 @@ async def test_a_second_busy_period_plays_a_fresh_session(tmp_path):
         assert saved["answered"] == 2  # both sessions banked, neither one twice
 
 
+async def test_space_on_an_exhausted_pool_deals_a_fresh_round(tmp_path):
+    status = {"value": "idle"}
+    app = lifecycle_app([QUIZ], status, tmp_path)
+    async with app.run_test() as pilot:
+        await pilot.press("2")
+        await pilot.press("space")
+        await pilot.pause()
+        assert game.current(app.session) is None
+        assert "space" in text_of(app.query_one("#card"))
+
+        await pilot.press("space")
+        await pilot.pause()
+        assert game.current(app.session) is QUIZ
+        assert app.session.answered == 0
+    saved = json.loads((tmp_path / SCORES_RELPATH).read_text(encoding="utf-8"))
+    assert saved["answered"] == 1  # the finished round was banked, and only once
+
+
+async def test_quitting_mid_session_banks_it(tmp_path):
+    """Without hooks there is never an idle edge, so `q` is where a session ends."""
+    status = {"value": "idle"}
+    app = lifecycle_app([QUIZ], status, tmp_path)
+    async with app.run_test() as pilot:
+        await pilot.press("2")
+        await pilot.pause()
+        await pilot.press("q")
+        await pilot.pause()
+    saved = json.loads((tmp_path / SCORES_RELPATH).read_text(encoding="utf-8"))
+    assert saved["answered"] == 1
+
+
+async def test_quitting_after_done_does_not_bank_twice(tmp_path, monkeypatch):
+    calls = []
+    monkeypatch.setattr(scores, "record_session", lambda repo_dir, session: calls.append(session))
+    status = {"value": "busy"}
+    app = lifecycle_app([QUIZ], status, tmp_path)
+    async with app.run_test() as pilot:
+        await pilot.press("2")
+        status["value"] = "idle"
+        poll(app)
+        await pilot.pause()
+        await pilot.press("q")
+        await pilot.pause()
+    assert len(calls) == 1
+
+
 async def test_a_session_is_banked_once_no_matter_how_many_idle_polls(tmp_path, monkeypatch):
     calls = []
     monkeypatch.setattr(scores, "record_session", lambda repo_dir, session: calls.append(session))
@@ -353,14 +415,6 @@ async def test_the_footer_follows_the_card_not_the_widest_card_in_the_pool(tmp_p
         assert sorted(seen) == [2, 3]  # both widths really were on screen
 
 
-async def test_the_waiting_screen_offers_no_card_keys(tmp_path):
-    app = app_for([QUIZ, NARROW], status="idle", tmp_path=tmp_path)
-    async with app.run_test() as pilot:
-        await pilot.pause()
-        assert app.phase == WAITING
-        assert card_keys(app) == []
-
-
 async def test_the_done_screen_offers_no_card_keys(tmp_path):
     status = {"value": "busy"}
     app = lifecycle_app([QUIZ, NARROW], status, tmp_path)
@@ -399,12 +453,12 @@ async def test_space_does_nothing_before_the_card_is_answered(tmp_path):
 # --- language ---------------------------------------------------------
 
 
-async def test_the_waiting_line_is_turkish_when_the_pool_is(tmp_path):
-    app = app_for([QUIZ], status="idle", tmp_path=tmp_path, language="tr")
+async def test_the_done_line_is_turkish_when_the_pool_is(tmp_path):
+    app = app_for([QUIZ], tmp_path=tmp_path, language="tr")
     async with app.run_test() as pilot:
-        await pilot.pause()
+        await drive_to_done(app, pilot)
         assert text_of(app.query_one("#status")) == strings.text(
-            "tr", "waiting", agent=strings.text("tr", "agent")
+            "tr", "done", agent=strings.text("tr", "agent")
         )
 
 

{meanwhile_cli-0.1.0 → meanwhile_cli-0.1.1}/tests/test_strings.py

@@ -14,7 +14,7 @@ def test_an_unknown_language_falls_back_to_english():
 
 
 def test_turkish_and_english_differ():
-    assert strings.text("tr", "waiting", agent="Codex") != strings.text("en", "waiting", agent="Codex")
+    assert strings.text("tr", "done", agent="Codex") != strings.text("en", "done", agent="Codex")
 
 
 def test_the_agent_name_is_substituted():

meanwhile_cli-0.1.0/PKG-INFO

@@ -1,265 +0,0 @@
-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/README.md

@@ -1,250 +0,0 @@
-# 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/src/meanwhile/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"