your-turn 0.4.0__tar.gz

your_turn-0.4.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+docs/design
+docs/verification.md
+# Added by code-review-graph
+.code-review-graph/
+# Personal agent and editor setup
+.claude/
+.cursor/
+.cursorrules
+.mcp.json
+/CLAUDE.md
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+.agentsroom/fork-context-*.txt
+.agentsroom/transfer-context-*.txt

your_turn-0.4.0/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.

your_turn-0.4.0/PKG-INFO

@@ -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/README.md

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

@@ -0,0 +1,29 @@
+# Third-party assets
+
+The Settings, menu, inbox and question-message glyphs in the HTML sprite are from [Tabler Icons](https://github.com/tabler/tabler-icons), retrieved 30 October 2026. They are distributed under the MIT license:
+
+MIT License
+
+Copyright (c) 2020-2026 Paweł Kuna
+
+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.
+
+The decorative header scenes and leaf artwork were generated for this project with AI image generation and are not third-party assets.
+
+The footer's GitHub mark is GitHub's logo, used only to link to this project's repository. Its path comes from [Simple Icons](https://github.com/simple-icons/simple-icons) (CC0 1.0).

your_turn-0.4.0/config.toml

@@ -0,0 +1,2 @@
+# Chats updated within this many days appear in the inbox. Restart the server after changes.
+history_days = 14

your_turn-0.4.0/docs/agents-snippet.md

@@ -0,0 +1,39 @@
+# Handoff format without automatic setup
+
+Your Turn supports Codex, Claude Code, and Cursor. `your-turn install` adds the handoff instructions
+to each app in its native way. If you want to set them up yourself, paste the block below into an
+instruction file that your agent reads, such as `~/.codex/AGENTS.md` for Codex or a repository's
+applicable instruction file.
+
+The handoff is plain text; Your Turn reads it from the agent's final answer to build recaps and find
+next steps.
+
+```markdown
+## Your Turn handoff
+
+I run many agent chats at once, across apps, and triage them in the Your Turn inbox. End every response
+to me, on every turn, with these lines at the very top or the very bottom, as one group with no prose
+between them, each on one line with a blank line between them (chat apps join adjacent lines into one
+paragraph), as plain Markdown outside code blocks:
+
+**Outcome:** <one sentence: what is now true, or what you found>
+
+**Next step:** <none | answer: <question> | decide: <options> | review: <what to look at> | approve: <plan> | run: <command>>
+
+**Recap:** <from the second turn on, 1-2 sentences under 400 characters: the chat's goal, what is settled, what is open>
+
+**Decision:** <question> -> <chosen> (over <alternatives>). <reason>
+
+Keep the labels and prefixes in English, even when you reply in another language, and start no other
+line with them. Any step other than `none` puts the chat under Needs you; start it with one of the
+prefixes above. A question I must react to also goes in the next step. When the task is done, write
+exactly `Next step: none` and stop; an optional suggestion goes in the body, and never close with a
+polite offer such as "Let me know if…" or "Should I also…?". Write a Decision line only for a
+non-trivial trade-off (architecture, edge-case behavior, library or approach), one line each with `->`,
+not for routine edits.
+
+Keep the details short. Do not repeat the outcome or list changed files and test results. Edit files
+with your app's native edit tool, not from the shell, so Your Turn sees them. Run the checks that cover
+your last code edit (documentation-only edits need none), alone or last in a chain joined with `&&`; if
+one fails, say so in the outcome, and if you cannot run it, make the next step `run: <command>`.
+```

your_turn-0.4.0/docs/configuration.md

@@ -0,0 +1,198 @@
+# Configuration
+
+Commands, flags, the handoff install, and the handoff format. What each app records is in
+[harnesses.md](./harnesses.md).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `your-turn serve` | Starts the inbox on `http://localhost:8787` and runs until Ctrl+C |
+| `your-turn install` | Sets up the handoff for each app it finds. Run in a terminal, it then starts the inbox, or says so when it is already running; from a script, or with input or output redirected, it exits |
+| `your-turn uninstall` | Removes exactly what `install` added |
+| `your-turn doctor` | Checks, without changing anything, whether the installed handoff matches this version |
+| `your-turn cursor-rule` | Prints the [Cursor User Rule](#cursor-user-rule) to paste into Cursor, without changing anything |
+
+## Flags and environment
+
+| Flag | Commands | Default | Environment |
+| --- | --- | --- | --- |
+| `--port` | `serve` | `8787` | `PORT` for `make up` |
+| `--codex-home` | all but `cursor-rule` | `~/.codex` | `CODEX_HOME` |
+| `--claude-home` | all but `cursor-rule` | `~/.claude` | `CLAUDE_CONFIG_DIR` |
+| `--cursor-home` | all but `cursor-rule` | `~/.cursor` | none |
+| `--cursor-user-dir` | `serve` | `~/Library/Application Support/Cursor/User` on macOS, `~/.config/Cursor/User` on Linux, `AppData/Roaming/Cursor/User` on Windows | none |
+| `--harness` | `install`, `uninstall`, `doctor` | every app whose folder exists | none |
+
+`--harness` takes `codex`, `claude`, `cursor`, or `all`. The server always binds `127.0.0.1`.
+`YOUR_TURN_REPO` tells a development install where your clone is when it is not at
+`~/dev/your-turn`.
+
+### History window
+
+Set the history window in `config.toml` at the repository root, then run `make restart`:
+
+```toml
+history_days = 14
+```
+
+The inbox shows chats whose session file changed in that many days. Direct chat links still open
+older chats.
+
+### State file
+
+`~/.your-turn/state.json` keeps which results you have seen and which reminders you dismissed, so
+every browser and tab shows the same inbox. It is the only file Your Turn writes. Entries for chats
+that leave the inbox are dropped.
+
+Each browser also backs up this state in `localStorage`. It restores missing server marks after a
+restart or lost state file, and retries local changes after a failed save. Dismiss and restore actions
+carry timestamps; a newer restore wins over an older browser backup. Backups contain only chat keys,
+seen times, and reminder identifiers, and are pruned to the current inbox. With storage blocked,
+server sharing still works. To fully reset marks, clear both the server state file and browser site data.
+
+## What `install` sets up
+
+Everything goes into your own app folders, never into a project, so no repository gains a file or
+a `.gitignore` entry:
+
+| App | What `install` sets up | What `uninstall` removes |
+| --- | --- | --- |
+| Codex | The `your-turn` plugin from the `your-turn` marketplace, which holds the handoff skill. Without the Codex CLI, the skill in `~/.agents/skills/your-turn/SKILL.md` instead, worded for any app; Cursor reads that folder too, so it then keeps no copy of its own. Once the CLI is there, `install` adds the plugin and removes that copy | The plugin and its marketplace, and the shared skill |
+| Claude Code | `~/.claude/skills/your-turn/SKILL.md` and a marked `your-turn` block in `~/.claude/CLAUDE.md` | The skill file and the block; the rest of `CLAUDE.md` stays |
+| Cursor | `~/.cursor/skills/your-turn/SKILL.md` and the [rule](#cursor-user-rule) as a local plugin in `~/.cursor/plugins/local/your-turn` | The skill file and the plugin |
+
+The handoff is plain text in the agent's answer, so nothing runs in the background and no app asks
+for a permission. `install` rewrites its own skill files and block whenever their text differs from
+this version, whatever version they name; running it again then changes nothing. A `SKILL.md` or a
+`your-turn` plugin that Your Turn did not write, a symlinked one, and other files in those folders
+are left alone by both commands. Both
+also remove the `your-turn` MCP server that earlier versions registered. Restart the apps after
+installing.
+
+### Cursor User Rule
+
+A saved skill is used only when the agent picks it. To apply the handoff in every Cursor Agent chat,
+`install` saves the text below as an always-applied rule in a
+[local plugin](https://cursor.com/docs/plugins#test-plugins-locally),
+`~/.cursor/plugins/local/your-turn`. Cursor loads it after a restart or **Developer: Reload Window**,
+and **Customize → Rules** then lists it.
+
+On Enterprise plans, an admin can turn local plugins off, and they are off by default there. If the
+rule is not listed after a reload, open **Customize → Rules**, add a **User Rule**, and paste the
+text below (GitHub shows a copy button on the block):
+
+````markdown
+## Your Turn handoff
+
+End every response to the user, on every turn, with this block at the very top or the very bottom: one
+group of lines with no prose between them, each on one line with a blank line between them (chat apps
+join adjacent lines into one paragraph), as plain Markdown outside code blocks.
+
+- `**Outcome:**` one sentence: what is now true.
+- `**Next step:**` `none`, `answer: …`, `decide: …`, `review: …`, `approve: …` or `run: …`. When the task
+  is done, write exactly `**Next step:** none` and stop. A question the user must react to goes here.
+- `**Recap:**` from the second turn on: 1-2 sentences under 400 characters (goal, what is settled, what
+  is open).
+- `**Decision:** <question> -> <chosen> (over <alternatives>). <reason>` only for a non-trivial trade-off
+  (architecture, edge-case behavior, library or approach), one line each.
+
+Keep the labels and prefixes in English, even when you reply in another language, and start no other
+line with them. An optional suggestion goes in the body; never close with a polite offer such as
+"Let me know if…" or "Should I also…?".
+Keep the labels (`Outcome:`, `Next step:`, `Recap:`, `Decision:`) and `Next step` prefixes in English even when replying in another language. Optional suggestions are not next steps: write `none`.
+
+Example:
+
+```markdown
+**Outcome:** The login redirect bug is fixed and covered by a test.
+
+**Next step:** none
+
+**Recap:** Fixing login redirects; the fix and its test are in, nothing is open.
+```
+
+While working:
+
+- Edit files with `StrReplace`, `Write` or `ApplyPatch`, not from the shell, so Your Turn sees them.
+- After your last code edit, run the check that covers it, alone or last in a chain joined with `&&`;
+  if you cannot, make the next step `run: <command>`.
+- Ask the user to choose with `AskQuestion`. The `your-turn` skill has the details.
+````
+
+To print exactly this text instead, without changing anything (on macOS, `| pbcopy` puts it on the
+clipboard):
+
+```sh
+uvx your-turn cursor-rule
+```
+
+Plain `your-turn cursor-rule` works when `your-turn` is on your PATH. Cursor keeps User Rules in its own settings, so `install` cannot
+add one there. Whether Cursor loaded the plugin is not visible outside Cursor, so `doctor` reports
+**rule loaded: unverified** even when the plugin is current. A `.cursor/rules` folder belongs to one
+project and does not apply elsewhere.
+
+### Checking the install
+
+`your-turn doctor` compares each file with the text this version would write and reports **current**,
+**missing**, **content mismatch**, or **unreadable**; run `install` to fix the last three. For Claude
+Code it checks the skill and only the Your Turn block of `CLAUDE.md`, and shows nothing else from that
+file. For Cursor it checks the skill and both files of the rule plugin. Codex keeps the plugin in
+its own cache, so the plugin is **unverified**. Neither `doctor` nor
+the saved files prove that an app has loaded the handoff into a chat.
+
+| You want | Do this |
+| --- | --- |
+| Only the inbox, no handoff | Run only `serve`. Recaps fall back to the first paragraph of each answer and a guessed next step. |
+| The handoff format without installing anything | Paste [agents-snippet.md](./agents-snippet.md) into the app's global instructions, such as `~/.codex/AGENTS.md`. |
+| To develop Your Turn | Clone the repo and run `make install`. It runs `your-turn install` for each app it finds, with the Codex plugin from your checkout when the Codex CLI is installed, and starts the server in the background. |
+
+## Handoff contract
+
+Recaps come from the agent's final answer:
+
+| If the final answer has | Your Turn shows |
+| --- | --- |
+| `**Outcome:**`, `**Next step:**`, and `**Recap:**` lines | Those lines as written |
+| `**Decision:** <question> -> <chosen> (over <alternatives>). <reason>` lines | One decision each, with its options; `→` works too |
+| `**Outcome:**` without `**Next step:**` | The outcome, marked **No next step** |
+| No handoff lines | The first paragraph as the outcome, and a best-guess next step (Run, Review, or Answer) marked **Inferred**; with none found, **No handoff** |
+
+- `**Outcome:**` is one sentence: what is now true.
+- `**Next step:**` is `none`, `answer: …`, `review: …`, `approve: …`, or `run: …`.
+- `**Recap:**` is added from the second turn on.
+- Questions go through the app's question tool (`AskUserQuestion` in Claude Code, `AskQuestion` in
+  Cursor) with options, so they show under Needs you until answered.
+
+Decisions that older chats logged through the `log_decision` tool still show. The full skill is
+[plugin/skills/your-turn-handoff/SKILL.md](../plugin/skills/your-turn-handoff/SKILL.md).
+
+## Development
+
+| Command | Use it when |
+| --- | --- |
+| `make install` | First setup, or to update the handoff |
+| `make doctor` | Check, without changing anything, whether the installed handoff is current |
+| `make up` | Start the server in the background (`PORT=...` to change from 8787) |
+| `make status` | Check whether it is running |
+| `make logs` | Follow the server log |
+| `make restart` | Pick up code or config changes |
+| `make down` | Stop the server |
+| `make test` | Run the test suite |
+| `make screenshots` | Regenerate the README images from demo chats (needs Google Chrome and ffmpeg) |
+
+| Route | Returns |
+| --- | --- |
+| `GET /api/inbox` | Recent chats with status, outcome, next step, and check state |
+| `GET /api/threads/<key>` | Snapshot of one chat. `<key>` is `codex:<id>`, `claude:<id>`, or `cursor:<id>`; a bare id means Codex |
+| `GET /api/stream?thread=<key>` | Server-sent events when that chat changes; without `thread`, inbox events |
+
+```text
+src/yourturn/                 FastAPI server, session engine, and installer
+src/yourturn/harness/         One adapter per app: Codex, Claude Code, Cursor
+src/yourturn/static/          Dashboard HTML, CSS tokens, and JavaScript
+plugin/                       Codex plugin: manifest and the your-turn-handoff skill
+tests/                        Parser and API tests
+scripts/                      Demo-data screenshot and GIF generator for the README
+docs/images/                  README images
+```

your_turn-0.4.0/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "your-turn",
+  "version": "0.4.0",
+  "description": "Read-only inbox view of what the current Codex chat is doing and the decisions it makes.",
+  "author": {
+    "name": "Martin Gomola"
+  },
+  "license": "MIT",
+  "keywords": [
+    "inbox",
+    "agents",
+    "dashboard",
+    "decisions",
+    "observability"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Your Turn",
+    "shortDescription": "See what the agent is doing and why",
+    "longDescription": "Ends every turn with short Outcome and Next step lines, and a Decision line for each real choice, that the local dashboard at http://localhost:8787 turns into an inbox of your chats.",
+    "developerName": "Martin Gomola",
+    "category": "Productivity",
+    "capabilities": [
+      "Instructions"
+    ],
+    "composerIcon": "./assets/your-turn-light.png",
+    "composerIconDark": "./assets/your-turn-dark.png",
+    "defaultPrompt": [
+      "End your answers in the Your Turn handoff format."
+    ],
+    "logo": "./assets/your-turn-light.png",
+    "logoDark": "./assets/your-turn-dark.png",
+    "brandColor": "#4F9A8B"
+  }
+}