your-turn 0.4.0__py3-none-any.whl

your_turn-0.4.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: your-turn
+Version: 0.4.0
+Summary: An inbox for your coding agents. See which chat is waiting on you, what each one produced, and what to do next.
+Project-URL: Homepage, https://github.com/martin-gomola/your-turn
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.29
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Your Turn
+
+<p align="center"><strong>Your agents are fast. You're the queue.</strong></p>
+
+![Works with Codex · Claude Code · Cursor](https://img.shields.io/badge/Works%20with-Codex%20%C2%B7%20Claude%20Code%20%C2%B7%20Cursor-56645f)
+![Local · Read-only](https://img.shields.io/badge/Local-Read--only-2f7a6b)
+
+[Your inbox](#your-inbox) · [Quick start](#quick-start) · [Privacy](#privacy) ·
+[Why install the handoff](#why-install-the-handoff) · [Docs](#docs)
+
+</div>
+
+When Codex, Claude Code, and Cursor run side by side, the slow part is your attention. The chat blocked on you sits in a window you are not looking at, and every answer is a long log.
+
+## Your inbox
+
+<div align="center">
+
+<img src="docs/images/desktop.png?v=1" width="800" alt="Your Turn dark inbox in Focus Mode, with Codex, Claude Code, and Cursor chats grouped by status">
+
+<sub>Made-up demo chats from <code>make screenshots</code>, not real session data.</sub>
+
+</div>
+
+<details>
+<summary>See the inbox beside a chat</summary>
+
+<img src="docs/images/in-codex.png?v=1" width="800" alt="Codex chat beside the Your Turn dark inbox in Focus Mode">
+
+</details>
+
+<details>
+<summary>Watch a chat move into Needs you</summary>
+
+<img src="docs/images/demo.gif?v=1" width="800" alt="A chat moves into Needs you when its question arrives, then opens beside the inbox">
+
+</details>
+<br>
+
+**Your Turn** is not another orchestrator, IDE wrapper, or cloud dashboard. It is a read-only, zero-config local inbox on `localhost:8787`. It reads the JSONL logs your agents already write and the local Cursor chat database. It answers three questions at a glance:
+
+- ⏳ **Who is waiting on you?**<br>
+  Questions, pending approvals, and unreviewed results, ordered by how long they have waited.<br>
+- ✅ **Can you trust the result without reading the log?**<br>
+  `Check failed` and `Edits unchecked` badges tied to the latest code edit.<br>
+- ➡️ **What is the exact next step?**<br>
+  One line per chat, with one click to open or resume it in its app.<br>
+
+Your Turn runs on your machine. It does not take over agent processes, run a background service, or send chat data to the cloud. It uses no cloud account or extra agent permissions.
+
+## Quick start
+
+You need Python 3.11+, [`uv`](https://docs.astral.sh/uv/), and Codex, Claude Code, or Cursor. Without `uv`, install it first with `brew install uv` or [uv's installer](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uvx your-turn install
+```
+
+`install` adds the Your Turn handoff instructions to the agent apps it finds, then starts the inbox. Restart those agent apps, then open [http://localhost:8787](http://localhost:8787).
+
+To start the inbox later, run:
+
+```bash
+uvx your-turn serve
+```
+
+The server binds to loopback only (`127.0.0.1`). To check or remove the handoff, run `uvx your-turn doctor` or `uvx your-turn uninstall`.
+
+`uvx your-turn` runs the [PyPI release](https://pypi.org/project/your-turn/), which is built from a Git tag by GitHub Actions. `uvx your-turn@latest` picks up a newer release. To pin a version, use `uvx your-turn@0.4.0`, or install straight from its tag with `uvx --from git+https://github.com/martin-gomola/your-turn@v0.4.0 your-turn`.
+
+### With Nix
+
+The repository is a flake, with dependencies pinned in `flake.lock`. This starts the inbox without changing any agent app:
+
+```bash
+nix run github:martin-gomola/your-turn
+```
+
+Only `install` and `uninstall` change agent app folders. To see what `install` would touch, run `nix run github:martin-gomola/your-turn -- doctor` first. To skip it, add the handoff by hand from [docs/agents-snippet.md](./docs/agents-snippet.md), or print the Cursor rule with `nix run github:martin-gomola/your-turn -- cursor-rule`. `nix profile install github:martin-gomola/your-turn` puts `your-turn` on your `PATH`. To pin a release, use `github:martin-gomola/your-turn/v0.4.0`.
+
+## Privacy
+
+- **Local only.** The server binds to `127.0.0.1`. It does not send session data anywhere.
+- **Read-only session access.** Your Turn reads agent logs and Cursor's local chat database. It never edits them, starts or answers chats, or approves actions.
+- **Small local state file.** `~/.your-turn/state.json` stores seen results and dismissed reminders so they stay in sync across browsers. The browser keeps a local backup.
+- **No account or setup file.** Your Turn finds existing chats and leaves out sub-agents, headless runs, and abandoned chats.
+
+## Why install the handoff?
+
+<details>
+<summary>See how the handoff keeps finished chats out of Needs you</summary>
+
+Agents often end with a polite question such as “Would you like me to update the docs?” Your Turn can read that as a question waiting on you, even when the work is done. The handoff asks the agent to end with an `Outcome` and a `Next step`, so the inbox can show a clear result.
+
+Without the handoff:
+
+```text
+I refactored the token refresh logic and ran pytest. All 12 tests passed.
+Would you like me to update the docs or commit the changes?
+```
+
+With the handoff:
+
+```text
+I refactored the token refresh logic and ran pytest. All 12 tests passed.
+
+**Outcome:** Token refresh is refactored and all 12 tests pass.
+
+**Next step:** none
+```
+
+If an agent needs a decision, answer, review, or approval, `Next step` names it. See the full format in [docs/configuration.md](./docs/configuration.md#your-turn-handoff).
+
+</details>
+
+## Docs
+
+| Guide | What it covers |
+| --- | --- |
+| [docs/harnesses.md](./docs/harnesses.md) | Data sources by OS, supported apps, inbox states, checks, and limits |
+| [docs/configuration.md](./docs/configuration.md) | CLI commands and flags, app setup, handoff format, and development |
+| [DESIGN.md](./DESIGN.md) | UI design contract and references |
+| [docs/agents-snippet.md](./docs/agents-snippet.md) | Handoff format to add to agent instructions by hand |
+
+## Run from a clone
+
+```bash
+git clone https://github.com/martin-gomola/your-turn.git
+cd your-turn
+make install
+```
+
+`make install` sets up the handoff from this checkout and starts the inbox. Open [http://localhost:8787](http://localhost:8787). Later, from the same folder:
+
+```bash
+make up        # start the inbox in the background
+make down      # stop it
+make doctor    # check the handoff without changing it
+make test      # run the test suite
+```
+
+See [docs/configuration.md](./docs/configuration.md#development) for all `make` targets and API routes.
+
+## License
+
+[MIT](./LICENSE). Third-party icons and artwork are listed in [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).

your_turn-0.4.0.dist-info/RECORD

@@ -0,0 +1,47 @@
+yourturn/__init__.py,sha256=42STGor_9nKYXumfeV5tiyD_M8VdcddX7CEexmibPBk,22
+yourturn/app.py,sha256=Y_NY-hzuYXPOTzcZeBIrAMnVU0ylsw1pUUbHsAAf1rk,8027
+yourturn/cli.py,sha256=5RbFnl2jtYT3bwW9s5KNhJucZAZ8lX4jL5vhQ7Jgvos,5925
+yourturn/config.py,sha256=r1q2URbmin9ezIMz6VVV2pRBniLl-TQVDw8KcO0YifQ,562
+yourturn/engine.py,sha256=nV9QiUGWfszQSUYhW_qny--ZGTo41ls9yKx7gmBTSfE,36049
+yourturn/heuristics.py,sha256=jll8Hboi0BHns1kalvdwb1mmzXwR4Mj6FfLmXESayks,17055
+yourturn/install.py,sha256=g5xalQVA-dZxLgMMxZEjqtKxk0vXUeLJPAfCrOnCAxg,22483
+yourturn/model.py,sha256=y5Lf-Ion6VjlTSOMnS9rO9blXkmi1hgpbojfh_TS2ZI,3514
+yourturn/state.py,sha256=1OQBV4MsippHRL8kL8akI0TpDKFc3qKJ6JYt4xUpJSM,3178
+yourturn/harness/__init__.py,sha256=aYV3nQXzYE6bYHjXpVkPhRe3CmgG9CIgJGXYz3_Yt08,96
+yourturn/harness/base.py,sha256=4_UpyUIGFi8r7OX4qv2_NoQLkJJUAUZ28DPI_QlR4Qo,9151
+yourturn/harness/claude.py,sha256=v_3EjdyTt-4ThxQGp4TAxuglYCQvN0LpLFHcVZJlUvs,25450
+yourturn/harness/codex.py,sha256=h0c4q1-8vPC0HZJs1HqWDngz18P2QPd7M4xVwB0OzRE,19249
+yourturn/harness/cursor.py,sha256=kxNgR91sScUeWu0qGz7OMwPwHOilAfDEKPlDu_a32iM,20860
+yourturn/static/app-icon-dark-180.png,sha256=tz5ZLCSEOXXkKcrGQe1IVbH6oCmDcHzB8MLZjNa2YC0,5952
+yourturn/static/app-icon-dark-192.png,sha256=chYhyf3_asjZpAt26TZOvwHynE40Rl7JDW-nlg-zFg4,5900
+yourturn/static/app-icon-dark-512.png,sha256=PzrvQPq-v6ftBakIE2wYQ-QLc9Bzme4vYy-p2COmtpc,16974
+yourturn/static/app-icon-light-180.png,sha256=NgsG8xA-ZVTo0mDmerJKpQFg9yUyfOfbtqYc0dAl9aQ,6183
+yourturn/static/app-icon-light-192.png,sha256=ClHceUmDlYTuxohW3hvoYpiKj7tZHQAd4HIEUnfgcuE,6104
+yourturn/static/app-icon-light-512.png,sha256=D2HkURz6iCpUy7E9WK8VTEHQrHepAK4-hXwUZTQbPfU,16824
+yourturn/static/app.css,sha256=UJHCkGI8v_VGkN44UPdIBYO9q8iUxv2LSttUFlZQzrA,68021
+yourturn/static/app.js,sha256=RmqI18A2xeD_C77yADwVUmQtAzbxL27jaURj-BwRDMg,80538
+yourturn/static/brand-leaf.webp,sha256=qeBru_ZQ-3NEwFo1s6iH2zy3AJfdWRCnR1mUxv8B4L0,4000
+yourturn/static/favicon-alert.ico,sha256=VNhxt-ftKn90sfHABzy6mOlsJFoK0MDObjDmK8F_5Cw,3374
+yourturn/static/favicon-dark-alert.ico,sha256=KmImWO6EXlhb-We5IkcByAJe6bLROyNCcBF7eoDMsGg,3199
+yourturn/static/favicon-dark.ico,sha256=OIJjv94wmectHgKHG9051MNhLFoLifK_bhcEOx-P4fw,3200
+yourturn/static/favicon.ico,sha256=1ov04oH-q01L027axxX8mIHWB3xi94hKLNS2HDO16HI,3362
+yourturn/static/header-dark.webp,sha256=KxOWfTbtcMXviKOik-FxG_0VSAEbra__KC4_yVCWNLs,143772
+yourturn/static/header-light.webp,sha256=0N5rlp5AkmRkLbUQdtwEEkbJEccLJNcP3t3ePwzdTrw,77474
+yourturn/static/icon-alert.svg,sha256=RQSHSZE4oNGjX5PgjzpefjocyiKeK8P9Vlo0yxE-zEI,750
+yourturn/static/icon-dark-alert.svg,sha256=TLtZ2_nDFgezM3zplHwoP2aZGr6zcvViP5pmgtY6W30,820
+yourturn/static/icon-dark.svg,sha256=cWzzh3ctWqyLNIT9YbPK_b1I0s1pOsgHBNEsLKQUhFw,822
+yourturn/static/icon.svg,sha256=2YHRFO9iyxPydy4KQvwbzEtF7a8JvqQizEJxFLGWwNY,756
+yourturn/static/index.html,sha256=eqMHVRX5Q89XbLV0uFX7SNITP8o170fScLHS_uvGW-c,28728
+yourturn/static/navigation.js,sha256=zLeERr_T-WxFCv5Xn0eongkZpKlngxzoKIXqHFq54h8,1232
+yourturn/static/state-sync.js,sha256=VE_WKM6llyOzxFO0GQKYM8V8zA59-rPDRZVWlo0c2-4,4668
+yourturn/static/theme.js,sha256=3jtMaPGvYuFIKxv06ilT_mF82BHW0ImTc19vZklaMPE,1572
+yourturn/static/tokens.css,sha256=J54-W-F9wIXrp6Q6oIgY3l-MQnJuKXXhj8i3T6GZB-w,4507
+yourturn/plugin/.codex-plugin/plugin.json,sha256=IEBace7vXtENoqLucMLCsmCIp06lIfI-zZH21uUPC80,1111
+yourturn/plugin/assets/your-turn-dark.png,sha256=PzrvQPq-v6ftBakIE2wYQ-QLc9Bzme4vYy-p2COmtpc,16974
+yourturn/plugin/assets/your-turn-light.png,sha256=D2HkURz6iCpUy7E9WK8VTEHQrHepAK4-hXwUZTQbPfU,16824
+yourturn/plugin/skills/your-turn-handoff/SKILL.md,sha256=JzA-PaYyz_Z56muGDDcmzsoyTCjK-hd-igVhprFo5GQ,6025
+your_turn-0.4.0.dist-info/METADATA,sha256=Ems7-nD_aj4so4kv7nOZ40PvJUhvB8nNapk71TkoGe4,6976
+your_turn-0.4.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+your_turn-0.4.0.dist-info/entry_points.txt,sha256=xL0nm-Z4nS9mpB6Uwu2a1jT3gxLYju-a7tNJzFTQYWw,77
+your_turn-0.4.0.dist-info/licenses/LICENSE,sha256=g7_Dxduwq94sW6Oir1CbSjuJCVpIfg8EQWtdS3QL0Y4,1070
+your_turn-0.4.0.dist-info/RECORD,,

your_turn-0.4.0.dist-info/WHEEL

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

your_turn-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+your-turn = yourturn.cli:main
+yourturn = yourturn.cli:main

your_turn-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Gomola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yourturn/__init__.py

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

yourturn/app.py

@@ -0,0 +1,158 @@
+"""Loopback-only Your Turn server: an inbox of agent chats (Codex, Claude Code, Cursor) and a per-turn summary of each."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator, Callable
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.responses import HTMLResponse, StreamingResponse
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from yourturn import __version__
+from yourturn.config import DEFAULT_HISTORY_DAYS
+from yourturn.engine import SessionHub
+from yourturn.model import UUID, Harness, SessionKey
+from yourturn.state import InboxState
+
+LOOPBACK_HOSTS = ["127.0.0.1", "localhost", "[::1]"]
+POLL_SECONDS = 1.0
+HEARTBEAT_SECONDS = 15.0
+PAGE_POLICY = (
+    "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; "
+    "base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+)
+ASSET_TYPES = {".css": "text/css", ".js": "text/javascript", ".svg": "image/svg+xml", ".webp": "image/webp", ".png": "image/png", ".ico": "image/x-icon"}
+
+
+def _static(name: str) -> str:
+    return files("yourturn").joinpath("static", name).read_text(encoding="utf-8")
+
+
+def create_app(
+    codex_home: Path, poll_seconds: float = POLL_SECONDS, should_stop: Callable[[], bool] = lambda: False,
+    history_days: int = DEFAULT_HISTORY_DAYS, claude_home: Path | None = None,
+    cursor_home: Path | None = None, cursor_user_dir: Path | None = None, state_path: Path | None = None,
+) -> FastAPI:
+    app = FastAPI(title="Your Turn", docs_url=None, redoc_url=None, openapi_url=None)
+    app.add_middleware(TrustedHostMiddleware, allowed_hosts=LOOPBACK_HOSTS)
+    hub = SessionHub.for_codex_home(codex_home, claude_home=claude_home, cursor_home=cursor_home, cursor_user_dir=cursor_user_dir)
+    state = InboxState(state_path) if state_path else InboxState()
+
+    @app.middleware("http")
+    async def security_headers(request: Request, call_next: Any) -> Response:
+        response: Response = await call_next(request)
+        response.headers["Content-Security-Policy"] = PAGE_POLICY
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["Referrer-Policy"] = "no-referrer"
+        response.headers["Cache-Control"] = "no-store"
+        return response
+
+    served = {Harness(adapter.name) for adapter in hub.adapters}
+
+    def checked(thread: str) -> SessionKey:
+        """Resolve `<harness>:<uuid>` or a bare `<uuid>` (Codex, same rule as `SessionHub.detail`) to a session key.
+
+        Malformed ids -> 400; a well-formed key for a harness with no session source -> 404.
+        """
+        try:
+            key = SessionKey.parse(thread)
+        except ValueError:
+            raise HTTPException(status_code=400, detail="thread must be a session key or Codex thread id") from None
+        if key.harness not in served:
+            raise HTTPException(status_code=404, detail="no session source for this harness")
+        # Codex thread ids, Claude Code session ids and Cursor composer ids are all UUIDs.
+        if not UUID.match(key.native_id):
+            raise HTTPException(status_code=400, detail="thread must be a session key or Codex thread id")
+        return key
+
+    @app.get("/", response_class=HTMLResponse)
+    def index() -> str:
+        return _static("index.html").replace("{{APP_VERSION}}", __version__).replace("{{HISTORY_DAYS}}", str(history_days))
+
+    @app.get("/assets/{name}")
+    def asset(name: str) -> Response:
+        media_type = ASSET_TYPES.get(Path(name).suffix)
+        if media_type is None or name not in {entry.name for entry in files("yourturn").joinpath("static").iterdir()}:
+            raise HTTPException(status_code=404)
+        return Response(files("yourturn").joinpath("static", name).read_bytes(), media_type=media_type)
+
+    @app.get("/api/inbox")
+    def inbox() -> list[dict[str, Any]]:
+        return hub.inbox_dicts(history_days)
+
+    @app.get("/api/threads/{thread}")
+    def thread_state(thread: str) -> dict[str, Any]:
+        data = hub.detail_dict(checked(thread))
+        if data is None:
+            raise HTTPException(status_code=404, detail="no session file for this thread")
+        return data
+
+    @app.post("/api/state", status_code=204)
+    async def write_state(request: Request) -> None:
+        """Mark results seen or reminders dismissed for every browser; streams push the change to the others."""
+        # JSON from this page only: a cross-site form cannot send JSON, and a cross-site fetch carries its Origin.
+        origin = request.headers.get("origin")
+        if not request.headers.get("content-type", "").startswith("application/json") or (
+                origin and urlsplit(origin).hostname not in {"127.0.0.1", "localhost", "::1"}):
+            raise HTTPException(status_code=403)
+        try:
+            body = await request.json()
+        except ValueError:
+            raise HTTPException(status_code=400) from None
+
+        def entries(name: str, nullable: bool) -> dict[str, Any]:
+            values = body.get(name) or {} if isinstance(body, dict) else None
+            if not isinstance(values, dict) or not all(isinstance(v, str) or (nullable and v is None) for v in values.values()):
+                raise HTTPException(status_code=400, detail=f"{name} must map chat keys to strings")
+            return {str(checked(key)): value for key, value in values.items()}
+
+        seen, dismissed = entries("seen", False), entries("dismissed", True)
+        stamps = body.get("dismissed_at", {})
+        if not isinstance(stamps, dict) or not all(type(v) is int and 0 <= v <= 2**53 - 1 for v in stamps.values()):
+            raise HTTPException(status_code=400, detail="dismissed_at must map chat keys to timestamps")
+        stamps = {str(checked(key)): value for key, value in stamps.items()}
+        if not stamps.keys() <= dismissed.keys():
+            raise HTTPException(status_code=400, detail="timestamps require a matching dismissal or restore")
+        keep = {row["key"] for row in await asyncio.to_thread(hub.inbox_dicts, history_days)}
+        await asyncio.to_thread(state.update, seen, dismissed, keep, stamps)
+
+    @app.get("/api/stream")
+    async def stream(request: Request, thread: str | None = None) -> StreamingResponse:
+        key: SessionKey | None = checked(thread) if thread else None
+
+        def current(last: str | None) -> tuple[str, Any]:
+            """Blocking file reads; called off the event loop so one large chat cannot stall every stream."""
+            if key is not None:
+                data = hub.detail_dict(key)
+                return (f"{data['version']}:{data['quiet']}" if data else "missing"), data
+            if last is None:
+                # Warm the entry cache so the first marker already knows which chats are quiet.
+                hub.inbox_dicts(history_days)
+            marker = hub.inbox_fingerprint(history_days)
+            return marker, hub.inbox_dicts(history_days) if marker != last else None
+
+        async def events() -> AsyncIterator[str]:
+            last, idle, shared = None, 0.0, -1
+            while not should_stop() and not await request.is_disconnected():
+                if state.version != shared:
+                    shared = state.version
+                    yield f"event: state\ndata: {json.dumps(state.snapshot())}\n\n"
+                marker, data = await asyncio.to_thread(current, last)
+                if marker != last:
+                    last, idle = marker, 0.0
+                    yield f"event: {'thread' if thread else 'inbox'}\ndata: {json.dumps(data)}\n\n"
+                elif idle >= HEARTBEAT_SECONDS:
+                    idle = 0.0
+                    yield ": heartbeat\n\n"
+                await asyncio.sleep(poll_seconds)
+                idle += poll_seconds
+
+        return StreamingResponse(events(), media_type="text/event-stream")
+
+    return app

yourturn/cli.py

@@ -0,0 +1,122 @@
+"""`your-turn` (or `your-turn serve`) runs the dashboard; `your-turn install` sets up the handoff for every
+agent app found (globally, never in a project), then, run in a terminal, starts the dashboard unless it is
+already running; `your-turn uninstall` removes it; `your-turn
+doctor` reports whether the installed handoff is current, without changing anything; `your-turn cursor-rule`
+prints the Cursor User Rule to paste into Cursor's settings."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+from yourturn.install import APPS, detect, doctor, install, rule_text, uninstall
+
+SERVE = "uvx your-turn serve"
+PORT = 8787
+
+
+def _url(port: int) -> str:
+    """The address to show: the server binds only 127.0.0.1, which `localhost` reaches and is easier to type."""
+    return f"http://localhost:{port}"
+
+
+def _interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def _inbox_running(port: int) -> bool:
+    """Whether Your Turn already answers on the port, as `make up` checks it."""
+    try:
+        with urllib.request.urlopen(f"http://127.0.0.1:{port}/api/inbox", timeout=1):
+            return True
+    except OSError:
+        return False
+
+
+def main(argv: list[str] | None = None) -> int | None:
+    argv = sys.argv[1:] if argv is None else argv
+    # No subcommand, or only serve options: serve.
+    if not argv or (argv[0].startswith("-") and argv[0] not in ("-h", "--help")):
+        argv = ["serve", *argv]
+    parser = argparse.ArgumentParser(prog="your-turn")
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name, help_text in (("serve", "Run the dashboard on localhost"),
+                            ("install", "Set up the handoff for Codex, Claude Code and Cursor, then start the dashboard"),
+                            ("uninstall", "Remove the handoff that install set up"),
+                            ("doctor", "Check, without changing anything, whether the installed handoff is current")):
+        command = commands.add_parser(name, help=help_text)
+        if name == "serve":
+            command.add_argument("--port", type=int, default=PORT)
+            command.add_argument("--cursor-user-dir", type=Path, default=None,
+                                 help="Cursor user data folder holding globalStorage/state.vscdb (default: per OS)")
+        else:
+            command.add_argument("--harness", choices=[*APPS, "all"], default=None,
+                                 help="Only this app, or all three (default: every app whose folder exists)")
+        command.add_argument("--codex-home", type=Path,
+                             default=Path(os.environ.get("CODEX_HOME", Path.home() / ".codex")))
+        command.add_argument("--claude-home", type=Path,
+                             default=Path(os.environ.get("CLAUDE_CONFIG_DIR", Path.home() / ".claude")))
+        command.add_argument("--cursor-home", type=Path, default=Path.home() / ".cursor",
+                             help="Cursor home holding projects/*/agent-transcripts (default: ~/.cursor)")
+    commands.add_parser("cursor-rule", help="Print the Cursor User Rule to paste into Customize → Rules")
+    args = parser.parse_args(argv)
+
+    if args.command == "cursor-rule":
+        print(rule_text("cursor"), end="", flush=True)
+        return 0
+
+    if args.command in ("install", "uninstall", "doctor"):
+        homes = {"codex": args.codex_home, "claude": args.claude_home, "cursor": args.cursor_home}
+        harnesses = list(APPS) if args.harness == "all" else [args.harness] if args.harness else detect(homes)
+        if args.command == "doctor":
+            return doctor(harnesses, homes)
+        try:
+            done = (install if args.command == "install" else uninstall)(harnesses, homes)
+        except subprocess.CalledProcessError as error:
+            parser.exit(1, f"Plugin install failed: {' '.join(error.cmd)}\n")
+        if args.command == "uninstall":
+            return
+        names = [APPS[harness] for harness in done]
+        apps = ", ".join(names[:-1]) + f" and {names[-1]}" if len(names) > 1 else "".join(names)
+        restart = f"Restart {apps} to load the handoff" if names else ""
+        # Run from a script, or with input or output redirected, install only sets up and exits.
+        if not _interactive():
+            start = f"start the inbox with: {SERVE} (or `make up` in a clone)"
+            print(f"\n→ {restart}, then {start}" if restart else f"\n→ {start[0].upper()}{start[1:]}", flush=True)
+            return
+        if restart:
+            print(f"\n→ {restart}.", flush=True)
+        if _inbox_running(PORT):
+            print(f"→ Your Turn is already running at {_url(PORT)}", flush=True)
+            return
+        print(f"→ Next time, start the inbox with: {SERVE}", flush=True)
+        args.port, args.cursor_user_dir = PORT, None
+
+    import uvicorn
+
+    from yourturn.app import create_app
+
+    from yourturn.config import load_history_days
+
+    try:
+        history_days = load_history_days()
+    except (OSError, ValueError) as error:
+        parser.error(f"Cannot read Your Turn config: {error}")
+
+    print(f"Starting Your Turn at {_url(args.port)}. Press Ctrl+C to stop it.", flush=True)
+    try:
+        uvicorn.run(create_app(args.codex_home, history_days=history_days, claude_home=args.claude_home,
+                               cursor_home=args.cursor_home, cursor_user_dir=args.cursor_user_dir),
+                    host="127.0.0.1", port=args.port, log_level="warning")
+    except SystemExit as error:
+        if error.code not in (None, 0):
+            print(
+                f"Could not start Your Turn. If it is already running, open {_url(args.port)} "
+                f"in your browser. Otherwise, try another port: your-turn serve --port 8788.",
+                file=sys.stderr,
+            )
+        raise

yourturn/config.py

@@ -0,0 +1,17 @@
+"""Local dashboard configuration, loaded when the server starts."""
+
+from pathlib import Path
+import tomllib
+
+DEFAULT_HISTORY_DAYS = 14
+CONFIG_PATH = Path(__file__).resolve().parents[2] / "config.toml"
+
+
+def load_history_days(path: Path = CONFIG_PATH) -> int:
+    if not path.exists():
+        return DEFAULT_HISTORY_DAYS
+    with path.open("rb") as handle:
+        days = tomllib.load(handle).get("history_days", DEFAULT_HISTORY_DAYS)
+    if type(days) is not int or days < 1:
+        raise ValueError("history_days must be a positive integer")
+    return days