context-handoff 0.1.1__tar.gz

context_handoff-0.1.1/LICENSE

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

context_handoff-0.1.1/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: context-handoff
+Version: 0.1.1
+Summary: Keep Claude Code sessions cheap: meter cost, write a handoff note, resume after /clear
+Author: Yauhen Bichel
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YauhenBichel/context-handoff
+Project-URL: Changelog, https://github.com/YauhenBichel/context-handoff/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/YauhenBichel/context-handoff/issues
+Keywords: claude,claude-code,llm,cost,context,handoff
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# context-handoff
+
+[![ci](https://github.com/YauhenBichel/context-handoff/actions/workflows/ci.yml/badge.svg)](https://github.com/YauhenBichel/context-handoff/actions/workflows/ci.yml)
+[![release](https://img.shields.io/github/v/release/YauhenBichel/context-handoff)](https://github.com/YauhenBichel/context-handoff/releases)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A Claude Code plugin that keeps long sessions from getting expensive: it shows
+what each turn costs, writes a handoff note when the session grows, and resumes
+from it after `/clear`.
+
+```
+/plugin marketplace add YauhenBichel/context-handoff
+/plugin install context-handoff@context-handoff
+```
+
+Python 3.10+ as `python3`, nothing else. Details in [Install](#install).
+
+Every Claude Code turn re-sends the whole conversation. While the prompt cache
+is warm that re-read is cheap; after a pause the whole context is written to
+the cache again at up to 2× the input price. A 400K-token session on Claude
+Opus 5.5 pays about $3.20 for one such cold turn, before Claude writes a word.
+Long sessions also get slower and lose focus.
+
+context-handoff watches what each turn costs. When a session gets too big or
+too expensive, Claude writes a short handoff note at the end of the current
+task. You run `/clear`, type `go`, and a fresh, small session continues from
+the note.
+
+What you see above a prompt once a session is past the warn limit:
+
+```
+[context-handoff] 182K context, last turn $0.61, session $14.20, a cold turn would cost $1.46
+(claude-opus-5-5 prices). Claude will write a handoff note after this task; then /clear and type go.
+```
+
+## How it works
+
+1. **Meter** (`UserPromptSubmit` hook). Before each prompt it reads the
+   session transcript and computes, at API list prices:
+   - the context the next turn will re-send,
+   - what the last turn cost,
+   - what the whole session cost,
+   - what one cold turn would cost now.
+2. **Auto handoff**. Over a warn limit, it asks Claude (once per session) to
+   write a handoff note when the current task is done.
+3. **Block**. Over a block limit, it holds the prompt until you type `handoff`
+   or add `#override`.
+4. **Resume** (`SessionStart` hook, after `/clear`). It loads the project's
+   newest unused note into the new session, so you type `go` instead of
+   pasting a prompt. Each note is loaded once.
+
+## Install
+
+In Claude Code:
+
+```
+/plugin marketplace add YauhenBichel/context-handoff
+/plugin install context-handoff@context-handoff
+```
+
+Or from a terminal:
+
+```
+claude plugin marketplace add YauhenBichel/context-handoff
+claude plugin install context-handoff@context-handoff
+```
+
+Restart Claude Code (or start a new session) to load the hooks. The meter
+line appears from the second prompt of a session.
+
+Requires Python 3.10 or newer on `PATH` as `python3`. No other dependencies.
+
+### Without Claude Code plugins
+
+The same code is on PyPI. It gives the `context-handoff` command for reports
+and checks, for example in a shell or on a machine where you don't use the
+plugin:
+
+```
+pipx install context-handoff        # or: uv tool install context-handoff
+context-handoff report 14
+```
+
+The hooks still come from the plugin above; the package does not install them.
+
+Update or remove:
+
+```
+claude plugin marketplace update context-handoff
+claude plugin update context-handoff@context-handoff
+claude plugin uninstall context-handoff@context-handoff
+```
+
+## Use
+
+- **Normal flow**: keep working. When the meter asks, Claude writes the note
+  after the current task and tells you. Run `/clear`, then type `go`.
+- **By hand**: `/context-handoff:handoff`, then `/clear` and `go`.
+- **Past a block**: start the prompt with `handoff`, or add `#override`.
+- **Check a session**: `python3 bin/context-handoff check <transcript.jsonl>`.
+- **Report** of the last N days (default 7):
+  `python3 bin/context-handoff report 14`.
+
+## Settings
+
+Defaults, then `~/.claude/context-handoff.json`, then environment variables
+(`CONTEXT_HANDOFF_` + the key in upper case). A limit of 0 turns it off.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `warn_k` | 150 | context size (thousands of tokens) that triggers a handoff |
+| `block_k` | 400 | context size that blocks prompts |
+| `warn_turn_usd` | 0.50 | cost of the last turn that triggers a handoff |
+| `block_turn_usd` | 3.00 | cost of the last turn that blocks prompts |
+| `warn_session_usd` | 20 | session total that triggers a handoff |
+| `auto_handoff` | true | Claude writes the note itself; false = only a warning |
+| `max_age_min` | 180 | notes older than this are not resumed |
+| `handoff_dir` | `~/.claude/handoffs` | where notes go |
+| `state_dir` | `~/.claude/context-handoff` | log (`meter.jsonl`) and per-session markers |
+| `prices` | see [prices.py](src/context_handoff/prices.py) | `{"model-prefix": [input, output, cache_read]}` per million tokens |
+
+Example `~/.claude/context-handoff.json`:
+
+```json
+{ "warn_turn_usd": 1.0, "warn_session_usd": 50, "prices": { "claude-opus-5-5": [4.0, 20.0, 0.20] } }
+```
+
+## Prices
+
+The default table holds Anthropic's first-party API list prices as of November
+2026. Cache writes are priced at 1.25× input (5-minute TTL) or 2× input (1-hour
+TTL). On a Claude subscription you do not pay per token, but the same numbers
+show how fast a session uses your limits. Prices change: override them in the
+config file.
+
+## Limits
+
+- A plugin cannot run `/clear` for you. That one step stays manual.
+- Notes are matched by the project folder's name, and only those newer than
+  `max_age_min` are loaded.
+- The meter reads the transcript, so the first prompt of a session is not
+  metered.
+- Costs are estimates from the transcript's usage fields, not your bill.
+
+## Privacy
+
+Everything runs locally. The plugin reads your transcripts in `~/.claude` and
+writes notes and a log there. Nothing is sent anywhere. Do not put secrets in
+handoff notes.
+
+## Development
+
+```
+python3 -m unittest discover -s tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

context_handoff-0.1.1/README.md

@@ -0,0 +1,161 @@
+# context-handoff
+
+[![ci](https://github.com/YauhenBichel/context-handoff/actions/workflows/ci.yml/badge.svg)](https://github.com/YauhenBichel/context-handoff/actions/workflows/ci.yml)
+[![release](https://img.shields.io/github/v/release/YauhenBichel/context-handoff)](https://github.com/YauhenBichel/context-handoff/releases)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A Claude Code plugin that keeps long sessions from getting expensive: it shows
+what each turn costs, writes a handoff note when the session grows, and resumes
+from it after `/clear`.
+
+```
+/plugin marketplace add YauhenBichel/context-handoff
+/plugin install context-handoff@context-handoff
+```
+
+Python 3.10+ as `python3`, nothing else. Details in [Install](#install).
+
+Every Claude Code turn re-sends the whole conversation. While the prompt cache
+is warm that re-read is cheap; after a pause the whole context is written to
+the cache again at up to 2× the input price. A 400K-token session on Claude
+Opus 5.5 pays about $3.20 for one such cold turn, before Claude writes a word.
+Long sessions also get slower and lose focus.
+
+context-handoff watches what each turn costs. When a session gets too big or
+too expensive, Claude writes a short handoff note at the end of the current
+task. You run `/clear`, type `go`, and a fresh, small session continues from
+the note.
+
+What you see above a prompt once a session is past the warn limit:
+
+```
+[context-handoff] 182K context, last turn $0.61, session $14.20, a cold turn would cost $1.46
+(claude-opus-5-5 prices). Claude will write a handoff note after this task; then /clear and type go.
+```
+
+## How it works
+
+1. **Meter** (`UserPromptSubmit` hook). Before each prompt it reads the
+   session transcript and computes, at API list prices:
+   - the context the next turn will re-send,
+   - what the last turn cost,
+   - what the whole session cost,
+   - what one cold turn would cost now.
+2. **Auto handoff**. Over a warn limit, it asks Claude (once per session) to
+   write a handoff note when the current task is done.
+3. **Block**. Over a block limit, it holds the prompt until you type `handoff`
+   or add `#override`.
+4. **Resume** (`SessionStart` hook, after `/clear`). It loads the project's
+   newest unused note into the new session, so you type `go` instead of
+   pasting a prompt. Each note is loaded once.
+
+## Install
+
+In Claude Code:
+
+```
+/plugin marketplace add YauhenBichel/context-handoff
+/plugin install context-handoff@context-handoff
+```
+
+Or from a terminal:
+
+```
+claude plugin marketplace add YauhenBichel/context-handoff
+claude plugin install context-handoff@context-handoff
+```
+
+Restart Claude Code (or start a new session) to load the hooks. The meter
+line appears from the second prompt of a session.
+
+Requires Python 3.10 or newer on `PATH` as `python3`. No other dependencies.
+
+### Without Claude Code plugins
+
+The same code is on PyPI. It gives the `context-handoff` command for reports
+and checks, for example in a shell or on a machine where you don't use the
+plugin:
+
+```
+pipx install context-handoff        # or: uv tool install context-handoff
+context-handoff report 14
+```
+
+The hooks still come from the plugin above; the package does not install them.
+
+Update or remove:
+
+```
+claude plugin marketplace update context-handoff
+claude plugin update context-handoff@context-handoff
+claude plugin uninstall context-handoff@context-handoff
+```
+
+## Use
+
+- **Normal flow**: keep working. When the meter asks, Claude writes the note
+  after the current task and tells you. Run `/clear`, then type `go`.
+- **By hand**: `/context-handoff:handoff`, then `/clear` and `go`.
+- **Past a block**: start the prompt with `handoff`, or add `#override`.
+- **Check a session**: `python3 bin/context-handoff check <transcript.jsonl>`.
+- **Report** of the last N days (default 7):
+  `python3 bin/context-handoff report 14`.
+
+## Settings
+
+Defaults, then `~/.claude/context-handoff.json`, then environment variables
+(`CONTEXT_HANDOFF_` + the key in upper case). A limit of 0 turns it off.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `warn_k` | 150 | context size (thousands of tokens) that triggers a handoff |
+| `block_k` | 400 | context size that blocks prompts |
+| `warn_turn_usd` | 0.50 | cost of the last turn that triggers a handoff |
+| `block_turn_usd` | 3.00 | cost of the last turn that blocks prompts |
+| `warn_session_usd` | 20 | session total that triggers a handoff |
+| `auto_handoff` | true | Claude writes the note itself; false = only a warning |
+| `max_age_min` | 180 | notes older than this are not resumed |
+| `handoff_dir` | `~/.claude/handoffs` | where notes go |
+| `state_dir` | `~/.claude/context-handoff` | log (`meter.jsonl`) and per-session markers |
+| `prices` | see [prices.py](src/context_handoff/prices.py) | `{"model-prefix": [input, output, cache_read]}` per million tokens |
+
+Example `~/.claude/context-handoff.json`:
+
+```json
+{ "warn_turn_usd": 1.0, "warn_session_usd": 50, "prices": { "claude-opus-5-5": [4.0, 20.0, 0.20] } }
+```
+
+## Prices
+
+The default table holds Anthropic's first-party API list prices as of November
+2026. Cache writes are priced at 1.25× input (5-minute TTL) or 2× input (1-hour
+TTL). On a Claude subscription you do not pay per token, but the same numbers
+show how fast a session uses your limits. Prices change: override them in the
+config file.
+
+## Limits
+
+- A plugin cannot run `/clear` for you. That one step stays manual.
+- Notes are matched by the project folder's name, and only those newer than
+  `max_age_min` are loaded.
+- The meter reads the transcript, so the first prompt of a session is not
+  metered.
+- Costs are estimates from the transcript's usage fields, not your bill.
+
+## Privacy
+
+Everything runs locally. The plugin reads your transcripts in `~/.claude` and
+writes notes and a log there. Nothing is sent anywhere. Do not put secrets in
+handoff notes.
+
+## Development
+
+```
+python3 -m unittest discover -s tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

context_handoff-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "context-handoff"
+dynamic = ["version"]
+description = "Keep Claude Code sessions cheap: meter cost, write a handoff note, resume after /clear"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Yauhen Bichel" }]
+dependencies = []
+keywords = ["claude", "claude-code", "llm", "cost", "context", "handoff"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development",
+]
+
+[project.scripts]
+context-handoff = "context_handoff.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/YauhenBichel/context-handoff"
+Changelog = "https://github.com/YauhenBichel/context-handoff/blob/main/CHANGELOG.md"
+Issues = "https://github.com/YauhenBichel/context-handoff/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "context_handoff.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"

context_handoff-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

context_handoff-0.1.1/src/context_handoff/__init__.py

@@ -0,0 +1,3 @@
+"""Keep Claude Code sessions cheap: meter cost, hand off, resume after /clear."""
+
+__version__ = "0.1.1"

context_handoff-0.1.1/src/context_handoff/__main__.py

@@ -0,0 +1,58 @@
+"""context-handoff entry point.
+
+    context-handoff meter    UserPromptSubmit hook (reads hook JSON on stdin)
+    context-handoff resume   SessionStart hook (reads hook JSON on stdin)
+    context-handoff report [days]
+    context-handoff check <transcript.jsonl>   print what the meter sees
+
+Hooks never fail the session: any error ends with no output and exit 0.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from . import config, meter, report, resume
+
+
+def _hook(fn) -> int:
+    try:
+        event = json.load(sys.stdin)
+        out = fn(event, config.load())
+    except Exception as exc:  # a hook must never break the session
+        print(f"context-handoff: {exc}", file=sys.stderr)
+        return 0
+    if out:
+        print(json.dumps(out))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    cmd = argv[0] if argv else ""
+    if cmd == "meter":
+        return _hook(meter.run)
+    if cmd == "resume":
+        return _hook(resume.run)
+    if cmd == "report":
+        days = int(argv[1]) if len(argv) > 1 else 7
+        print(report.render(config.load(), days))
+        return 0
+    if cmd == "check" and len(argv) > 1:
+        cfg = config.load()
+        r = meter.measure(argv[1], cfg)
+        if r is None:
+            print("no Claude replies in that transcript")
+            return 1
+        block, warn = meter.reasons(r, cfg)
+        print(r.summary())
+        print("block:", "; ".join(block) or "no")
+        print("warn: ", "; ".join(warn) or "no")
+        return 0
+    print(__doc__.strip())
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

context_handoff-0.1.1/src/context_handoff/config.py

@@ -0,0 +1,90 @@
+"""Settings: defaults, then ~/.claude/context-handoff.json, then environment.
+
+Config file example (all keys optional):
+
+    {
+      "warn_k": 150, "block_k": 400,
+      "warn_turn_usd": 0.50, "block_turn_usd": 3.00,
+      "warn_session_usd": 20, "auto_handoff": true,
+      "prices": {"claude-opus-5-5": [4.0, 20.0, 0.20]}
+    }
+
+Environment variables use the same names, upper case, with a
+CONTEXT_HANDOFF_ prefix: CONTEXT_HANDOFF_WARN_TURN_USD=1.0 and so on.
+A limit set to 0 is turned off.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+from .prices import DEFAULT_PRICES
+
+
+def _home() -> Path:
+    return Path(os.environ.get("HOME") or Path.home())
+
+
+@dataclass
+class Config:
+    warn_k: int = 150  # context size (thousands of tokens) that triggers a handoff
+    block_k: int = 400  # context size that blocks prompts until a handoff
+    warn_turn_usd: float = 0.50  # cost of the last turn that triggers a handoff
+    block_turn_usd: float = 3.00  # cost of the last turn that blocks prompts
+    warn_session_usd: float = 20.0  # whole-session cost that triggers a handoff
+    auto_handoff: bool = True  # ask Claude to write the note itself
+    max_age_min: int = 180  # notes older than this are not resumed
+    handoff_dir: str = ""
+    state_dir: str = ""
+    prices: dict = field(default_factory=lambda: dict(DEFAULT_PRICES))
+
+    @property
+    def notes(self) -> Path:
+        return Path(self.handoff_dir) if self.handoff_dir else _home() / ".claude" / "handoffs"
+
+    @property
+    def state(self) -> Path:
+        return Path(self.state_dir) if self.state_dir else _home() / ".claude" / "context-handoff"
+
+
+def _coerce(kind, value):
+    if kind is bool or kind == "bool":
+        return str(value).strip().lower() in ("1", "true", "yes", "on")
+    if kind is int or kind == "int":
+        return int(float(value))
+    if kind is float or kind == "float":
+        return float(value)
+    return str(value)
+
+
+def load(path: str | Path | None = None) -> Config:
+    cfg = Config()
+    path = Path(path) if path else Path(
+        os.environ.get("CONTEXT_HANDOFF_CONFIG") or _home() / ".claude" / "context-handoff.json"
+    )
+    data: dict = {}
+    if path.is_file():
+        try:
+            data = json.loads(path.read_text())
+        except (OSError, ValueError):
+            data = {}
+    for f in fields(Config):
+        if f.name == "prices":
+            continue
+        env = os.environ.get("CONTEXT_HANDOFF_" + f.name.upper())
+        raw = env if env not in (None, "") else data.get(f.name)
+        if raw is not None:
+            try:
+                setattr(cfg, f.name, _coerce(f.type, raw))
+            except (TypeError, ValueError):
+                pass
+    for prefix, row in (data.get("prices") or {}).items():
+        try:
+            i, o, r = (float(x) for x in row)
+            cfg.prices[prefix] = (i, o, r)
+        except (TypeError, ValueError):
+            pass
+    return cfg