context-handoff 0.1.1__py3-none-any.whl

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/__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/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

context_handoff/meter.py

@@ -0,0 +1,177 @@
+"""UserPromptSubmit hook: decide whether this session has become too expensive.
+
+Every turn re-sends the whole conversation. While the prompt cache is warm the
+re-read is cheap; after a pause the whole context is written again at the
+cache-write price, and that is where long sessions get expensive. The meter
+looks at three numbers from the transcript:
+
+  * context: tokens the last reply read (what the next turn re-sends)
+  * last turn: what the last reply cost
+  * session: what all replies in this session cost so far
+
+and also projects what one cold turn (cache expired) would cost now.
+
+Over a warn limit it asks Claude, once per session, to write a handoff note
+when the current task is done. Over a block limit it blocks the prompt until
+the owner asks for the handoff (prompt starts with "handoff") or overrides it
+("#override").
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import transcript
+from .config import Config
+from .prices import lookup
+
+BYPASS = re.compile(r"^\s*/?([a-z0-9-]+:)?handoff\b|#override", re.IGNORECASE)
+# The plugin's /handoff command defines the note's format; the meter reuses it.
+COMMAND_FILE = Path(__file__).resolve().parents[2] / "commands" / "handoff.md"
+
+
+@dataclass
+class Reading:
+    model: str
+    context: int
+    last_turn_usd: float
+    session_usd: float
+    cold_turn_usd: float
+    turns: int
+
+    def summary(self) -> str:
+        return (
+            f"{self.context // 1000}K context, last turn ${self.last_turn_usd:.2f}, "
+            f"session ${self.session_usd:.2f}, a cold turn would cost ${self.cold_turn_usd:.2f} "
+            f"({self.model} prices)"
+        )
+
+
+def measure(path: str, cfg: Config) -> Reading | None:
+    session = transcript.read(path)
+    last = session.last
+    if last is None:
+        return None
+    price = lookup(last.model, cfg.prices)
+    return Reading(
+        model=price.model,
+        context=last.context,
+        last_turn_usd=last.cost(price),
+        session_usd=session.cost(cfg.prices),
+        cold_turn_usd=last.context * price.write_1h / 1e6,
+        turns=len(session.turns),
+    )
+
+
+def _over(value: float, limit: float) -> bool:
+    return limit > 0 and value >= limit
+
+
+def reasons(r: Reading, cfg: Config) -> tuple[list[str], list[str]]:
+    """(block reasons, warn reasons)."""
+    block, warn = [], []
+    if _over(r.context, cfg.block_k * 1000):
+        block.append(f"context {r.context // 1000}K >= {cfg.block_k}K")
+    if _over(r.last_turn_usd, cfg.block_turn_usd):
+        block.append(f"last turn ${r.last_turn_usd:.2f} >= ${cfg.block_turn_usd:.2f}")
+    if _over(r.context, cfg.warn_k * 1000):
+        warn.append(f"context {r.context // 1000}K >= {cfg.warn_k}K")
+    if _over(r.last_turn_usd, cfg.warn_turn_usd):
+        warn.append(f"last turn ${r.last_turn_usd:.2f} >= ${cfg.warn_turn_usd:.2f}")
+    if _over(r.session_usd, cfg.warn_session_usd):
+        warn.append(f"session ${r.session_usd:.2f} >= ${cfg.warn_session_usd:.2f}")
+    return block, warn
+
+
+def note_path(cfg: Config, cwd: str, now: dt.datetime | None = None) -> Path:
+    now = now or dt.datetime.now()
+    project = Path(cwd).name or "session"
+    return cfg.notes / f"{project}-{now:%Y%m%d-%H%M}.md"
+
+
+def note_instructions() -> str:
+    """The handoff command's body: the one place the note's format is defined."""
+    try:
+        text = COMMAND_FILE.read_text()
+    except OSError:
+        return "Write the goal, state, decisions, open items and next steps, where things are, and gotchas."
+    if text.startswith("---"):
+        text = text.split("---", 2)[2]
+    return text.replace("$ARGUMENTS", "").strip()
+
+
+def _log(cfg: Config, event: dict) -> None:
+    try:
+        cfg.state.mkdir(parents=True, exist_ok=True)
+        with open(cfg.state / "meter.jsonl", "a") as f:
+            f.write(json.dumps(event) + "\n")
+    except OSError:
+        pass
+
+
+def run(event: dict, cfg: Config) -> dict | None:
+    """Hook output as a dict, or None for no output."""
+    path = event.get("transcript_path") or ""
+    session = event.get("session_id") or ""
+    cwd = event.get("cwd") or ""
+    prompt = event.get("prompt") or ""
+    if not path or not Path(path).is_file():
+        return None
+    r = measure(path, cfg)
+    if r is None:
+        return None
+
+    _log(cfg, {
+        "ts": dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds"),
+        "session": session, "cwd": cwd, "model": r.model, "ctx": r.context,
+        "turn_usd": round(r.last_turn_usd, 4), "session_usd": round(r.session_usd, 4),
+    })
+
+    block, warn = reasons(r, cfg)
+    if BYPASS.search(prompt):
+        if block or warn:
+            return {"systemMessage": f"[context-handoff] {r.summary()}; prompt let through."}
+        return None
+
+    if block:
+        return {
+            "decision": "block",
+            "reason": (
+                f"[context-handoff] {'; '.join(block)}. {r.summary()}. Every turn re-sends the whole "
+                "session. Type: handoff (Claude saves a note), then /clear and type go. "
+                "Add #override to send this prompt anyway."
+            ),
+        }
+    if not warn:
+        return None
+
+    marker = cfg.state / f"asked-{session}"
+    if cfg.auto_handoff and session and not marker.exists():
+        try:
+            cfg.state.mkdir(parents=True, exist_ok=True)
+            marker.touch()
+        except OSError:
+            pass
+        target = note_path(cfg, cwd)
+        context = (
+            f"[context-handoff] This session has become expensive: {'; '.join(warn)}. {r.summary()}. "
+            "Answer the owner's message first. Then, at the end of the current task (or now, if "
+            f"nothing is in progress), write a handoff note to {target} following these "
+            "instructions:\n\n" + note_instructions()
+        )
+        return {
+            "systemMessage": (
+                f"[context-handoff] {r.summary()}. Claude will write a handoff note after this "
+                "task; then /clear and type go."
+            ),
+            "hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": context},
+        }
+    return {
+        "systemMessage": (
+            f"[context-handoff] {r.summary()}. Finish this task, type handoff, then /clear and go."
+        )
+    }

context_handoff/prices.py

@@ -0,0 +1,66 @@
+"""Default per-million-token prices (USD) for Claude models on the Anthropic API.
+
+Source: Anthropic's published first-party prices as of November 2026. Prices
+change; override them in the config file (see config.py) rather than trusting
+these forever. Cache writes cost 1.25x input (5-minute TTL) or 2x input
+(1-hour TTL); cache reads have their own rate per model.
+
+Each entry: model-id prefix -> (input, output, cache_read).
+The longest matching prefix wins, so "claude-opus-4-8" beats "claude-opus-4".
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_PRICES: dict[str, tuple[float, float, float]] = {
+    "claude-fable-5-2": (8.00, 40.00, 0.20),
+    "claude-mythos-5-2": (8.00, 40.00, 0.20),
+    "claude-fable-5-1": (10.00, 50.00, 0.25),
+    "claude-mythos-5-1": (10.00, 50.00, 0.25),
+    "claude-fable-5": (10.00, 50.00, 1.00),
+    "claude-mythos-5": (10.00, 50.00, 1.00),
+    "claude-opus-5-5": (4.00, 20.00, 0.20),
+    "claude-opus-5": (5.00, 25.00, 0.50),
+    "claude-opus-4": (5.00, 25.00, 0.50),
+    "claude-sonnet-5-5": (2.00, 10.00, 0.10),
+    "claude-sonnet-5": (2.00, 10.00, 0.20),
+    "claude-sonnet-4": (3.00, 15.00, 0.30),
+    "claude-haiku-5-5": (0.10, 0.50, 0.01),
+    "claude-haiku-4": (1.00, 5.00, 0.10),
+}
+
+# Used when the model id matches nothing above: priced like the default Opus.
+FALLBACK = "claude-opus-5-5"
+
+WRITE_5M = 1.25
+WRITE_1H = 2.0
+
+
+@dataclass(frozen=True)
+class Price:
+    model: str
+    input: float
+    output: float
+    cache_read: float
+
+    @property
+    def write_5m(self) -> float:
+        return self.input * WRITE_5M
+
+    @property
+    def write_1h(self) -> float:
+        return self.input * WRITE_1H
+
+
+def lookup(model: str, table: dict[str, tuple[float, float, float]] | None = None) -> Price:
+    table = table or DEFAULT_PRICES
+    model = (model or "").lower()
+    best = ""
+    for prefix in table:
+        if model.startswith(prefix) and len(prefix) > len(best):
+            best = prefix
+    if not best:
+        best = FALLBACK if FALLBACK in table else next(iter(table))
+    i, o, r = table[best]
+    return Price(best, i, o, r)

context_handoff/report.py

@@ -0,0 +1,50 @@
+"""What Claude Code sessions cost, from local transcripts (API list prices)."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from . import transcript
+from .config import Config
+from .prices import lookup
+
+
+def rows(cfg: Config, days: int, root: Path | None = None):
+    root = root or Path.home() / ".claude" / "projects"
+    cutoff = time.time() - days * 86400
+    for f in root.glob("*/*.jsonl"):
+        try:
+            if f.stat().st_mtime < cutoff:
+                continue
+        except OSError:
+            continue
+        s = transcript.read(f)
+        if not s.turns:
+            continue
+        peak = max(t.context for t in s.turns)
+        cold = s.last.context * lookup(s.last.model, cfg.prices).write_1h / 1e6
+        yield {
+            "project": f.parent.name, "session": f.stem[:8], "turns": len(s.turns),
+            "usd": s.cost(cfg.prices), "peak_k": peak // 1000, "cold_usd": cold,
+        }
+
+
+def render(cfg: Config, days: int = 7, root: Path | None = None, top: int = 15) -> str:
+    data = sorted(rows(cfg, days, root), key=lambda r: r["usd"], reverse=True)
+    if not data:
+        return f"no sessions in the last {days} days"
+    total = sum(r["usd"] for r in data)
+    over = sum(1 for r in data if r["peak_k"] >= cfg.warn_k)
+    out = [
+        f"last {days} days: {len(data)} sessions, ${total:.2f} at API list prices, "
+        f"{over} sessions peaked over {cfg.warn_k}K context",
+        "",
+        f"{'usd':>9} {'turns':>6} {'peak(K)':>8} {'cold turn':>10}  project / session",
+    ]
+    for r in data[:top]:
+        out.append(
+            f"{r['usd']:>9.2f} {r['turns']:>6} {r['peak_k']:>8} {r['cold_usd']:>10.2f}  "
+            f"{r['project']} / {r['session']}"
+        )
+    return "\n".join(out)

context_handoff/resume.py

@@ -0,0 +1,63 @@
+"""SessionStart hook (after /clear): load the project's newest unused handoff note."""
+
+from __future__ import annotations
+
+import re
+import time
+from pathlib import Path
+
+from .config import Config
+
+MAX_BYTES = 12_000
+
+
+def find_note(cfg: Config, cwd: str, now: float | None = None) -> Path | None:
+    notes = cfg.notes
+    if not cwd or not notes.is_dir():
+        return None
+    project = Path(cwd).name
+    pattern = re.compile(re.escape(project) + r"-\d{8}-\d{4}\.md$")
+    used = _used(cfg)
+    now = now or time.time()
+    candidates = []
+    for p in notes.iterdir():
+        if not pattern.fullmatch(p.name) or str(p) in used:
+            continue
+        try:
+            mtime = p.stat().st_mtime
+        except OSError:
+            continue
+        if cfg.max_age_min > 0 and now - mtime > cfg.max_age_min * 60:
+            continue
+        candidates.append((mtime, p))
+    return max(candidates)[1] if candidates else None
+
+
+def _used(cfg: Config) -> set[str]:
+    try:
+        return set((cfg.notes / ".used").read_text().split("\n"))
+    except OSError:
+        return set()
+
+
+def run(event: dict, cfg: Config) -> dict | None:
+    note = find_note(cfg, event.get("cwd") or "")
+    if note is None:
+        return None
+    try:
+        body = note.read_text(errors="replace")[:MAX_BYTES]
+        with open(cfg.notes / ".used", "a") as f:
+            f.write(str(note) + "\n")
+    except OSError:
+        return None
+    return {
+        "systemMessage": f"[context-handoff] loaded {note}; type go to continue",
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": (
+                f"A handoff note from the previous session was loaded ({note}). On the owner's first "
+                'message, continue from its "Open items and next steps" unless the owner asks for '
+                "something else.\n\n" + body
+            ),
+        },
+    }

context_handoff/transcript.py

@@ -0,0 +1,97 @@
+"""Read token usage from a Claude Code session transcript (JSON lines)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .prices import Price, lookup
+
+
+@dataclass
+class Turn:
+    """Usage of one model reply."""
+
+    model: str
+    input: int = 0
+    cache_write_5m: int = 0
+    cache_write_1h: int = 0
+    cache_read: int = 0
+    output: int = 0
+
+    @property
+    def context(self) -> int:
+        """Tokens the model read for this reply: what the next turn re-sends."""
+        return self.input + self.cache_write_5m + self.cache_write_1h + self.cache_read
+
+    def cost(self, price: Price) -> float:
+        return (
+            self.input * price.input
+            + self.cache_write_5m * price.write_5m
+            + self.cache_write_1h * price.write_1h
+            + self.cache_read * price.cache_read
+            + self.output * price.output
+        ) / 1e6
+
+
+@dataclass
+class Session:
+    turns: list[Turn] = field(default_factory=list)
+
+    @property
+    def last(self) -> Turn | None:
+        return self.turns[-1] if self.turns else None
+
+    def cost(self, table=None) -> float:
+        return sum(t.cost(lookup(t.model, table)) for t in self.turns)
+
+
+def _turn(usage: dict, model: str) -> Turn:
+    creation = usage.get("cache_creation") or {}
+    w5 = creation.get("ephemeral_5m_input_tokens")
+    w1 = creation.get("ephemeral_1h_input_tokens")
+    total_write = usage.get("cache_creation_input_tokens") or 0
+    if w5 is None and w1 is None:
+        # No TTL breakdown: Claude Code writes with the 1-hour TTL, so price it as that.
+        w5, w1 = 0, total_write
+    return Turn(
+        model=model,
+        input=usage.get("input_tokens") or 0,
+        cache_write_5m=w5 or 0,
+        cache_write_1h=w1 or 0,
+        cache_read=usage.get("cache_read_input_tokens") or 0,
+        output=usage.get("output_tokens") or 0,
+    )
+
+
+def read(path: str | Path) -> Session:
+    """Main-thread Claude replies, one per message id, in order.
+
+    A reply is written as several transcript lines repeating the same usage,
+    so only the last line seen for each message id counts.
+    """
+    replies: dict[str, Turn] = {}
+    try:
+        f = open(path, encoding="utf-8", errors="replace")
+    except OSError:
+        return Session()
+    with f:
+        for line in f:
+            if '"usage"' not in line or '"assistant"' not in line:
+                continue
+            try:
+                rec = json.loads(line)
+            except ValueError:
+                continue
+            if rec.get("type") != "assistant" or rec.get("isSidechain"):
+                continue
+            msg = rec.get("message") or {}
+            usage = msg.get("usage")
+            model = msg.get("model") or ""
+            if not usage or not model.startswith("claude"):
+                continue
+            key = msg.get("id") or f"line-{len(replies)}"
+            replies.pop(key, None)  # keep insertion order at the latest position
+            replies[key] = _turn(usage, model)
+    return Session(list(replies.values()))

context_handoff-0.1.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+context_handoff/__init__.py,sha256=yNmguB0FR0W_PRnGEwLiCq878C16JtzTwjNOsowM4ro,105
+context_handoff/__main__.py,sha256=HAVx6Bdxknoy6a7MFGr-SRfRa8YtwJsF8B0KJjcahnI,1658
+context_handoff/config.py,sha256=xtz6NkHgMSgXM_tQ6kZn8AIIRdn_n_oBR-mfz46xYNc,3007
+context_handoff/meter.py,sha256=Z4jkPElt5QOR6yL1cXx0c-wRRNrRCzY-3jytfMB2YMM,6360
+context_handoff/prices.py,sha256=dERyLRaYIoejXPWfUi9mB4qK6MOhMby6Rg0QgntXdzk,2122
+context_handoff/report.py,sha256=HsPpYJrPaAcW9Fju5qWfLuVDZrYztZtecmyR1QHPWbc,1773
+context_handoff/resume.py,sha256=iYNU28T0aa2uCUhUqciGSQ5HO9D06hQBpz23jzE9TX8,1920
+context_handoff/transcript.py,sha256=n4xHVHjCSxwAPp0pwVmGMlRXqy1buv-Q9NB3w_AZ4B0,3091
+context_handoff-0.1.1.dist-info/licenses/LICENSE,sha256=b5IGCXKe5CTz8uH4O5cBtOC0aVMSlOgoKEC6DOHyOy4,1070
+context_handoff-0.1.1.dist-info/METADATA,sha256=BeJTLVhQxGFvTHuwokA-kYGMTMldDR0cp_KceXrikUU,6904
+context_handoff-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+context_handoff-0.1.1.dist-info/entry_points.txt,sha256=wJyGDDsDpPcM_rNd5DtAz9mi2equgTTxyPTvFGCfdUU,66
+context_handoff-0.1.1.dist-info/top_level.txt,sha256=a7XB-PbU5WJWkEViOFBiIJR4SyEcw6ohWF2sTEtVGzk,16
+context_handoff-0.1.1.dist-info/RECORD,,

context_handoff-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

context_handoff-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+context-handoff = context_handoff.__main__:main

context_handoff-0.1.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+context_handoff