cigar-break 0.1.0__tar.gz

cigar_break-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+tests/fixtures/private/
+.cigar/
+# Written by Claude Code when it loads the mod (editor typings)
+tsconfig.json

cigar_break-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 · 2026-10-26
+
+First release.
+
+- Detection: failures, repeats, re-reads, undos and failed checks over the last 20 tool calls, plus context pressure, combined into a fatigue score with evidence-backed nudges (at most three per session, 25 calls apart, never below 40k tokens).
+- Handoffs: `take_break`, `resume` and `status` MCP tools; handoffs saved in `<project>/.cigar/handoffs/` and restored after `/clear` or `/compact`.
+- Modes: `suggest` (default), `observe`, and opt-in `auto` (terminal), which clears the context only after a handoff is saved for the session.
+- Learning: per-model knees from your own sessions, per context window (`200k` or `1m`, detected or set with `context_window`); learned knees replace the defaults at medium confidence or above.
+- Report: `cigar report` and `/cigar:report`, as text and a self-contained HTML page.
+- Sharing: opt-in `cigar share` and `/cigar:share`, an allowlisted aggregate payload opened as a prefilled GitHub issue; `scripts/ingest_curves.py` and `data/curves/`.
+- Any agent: `record_event` MCP tool, `cigar.track` helper, `cigar-mcp` on PyPI as `cigar-break`.
+- Fail-open hooks; standard library only; Python 3.11+ found even when `python3` is older.

cigar_break-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Youssef
+
+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.

cigar_break-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: cigar-break
+Version: 0.1.0
+Summary: Detects when a coding agent's session is degrading, gets a structured handoff, and restores it after a context reset.
+Author: Mohamed Youssef
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Cigar 🚬
+
+**Your coding agent gets worse as its context fills up. Cigar notices, has it write a handoff, and restarts it fresh without losing the thread.**
+
+Two hours into a long Claude Code session the agent starts failing tool calls, re-reading files it already read and undoing its own edits. By the time you notice, you've lost twenty minutes; if you reset too early, you lose your place. Cigar watches for those signs, which the session already produces, and offers the agent a *cigar break*: write a structured handoff, reset the context, pick up from the handoff in a fresh one.
+
+In auto mode (opt-in, terminal), the whole break happens by itself. An illustrative session; the 🚬 lines are Cigar's own messages:
+
+```
+🚬 Cigar: this session shows fatigue (152k tokens, 9 signals in the last 20 calls).
+   Claude has been offered a break; in auto mode the context resets once it saves a handoff.
+⏺ cigar - take_break (MCP) … Handoff saved to .cigar/handoffs/2026-10-24T0130-ab12.md
+🚬 Handoff ready. Cigar auto mode clears the context now; if it doesn't, type /clear.
+🚬 Cigar auto mode cleared the context and restored the handoff from .cigar/handoffs/2026-10-24T0130-ab12.md.
+> what's next?
+⏺ We're adding retry logic to the upload client. Next: make test_retry_backoff pass …
+```
+
+## Install
+
+In Claude Code:
+
+```
+/plugin marketplace add MYoussef885/cigar-break
+/plugin install cigar@cigar-break
+```
+
+Or from a shell: `claude plugin marketplace add MYoussef885/cigar-break && claude plugin install cigar@cigar-break`.
+
+**Requirements:** Python 3.11 or newer somewhere on the machine, and nothing else (no packages to install). Claude Code runs Cigar with whatever `python3` is on your PATH; if that is older (macOS ships 3.9), Cigar's launcher finds `python3.11` to `python3.14` on your PATH, in `~/.local/bin`, `/opt/homebrew/bin`, `/usr/local/bin` or uv's Python folder, and uses it. If there is none, Cigar shows one warning at session start, at most once a day, and otherwise stays out of the way. `uv python install 3.12` is the quickest fix.
+
+## How it works
+
+1. **Detect.** After every tool call, Cigar reads the context size from the tail of the session transcript and looks at the last 20 calls for five signals: failed calls, repeated identical calls, files re-read with no edit in between, edits that undo an earlier edit, and failed tests, builds or lint runs. It combines them with *context pressure* (context size ÷ the model's knee) into a fatigue score. It never nudges below 40k tokens, and never on fewer than 10 calls of evidence (unless the session is far past the knee).
+2. **Nudge (`suggest`, the default).** When the score crosses the threshold, the agent gets a short factual note with the evidence, and you see one line (and a terminal notification). At most three nudges per session, 25 calls apart.
+3. **Hand off.** The agent calls Cigar's `take_break` tool and writes a handoff: goal, status, what's done, decisions, files, next steps, open questions and gotchas. It's saved in your project's `.cigar/handoffs/`, which git ignores by itself (Cigar never touches your `.gitignore`).
+4. **Reset and restore.** Type `/clear` (or `/compact`). Cigar injects the handoff into the fresh session, so the agent's first reply already knows the goal and the next step.
+5. **Learn.** Every model starts with a default *knee*, the context size where sessions usually start to slip (for example 100k for Sonnet and 120k for Opus on a 200k window). As you work, Cigar learns where **your** sessions slip, per model, and uses that once it is confident. `/cigar:report` shows the curve.
+
+Modes: `suggest` (default) nudges and waits for you; `observe` only records; `auto` resets by itself (below). Switch with `/cigar:mode`.
+
+### Auto mode (opt-in, terminal)
+
+`/cigar:mode auto` turns it on; it's off by default. In auto mode, once the agent has **saved a handoff for the current session**, Cigar clears the context itself at the end of that turn, restores the handoff, and tells you in one line which handoff it restored. If the agent ignores the nudge, auto mode behaves exactly like `suggest`: it nudges, waits, and never clears. It also never clears after an interrupted turn or for a subagent.
+
+Auto mode uses a Claude Code plugin mod and is **verified in the terminal CLI only**. It is not claimed for the VS Code panel; use `suggest` there.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/cigar:status` | Fatigue score, context size, knee, recent signals and mode |
+| `/cigar:break` | Have the agent write a handoff now; then type `/clear` |
+| `/cigar:mode [suggest\|observe\|auto]` | Show or change the mode |
+| `/cigar:report` | Your signal rate by context size, per model, with the learned knee; also writes an HTML page |
+| `/cigar:share` | Show your anonymous curve; `/cigar:share confirm` opens it as a prefilled GitHub issue |
+
+The same is available outside Claude Code as `cigar status`, `cigar report [--html|--open]`, `cigar share [--dry-run]` and `cigar mode` (`python3 <plugin>/bin/cigar …`, or `cigar` after `pip install cigar-break`).
+
+## Privacy
+
+- **Everything stays on your machine:** `~/.cigar/` (store, config, logs, reports) and `<project>/.cigar/` (handoffs).
+- Cigar stores **hashes** of tool arguments, never the arguments. It keeps file paths only to spot re-reads and undos, locally.
+- It never stores prompts, assistant text or file contents. Handoffs are the exception: the agent writes them on purpose, into your project folder.
+- **No telemetry, no network calls.** The only thing that ever leaves the machine is a curve you choose to share, below, and even then Cigar only opens a prefilled GitHub issue in your browser; nothing is sent until you press Submit there.
+
+## Sharing your curve (opt-in)
+
+Where agents get tired is an open question, and every developer's sessions are a data point. `cigar share` (or `/cigar:share`) shows you the **exact** payload first: one model ID, its context window label (`200k` or `1m`), counts and signal weight per 10k-token bucket, the knee and its confidence, the number of sessions, and the Cigar version. No paths, project names, code, prompts or user identifiers; a strict allowlist check runs before anything is shown. If you confirm, it opens a prefilled issue on this repo. Accepted curves are published in [`data/curves/`](data/curves/README.md) for anyone to use. `cigar share --dry-run` just prints the payload.
+
+Shared curves are published under [CC0-1.0](data/curves/LICENSE) (public domain), not the code's MIT license.
+
+## Other agents
+
+**Standalone MCP server.** `pip install cigar-break` installs `cigar-mcp`, a stdio MCP server with `take_break`, `resume`, `status` and `record_event`. Agents without Claude Code's hooks call `record_event` after each tool call to get detection, and `take_break`/`resume` for handoffs. Tested with the official MCP Python SDK client (`scripts/check_mcp_client.py`); other clients have not been tested yet.
+
+**Custom Python agent loops** can skip MCP and use `cigar.track` directly:
+
+```python
+from cigar.track import Tracker
+
+tracker = Tracker(session_id="run-42", model="gpt-5")  # one per agent session
+
+
+def run_tool(name, args):
+    try:
+        result = TOOLS[name](**args)
+        ok, code = True, 0
+    except ToolFailed as exc:
+        result, ok, code = str(exc), False, exc.exit_code
+    check = tracker.record(
+        name,
+        ok,
+        context_tokens=current_context_tokens(),
+        kind={"read_file": "read", "edit_file": "edit", "shell": "shell"}.get(name, "other"),
+        path=args.get("path"),
+        args=args,  # hashed, never stored
+        exit_code=code,
+    )
+    if check.break_suggested:
+        result += "\n\n" + check.message  # factual note: context size, knee, evidence
+    return result
+```
+
+## Verified setups
+
+Only these have been tested:
+
+| Setup | What was verified |
+|---|---|
+| Claude Code CLI 2.1.288, terminal, macOS 26, Python 3.11 via uv (system `python3` 3.9) | Detection, nudges, handoff, restore after `/clear` and `/compact`, `suggest` and `auto` modes (live sessions, Session 1) |
+| Claude Code 2.1.309, terminal, macOS | Auto-mode `/clear` from the plugin mod; plugin install from a marketplace in two commands |
+| `cigar-mcp` from a wheel, official MCP Python SDK 2.3.0 client, macOS and Ubuntu (CI) | All four MCP tools, outside the plugin |
+| Unit, replay, fail-open and MCP tests on Ubuntu, macOS and Windows (CI) | Tests only, no live Claude Code session on Linux or Windows |
+
+Not verified yet: the VS Code extension's chat panel, a live session on Linux or Windows, and other MCP clients.
+
+## Prior art
+
+Similar tools exist. foldcrumbs, novyx-hygiene and claude-mem save memory around compaction; Cairn and a "context rot detection" MCP server report health zones from token usage. Most of them use a fixed threshold. Cigar's difference is a per-model knee learned from *behavioral* signals in your own sessions, an evidence-backed nudge that leads into a structured handoff and restore, and an open dataset of shared curves. No code was taken from those projects.
+
+## Configuration
+
+`~/.cigar/config.toml`, overridden by environment variables:
+
+| Key | Env | Default |
+|---|---|---|
+| `mode` | `CIGAR_MODE` | `suggest` |
+| `min_tokens` | `CIGAR_MIN_TOKENS` | `40000` |
+| `knee_tokens` (one knee for every model) | `CIGAR_KNEE_TOKENS` | learned or default per model |
+| `context_window` (`200k` or `1m`) | `CIGAR_CONTEXT_WINDOW` | detected per session (past 200k means `1m`) |
+| `cooldown_events`, `max_nudges` | | `25`, `3` |
+| | `CIGAR_HOME` | `~/.cigar` |
+
+To see Cigar trigger quickly in a scratch project: `CIGAR_KNEE_TOKENS=20000 CIGAR_MIN_TOKENS=5000 claude`.
+
+## Development
+
+```
+uv sync --group dev
+uv run ruff check . && uv run ruff format --check .
+uv run pytest
+uv run pytest tests/test_perf.py -s                    # prints the hook p95
+claude --plugin-dir .                                  # load the plugin from this checkout
+uv run python scripts/simulate.py --home /tmp/cigar-sim   # fake data with a known knee
+CIGAR_HOME=/tmp/cigar-sim uv run cigar report --open
+```
+
+Design notes live in [`SRS.md`](SRS.md), [`architecture.md`](architecture.md) and [`decisions.md`](decisions.md). Changes: [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+Code: MIT. Shared curves in `data/curves/`: CC0-1.0.

cigar_break-0.1.0/README.md

@@ -0,0 +1,153 @@
+# Cigar 🚬
+
+**Your coding agent gets worse as its context fills up. Cigar notices, has it write a handoff, and restarts it fresh without losing the thread.**
+
+Two hours into a long Claude Code session the agent starts failing tool calls, re-reading files it already read and undoing its own edits. By the time you notice, you've lost twenty minutes; if you reset too early, you lose your place. Cigar watches for those signs, which the session already produces, and offers the agent a *cigar break*: write a structured handoff, reset the context, pick up from the handoff in a fresh one.
+
+In auto mode (opt-in, terminal), the whole break happens by itself. An illustrative session; the 🚬 lines are Cigar's own messages:
+
+```
+🚬 Cigar: this session shows fatigue (152k tokens, 9 signals in the last 20 calls).
+   Claude has been offered a break; in auto mode the context resets once it saves a handoff.
+⏺ cigar - take_break (MCP) … Handoff saved to .cigar/handoffs/2026-10-24T0130-ab12.md
+🚬 Handoff ready. Cigar auto mode clears the context now; if it doesn't, type /clear.
+🚬 Cigar auto mode cleared the context and restored the handoff from .cigar/handoffs/2026-10-24T0130-ab12.md.
+> what's next?
+⏺ We're adding retry logic to the upload client. Next: make test_retry_backoff pass …
+```
+
+## Install
+
+In Claude Code:
+
+```
+/plugin marketplace add MYoussef885/cigar-break
+/plugin install cigar@cigar-break
+```
+
+Or from a shell: `claude plugin marketplace add MYoussef885/cigar-break && claude plugin install cigar@cigar-break`.
+
+**Requirements:** Python 3.11 or newer somewhere on the machine, and nothing else (no packages to install). Claude Code runs Cigar with whatever `python3` is on your PATH; if that is older (macOS ships 3.9), Cigar's launcher finds `python3.11` to `python3.14` on your PATH, in `~/.local/bin`, `/opt/homebrew/bin`, `/usr/local/bin` or uv's Python folder, and uses it. If there is none, Cigar shows one warning at session start, at most once a day, and otherwise stays out of the way. `uv python install 3.12` is the quickest fix.
+
+## How it works
+
+1. **Detect.** After every tool call, Cigar reads the context size from the tail of the session transcript and looks at the last 20 calls for five signals: failed calls, repeated identical calls, files re-read with no edit in between, edits that undo an earlier edit, and failed tests, builds or lint runs. It combines them with *context pressure* (context size ÷ the model's knee) into a fatigue score. It never nudges below 40k tokens, and never on fewer than 10 calls of evidence (unless the session is far past the knee).
+2. **Nudge (`suggest`, the default).** When the score crosses the threshold, the agent gets a short factual note with the evidence, and you see one line (and a terminal notification). At most three nudges per session, 25 calls apart.
+3. **Hand off.** The agent calls Cigar's `take_break` tool and writes a handoff: goal, status, what's done, decisions, files, next steps, open questions and gotchas. It's saved in your project's `.cigar/handoffs/`, which git ignores by itself (Cigar never touches your `.gitignore`).
+4. **Reset and restore.** Type `/clear` (or `/compact`). Cigar injects the handoff into the fresh session, so the agent's first reply already knows the goal and the next step.
+5. **Learn.** Every model starts with a default *knee*, the context size where sessions usually start to slip (for example 100k for Sonnet and 120k for Opus on a 200k window). As you work, Cigar learns where **your** sessions slip, per model, and uses that once it is confident. `/cigar:report` shows the curve.
+
+Modes: `suggest` (default) nudges and waits for you; `observe` only records; `auto` resets by itself (below). Switch with `/cigar:mode`.
+
+### Auto mode (opt-in, terminal)
+
+`/cigar:mode auto` turns it on; it's off by default. In auto mode, once the agent has **saved a handoff for the current session**, Cigar clears the context itself at the end of that turn, restores the handoff, and tells you in one line which handoff it restored. If the agent ignores the nudge, auto mode behaves exactly like `suggest`: it nudges, waits, and never clears. It also never clears after an interrupted turn or for a subagent.
+
+Auto mode uses a Claude Code plugin mod and is **verified in the terminal CLI only**. It is not claimed for the VS Code panel; use `suggest` there.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/cigar:status` | Fatigue score, context size, knee, recent signals and mode |
+| `/cigar:break` | Have the agent write a handoff now; then type `/clear` |
+| `/cigar:mode [suggest\|observe\|auto]` | Show or change the mode |
+| `/cigar:report` | Your signal rate by context size, per model, with the learned knee; also writes an HTML page |
+| `/cigar:share` | Show your anonymous curve; `/cigar:share confirm` opens it as a prefilled GitHub issue |
+
+The same is available outside Claude Code as `cigar status`, `cigar report [--html|--open]`, `cigar share [--dry-run]` and `cigar mode` (`python3 <plugin>/bin/cigar …`, or `cigar` after `pip install cigar-break`).
+
+## Privacy
+
+- **Everything stays on your machine:** `~/.cigar/` (store, config, logs, reports) and `<project>/.cigar/` (handoffs).
+- Cigar stores **hashes** of tool arguments, never the arguments. It keeps file paths only to spot re-reads and undos, locally.
+- It never stores prompts, assistant text or file contents. Handoffs are the exception: the agent writes them on purpose, into your project folder.
+- **No telemetry, no network calls.** The only thing that ever leaves the machine is a curve you choose to share, below, and even then Cigar only opens a prefilled GitHub issue in your browser; nothing is sent until you press Submit there.
+
+## Sharing your curve (opt-in)
+
+Where agents get tired is an open question, and every developer's sessions are a data point. `cigar share` (or `/cigar:share`) shows you the **exact** payload first: one model ID, its context window label (`200k` or `1m`), counts and signal weight per 10k-token bucket, the knee and its confidence, the number of sessions, and the Cigar version. No paths, project names, code, prompts or user identifiers; a strict allowlist check runs before anything is shown. If you confirm, it opens a prefilled issue on this repo. Accepted curves are published in [`data/curves/`](data/curves/README.md) for anyone to use. `cigar share --dry-run` just prints the payload.
+
+Shared curves are published under [CC0-1.0](data/curves/LICENSE) (public domain), not the code's MIT license.
+
+## Other agents
+
+**Standalone MCP server.** `pip install cigar-break` installs `cigar-mcp`, a stdio MCP server with `take_break`, `resume`, `status` and `record_event`. Agents without Claude Code's hooks call `record_event` after each tool call to get detection, and `take_break`/`resume` for handoffs. Tested with the official MCP Python SDK client (`scripts/check_mcp_client.py`); other clients have not been tested yet.
+
+**Custom Python agent loops** can skip MCP and use `cigar.track` directly:
+
+```python
+from cigar.track import Tracker
+
+tracker = Tracker(session_id="run-42", model="gpt-5")  # one per agent session
+
+
+def run_tool(name, args):
+    try:
+        result = TOOLS[name](**args)
+        ok, code = True, 0
+    except ToolFailed as exc:
+        result, ok, code = str(exc), False, exc.exit_code
+    check = tracker.record(
+        name,
+        ok,
+        context_tokens=current_context_tokens(),
+        kind={"read_file": "read", "edit_file": "edit", "shell": "shell"}.get(name, "other"),
+        path=args.get("path"),
+        args=args,  # hashed, never stored
+        exit_code=code,
+    )
+    if check.break_suggested:
+        result += "\n\n" + check.message  # factual note: context size, knee, evidence
+    return result
+```
+
+## Verified setups
+
+Only these have been tested:
+
+| Setup | What was verified |
+|---|---|
+| Claude Code CLI 2.1.288, terminal, macOS 26, Python 3.11 via uv (system `python3` 3.9) | Detection, nudges, handoff, restore after `/clear` and `/compact`, `suggest` and `auto` modes (live sessions, Session 1) |
+| Claude Code 2.1.309, terminal, macOS | Auto-mode `/clear` from the plugin mod; plugin install from a marketplace in two commands |
+| `cigar-mcp` from a wheel, official MCP Python SDK 2.3.0 client, macOS and Ubuntu (CI) | All four MCP tools, outside the plugin |
+| Unit, replay, fail-open and MCP tests on Ubuntu, macOS and Windows (CI) | Tests only, no live Claude Code session on Linux or Windows |
+
+Not verified yet: the VS Code extension's chat panel, a live session on Linux or Windows, and other MCP clients.
+
+## Prior art
+
+Similar tools exist. foldcrumbs, novyx-hygiene and claude-mem save memory around compaction; Cairn and a "context rot detection" MCP server report health zones from token usage. Most of them use a fixed threshold. Cigar's difference is a per-model knee learned from *behavioral* signals in your own sessions, an evidence-backed nudge that leads into a structured handoff and restore, and an open dataset of shared curves. No code was taken from those projects.
+
+## Configuration
+
+`~/.cigar/config.toml`, overridden by environment variables:
+
+| Key | Env | Default |
+|---|---|---|
+| `mode` | `CIGAR_MODE` | `suggest` |
+| `min_tokens` | `CIGAR_MIN_TOKENS` | `40000` |
+| `knee_tokens` (one knee for every model) | `CIGAR_KNEE_TOKENS` | learned or default per model |
+| `context_window` (`200k` or `1m`) | `CIGAR_CONTEXT_WINDOW` | detected per session (past 200k means `1m`) |
+| `cooldown_events`, `max_nudges` | | `25`, `3` |
+| | `CIGAR_HOME` | `~/.cigar` |
+
+To see Cigar trigger quickly in a scratch project: `CIGAR_KNEE_TOKENS=20000 CIGAR_MIN_TOKENS=5000 claude`.
+
+## Development
+
+```
+uv sync --group dev
+uv run ruff check . && uv run ruff format --check .
+uv run pytest
+uv run pytest tests/test_perf.py -s                    # prints the hook p95
+claude --plugin-dir .                                  # load the plugin from this checkout
+uv run python scripts/simulate.py --home /tmp/cigar-sim   # fake data with a known knee
+CIGAR_HOME=/tmp/cigar-sim uv run cigar report --open
+```
+
+Design notes live in [`SRS.md`](SRS.md), [`architecture.md`](architecture.md) and [`decisions.md`](decisions.md). Changes: [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+Code: MIT. Shared curves in `data/curves/`: CC0-1.0.

cigar_break-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "cigar-break"
+version = "0.1.0"
+description = "Detects when a coding agent's session is degrading, gets a structured handoff, and restores it after a context reset."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Mohamed Youssef" }]
+dependencies = []
+
+[project.scripts]
+cigar = "cigar.cli:main"
+cigar-mcp = "cigar.mcp_server:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6", "mcp>=1.9"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cigar"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/cigar", "/README.md", "/LICENSE", "/CHANGELOG.md", "/pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["tests/fixtures"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"bin/*" = ["UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["perf: performance measurement (prints the hook p95)"]

cigar_break-0.1.0/src/cigar/__init__.py

@@ -0,0 +1,3 @@
+"""Cigar: notices when a coding agent's session is slipping, and hands off across a reset."""
+
+__version__ = "0.1.0"

cigar_break-0.1.0/src/cigar/auto.py

@@ -0,0 +1,70 @@
+"""Auto mode markers (D-007, D-021, D-026).
+
+In `auto` mode, once a handoff is saved for the session, the hook writes
+<CIGAR_HOME>/auto/<session id>.json with state "ready" and the handoff's path.
+The mod in mods/auto.ts reads it at the end of the turn, marks it "fired" and
+runs /clear. With no marker, or one without a handoff path, it never clears.
+Only these markers cross between the two.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+MAX_AGE_SECONDS = 24 * 3600
+FIRED_MAX_AGE_SECONDS = 600  # a clear that fired longer ago than this is not "just now"
+
+
+def marker_path(home: Path, session_id: str) -> Path:
+    safe = "".join(c for c in session_id if c.isalnum() or c in "-_")
+    return home / "auto" / f"{safe}.json"
+
+
+def mark_ready(home: Path, session_id: str, handoff: str) -> Path:
+    path = marker_path(home, session_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    marker = {"state": "ready", "session": session_id, "handoff": handoff, "ts": time.time()}
+    tmp.write_text(json.dumps(marker), encoding="utf-8")
+    tmp.replace(path)
+    return path
+
+
+def take_fired(home: Path, max_age: float = FIRED_MAX_AGE_SECONDS) -> str | None:
+    """The handoff path of a clear the mod just fired, removing its marker."""
+    folder = home / "auto"
+    if not folder.is_dir():
+        return None
+    found: tuple[float, str] | None = None
+    cutoff = time.time() - max_age
+    for path in folder.glob("*.json"):
+        try:
+            marker = json.loads(path.read_text(encoding="utf-8"))
+            if marker.get("state") != "fired" or path.stat().st_mtime < cutoff:
+                continue
+            handoff = marker.get("handoff")
+            if isinstance(handoff, str) and handoff:
+                stamp = path.stat().st_mtime
+                if found is None or stamp > found[0]:
+                    found = (stamp, handoff)
+            path.unlink()
+        except (OSError, ValueError, AttributeError):
+            continue
+    return found[1] if found else None
+
+
+def prune(home: Path, max_age: float = MAX_AGE_SECONDS) -> None:
+    """Remove fired markers and any older than max_age."""
+    folder = home / "auto"
+    if not folder.is_dir():
+        return
+    cutoff = time.time() - max_age
+    for path in folder.glob("*.json"):
+        try:
+            fired = json.loads(path.read_text(encoding="utf-8")).get("state") == "fired"
+            if fired or path.stat().st_mtime < cutoff:
+                path.unlink()
+        except (OSError, ValueError, AttributeError):
+            path.unlink(missing_ok=True)

cigar_break-0.1.0/src/cigar/cli.py

@@ -0,0 +1,128 @@
+"""`cigar` command line: status, report, share and mode (FR-C6)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from cigar import __version__, config, status
+from cigar.store import Store, project_hash
+
+MODE_HELP = {
+    "suggest": "Cigar nudges the agent and you when the session shows fatigue (default).",
+    "observe": "Cigar records signals only, with no nudges.",
+    "auto": (
+        "After a handoff is saved, Cigar clears the context itself at the end of the turn and "
+        "restores the handoff. Needs plugin mods (Claude Code 2.1.287 or newer); tested in the "
+        "terminal CLI only."
+    ),
+}
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    cfg = config.load()
+    project_dir = args.project or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    project = project_hash(str(Path(project_dir)))
+    with Store.open(cfg.db_path) as store:
+        info = status.collect(store, cfg, args.session, project)
+    print(json.dumps(info, indent=2) if args.json else status.render(info))
+    return 0
+
+
+def cmd_mode(args: argparse.Namespace) -> int:
+    cfg = config.load()
+    mode = (args.mode or "").strip().lower()
+    if not mode:
+        print(f"Mode: {cfg.mode}. {MODE_HELP[cfg.mode]}")
+        return 0
+    if mode not in config.MODES:
+        print(f"Unknown mode {mode!r}. Choose one of: {', '.join(config.MODES)}.")
+        return 2
+    args.mode = mode
+    path = config.write_value(cfg.home, "mode", args.mode)
+    note = ""
+    if os.environ.get("CIGAR_MODE") and os.environ["CIGAR_MODE"] != args.mode:
+        note = f" Note: CIGAR_MODE={os.environ['CIGAR_MODE']} is set and overrides it."
+    print(f"Mode set to {args.mode} in {path}. {MODE_HELP[args.mode]}{note}")
+    return 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    from cigar import report, track
+
+    cfg = config.load()
+    with Store.open(cfg.db_path) as store:
+        fits = track.refresh_knees(store, force=True) or []
+        compactions = store.compaction_tokens()
+    print(report.render_text(fits, compactions))
+    if args.html or args.open:
+        path = report.write_html(cfg.home, report.render_html(fits, compactions))
+        print(f"\nHTML report: {path}")
+        if args.open:
+            import webbrowser
+
+            webbrowser.open(path.as_uri())
+    return 0
+
+
+def cmd_share(args: argparse.Namespace) -> int:
+    from cigar import share, track
+
+    cfg = config.load()
+    with Store.open(cfg.db_path) as store:
+        fits = track.refresh_knees(store, force=True) or []
+        harnesses = track.harnesses(store)
+    return share.run(
+        cfg,
+        fits,
+        harnesses,
+        model=args.model,
+        window=args.window,
+        dry_run=args.dry_run,
+        yes=args.yes,
+        skill=args.skill,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cigar", description="Cigar: take a break before the context rots."
+    )
+    parser.add_argument("--version", action="version", version=f"cigar {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_status = sub.add_parser("status", help="score, context size, knee, recent signals and mode")
+    p_status.add_argument("--session", help="session ID (default: the latest in this project)")
+    p_status.add_argument("--project", help="project directory (default: current directory)")
+    p_status.add_argument("--json", action="store_true", help="print JSON")
+    p_status.set_defaults(func=cmd_status)
+
+    p_report = sub.add_parser("report", help="your signal rate by context size, per model")
+    p_report.add_argument("--html", action="store_true", help="also write the HTML report")
+    p_report.add_argument("--open", action="store_true", help="write the HTML and open it")
+    p_report.set_defaults(func=cmd_report)
+
+    p_share = sub.add_parser("share", help="share your anonymous curve (opt-in, shows it first)")
+    p_share.add_argument("--dry-run", action="store_true", help="print the payload only")
+    p_share.add_argument("--yes", action="store_true", help="skip the confirmation question")
+    p_share.add_argument("--model", help="which model's curve (default: the most data)")
+    p_share.add_argument("--window", choices=["200k", "1m"], help="which context window")
+    p_share.add_argument("--skill", help=argparse.SUPPRESS)  # /cigar:share passes its argument
+    p_share.set_defaults(func=cmd_share)
+
+    p_mode = sub.add_parser("mode", help="show or set the mode")
+    p_mode.add_argument("mode", nargs="?", help="suggest, observe or auto")
+    p_mode.set_defaults(func=cmd_mode)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())