havrin 0.1.0__tar.gz

havrin-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.env
+*.gguf
+*.safetensors
+.wrangler/
+node_modules/
+dist/
+.venv/

havrin-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.5
+Name: havrin
+Version: 0.1.0
+Summary: See where your Claude Code usage goes, from your own local session logs
+Project-URL: Homepage, https://havrin.dev
+Author: Gavin Schiller
+License-Expression: MIT
+License-File: havrin/LICENSE
+Keywords: claude,claude-code,cost,llm,usage
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# havrin
+
+See where your Claude Code usage goes, from the session logs Claude Code already keeps on your machine.
+
+```sh
+pipx install havrin        # or: pip install havrin
+havrin meter --days 30 --what-if
+```
+
+The meter reads the JSONL transcripts in `~/.claude/projects` and prints:
+
+- tokens by kind (input, cache writes, cache reads, output) and each kind's cost-weighted share;
+- which tools filled the context, in characters;
+- with `--what-if`: the share of cost you would have saved with subagents on Sonnet, with the main context capped
+  (150k tokens by default), and with both. These are estimates replayed from your own logs, not promises.
+
+**Privacy:** it only reads local files, sends nothing anywhere, and prints counts, never the content of your sessions.
+
+Options: `--days N` (default 7), `--sessions` (one line per transcript), `--dir PATH`, `--sonnet-ratio`, `--cap`.
+Python 3.10+, no dependencies.
+
+Havrin is building the rest: routing routine Claude Code steps to cheaper models and your own machine, with your
+tests checking every result. Join the beta at [havrin.dev](https://havrin.dev).

havrin-0.1.0/havrin/LICENSE

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

havrin-0.1.0/havrin/README.md

@@ -0,0 +1,23 @@
+# havrin
+
+See where your Claude Code usage goes, from the session logs Claude Code already keeps on your machine.
+
+```sh
+pipx install havrin        # or: pip install havrin
+havrin meter --days 30 --what-if
+```
+
+The meter reads the JSONL transcripts in `~/.claude/projects` and prints:
+
+- tokens by kind (input, cache writes, cache reads, output) and each kind's cost-weighted share;
+- which tools filled the context, in characters;
+- with `--what-if`: the share of cost you would have saved with subagents on Sonnet, with the main context capped
+  (150k tokens by default), and with both. These are estimates replayed from your own logs, not promises.
+
+**Privacy:** it only reads local files, sends nothing anywhere, and prints counts, never the content of your sessions.
+
+Options: `--days N` (default 7), `--sessions` (one line per transcript), `--dir PATH`, `--sonnet-ratio`, `--cap`.
+Python 3.10+, no dependencies.
+
+Havrin is building the rest: routing routine Claude Code steps to cheaper models and your own machine, with your
+tests checking every result. Join the beta at [havrin.dev](https://havrin.dev).

havrin-0.1.0/havrin/__init__.py

@@ -0,0 +1,2 @@
+"""Havrin: see where your Claude Code usage goes, from your own local session logs."""
+__version__ = "0.1.0"

havrin-0.1.0/havrin/__main__.py

@@ -0,0 +1,30 @@
+"""The `havrin` command. The meter itself is hybrid/meter.py, copied in as havrin/meter.py at build time
+(see pyproject.toml), so the private repo keeps one copy of it."""
+import sys
+
+from . import __version__
+
+USAGE = """usage: havrin meter [--days N] [--what-if] [--sessions] [--dir PATH]
+       havrin --version
+
+  meter   where your Claude Code usage went, read from local session logs (nothing is sent anywhere)"""
+
+
+def main(argv=None):
+    args = sys.argv[1:] if argv is None else argv
+    if args[:1] == ["meter"]:
+        from . import meter
+        meter.main(args[1:], prog="havrin meter")
+        return 0
+    if args[:1] in (["--version"], ["-V"]):
+        print(f"havrin {__version__}")
+        return 0
+    if args[:1] in ([], ["-h"], ["--help"]):
+        print(USAGE)
+        return 0
+    print(USAGE, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

havrin-0.1.0/hybrid/meter.py

@@ -0,0 +1,171 @@
+"""Savings meter, step 1: where a coding agent's usage goes, read from Claude Code's own session logs.
+
+Usage: python3 -m hybrid.meter [--days 7] [--dir ~/.claude/projects]
+
+Reads the local JSONL transcripts Claude Code writes (one file per session) and prints, per session and in total:
+- tokens by kind;
+- a cost-weighted share of each kind;
+- characters each tool's results added to the context;
+- characters written as text or tool input.
+
+Only local files are read, nothing is sent anywhere, and only counts are printed, never content.
+Savings need a comparison (helpers on vs. off); this module only measures.
+"""
+import argparse
+import json
+import time
+from collections import Counter
+from pathlib import Path
+
+KINDS = ("input", "cache_write_5m", "cache_write_1h", "cache_read", "output")
+# shortcut: Anthropic list-price ratios to new input as of 2026-10 (5-minute cache writes 1.25x, 1-hour writes 2x,
+# reads 0.1x, output 5x); verify against current pricing, and use per-model prices if dollars are needed.
+WEIGHTS = {"input": 1.0, "cache_write_5m": 1.25, "cache_write_1h": 2.0, "cache_read": 0.1, "output": 5.0}
+
+
+def _tokens(usage):
+    split = usage.get("cache_creation") or {}
+    write_1h = split.get("ephemeral_1h_input_tokens", 0)
+    return Counter({"input": usage.get("input_tokens", 0),
+                    "cache_write_5m": usage.get("cache_creation_input_tokens", 0) - write_1h,
+                    "cache_write_1h": write_1h,
+                    "cache_read": usage.get("cache_read_input_tokens", 0),
+                    "output": usage.get("output_tokens", 0)})
+
+
+def _text(content):
+    if isinstance(content, str):
+        return content
+    return "".join(x.get("text", "") for x in content if isinstance(x, dict)) if isinstance(content, list) else ""
+
+
+def session(path, seen=None):
+    """{"requests", "tokens", "models", "read", "written", "start", "end"} for one transcript. A request's usage is
+    logged once per content block, so it is counted once per requestId (the last entry wins). Requests already in
+    `seen` (a set shared across files: resumed sessions repeat earlier requests) are skipped and new ones added."""
+    seen = set() if seen is None else seen
+    usage, names, read, written, stamps = {}, {}, Counter(), Counter(), []
+    with open(path, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            try:
+                e = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(e, dict) or not isinstance(e.get("message"), dict):
+                continue
+            if e.get("timestamp"):
+                stamps.append(e["timestamp"])
+            m, kind = e["message"], e.get("type")
+            content = m.get("content") if isinstance(m.get("content"), list) else []
+            if kind == "assistant":
+                rid = e.get("requestId") or e.get("uuid")
+                if isinstance(m.get("usage"), dict) and rid not in seen:
+                    usage[rid] = (m.get("model") or "?", m["usage"])
+                for b in content:
+                    if isinstance(b, dict) and b.get("type") == "tool_use":
+                        names[b.get("id")] = b.get("name", "?")
+                        written[b.get("name", "?")] += len(json.dumps(b.get("input", {})))
+                    elif isinstance(b, dict) and b.get("type") == "text":
+                        written["text"] += len(b.get("text", ""))
+            elif kind == "user":
+                for b in content:
+                    if isinstance(b, dict) and b.get("type") == "tool_result":
+                        read[names.get(b.get("tool_use_id"), "?")] += len(_text(b.get("content")))
+    seen.update(usage)
+    models = Counter()
+    for model, u in usage.values():
+        models[model] += sum(weighted(_tokens(u)).values())
+    return {"requests": len(usage), "tokens": sum((_tokens(u) for _, u in usage.values()), Counter()),
+            "models": models, "reads": [u.get("cache_read_input_tokens", 0) for _, u in usage.values()],
+            "read": read, "written": written, "start": min(stamps, default=""),
+            "end": max(stamps, default="")}
+
+
+def sessions(root, days):
+    """(path, session) for transcripts under `root` modified in the last `days` days, oldest first."""
+    since = time.time() - days * 86400
+    paths = sorted((p for p in Path(root).expanduser().rglob("*.jsonl") if p.stat().st_mtime >= since),
+                   key=lambda p: p.stat().st_mtime)
+    seen = set()
+    return [(p, s) for p in paths if (s := session(p, seen))["requests"]]
+
+
+def _shares(counter, top=6):
+    total = sum(counter.values())
+    if not total:
+        return "none"
+    shown = [(k, v) for k, v in counter.most_common(top) if v]
+    rest = total - sum(v for _, v in shown)
+    return ", ".join(f"{k} {v / total:.0%}" for k, v in shown) + (f", other {rest / total:.0%}" if rest else "")
+
+
+def weighted(tokens):
+    return Counter({k: tokens[k] * WEIGHTS[k] for k in KINDS})
+
+
+def report(found, per_session=False):
+    lines, tokens, models, read, written = [], Counter(), Counter(), Counter(), Counter()
+    for path, s in found:
+        w = weighted(s["tokens"])
+        if per_session:
+            lines.append(f"{s['start'][:16]} {path.stem[:8]}: {s['requests']} requests, "
+                         f"{sum(w.values()) / 1e6:.2f}M input-equivalent tokens ({_shares(w)})")
+        tokens.update(s["tokens"]), models.update(s["models"]), read.update(s["read"]), written.update(s["written"])
+    if not found:
+        return ["no Claude Code sessions with usage found"]
+    requests = sum(s["requests"] for _, s in found)
+    context = tokens["input"] + tokens["cache_write_5m"] + tokens["cache_write_1h"] + tokens["cache_read"]
+    subagents = sum(p.stem.startswith("agent-") for p, _ in found)
+    sub_cost = sum(sum(s["models"].values()) for p, s in found if p.stem.startswith("agent-"))
+    all_cost = sum(sum(s["models"].values()) for _, s in found)
+    return lines + ([""] if lines else []) + [
+                    f"total: {len(found)} transcripts ({subagents} subagent), {requests} requests, "
+                    f"{sum(weighted(tokens).values()) / 1e6:.1f}M input-equivalent tokens",
+                    f"  average context per request: {context / requests:,.0f} tokens",
+                    f"  cost-weighted, by kind: {_shares(weighted(tokens))}",
+                    f"  cost-weighted, by model: {_shares(models)}",
+                    f"  subagents' share of cost: {sub_cost / all_cost if all_cost else 0:.0%}",
+                    f"  tokens: " + ", ".join(f"{k} {tokens[k]:,}" for k in KINDS),
+                    f"  chars read, by tool: {_shares(read)} ({sum(read.values()):,} chars)",
+                    f"  chars written, by kind: {_shares(written)} ({sum(written.values()):,} chars)"]
+
+
+def what_if(found, sonnet_ratio=0.6, cap=150_000):
+    """Replay of the measured usage under two changes, in cost-weighted tokens:
+    - subagents that ran on Opus repriced at `sonnet_ratio` of Opus (list-price ratio; check current prices);
+    - main conversations never re-reading more than `cap` tokens of context per request (as if cleared or compacted
+      there). shortcut: an upper bound; work lost by clearing would partly be re-read, which only a live test shows.
+    """
+    total = sum(sum(s["models"].values()) for _, s in found)
+    if not total:
+        return ["no usage to replay"]
+    agent = [s for p, s in found if p.stem.startswith("agent-")]
+    main_ = [s for p, s in found if not p.stem.startswith("agent-")]
+    opus_sub = sum(v for s in agent for m, v in s["models"].items() if "opus" in m)
+    sub_saving = opus_sub * (1 - sonnet_ratio)
+    cap_saving = sum(max(0, r - cap) * WEIGHTS["cache_read"] for s in main_ for r in s["reads"])
+    lines = [f"what-if replay of {total / 1e6:.1f}M input-equivalent tokens:",
+             f"  subagents on Sonnet (Opus subagent cost {opus_sub / total:.0%} of total, Sonnet at "
+             f"{sonnet_ratio:.0%} of Opus price): saves {sub_saving / total:.0%}",
+             f"  main context capped at {cap // 1000}k tokens (upper bound): saves {cap_saving / total:.0%}",
+             f"  both: saves {(sub_saving + cap_saving) / total:.0%}"]
+    return lines
+
+
+def main(argv=None, prog="python3 -m hybrid.meter"):
+    p = argparse.ArgumentParser(prog=prog, description=__doc__.split("\n")[0])
+    p.add_argument("--days", type=float, default=7, help="sessions modified in the last N days (default 7)")
+    p.add_argument("--dir", default="~/.claude/projects", help="Claude Code transcript directory")
+    p.add_argument("--sessions", action="store_true", help="also print one line per transcript")
+    p.add_argument("--what-if", action="store_true", help="also replay the usage with subagents on Sonnet and a "
+                   "context cap (see what_if)")
+    p.add_argument("--sonnet-ratio", type=float, default=0.6, help="Sonnet price as a share of Opus (default 0.6)")
+    p.add_argument("--cap", type=int, default=150_000, help="context cap in tokens for --what-if (default 150000)")
+    args = p.parse_args(argv)
+    found = sessions(args.dir, args.days)
+    print("\n".join(report(found, args.sessions) + (["", *what_if(found, args.sonnet_ratio, args.cap)]
+                                                    if args.what_if else [])))
+
+
+if __name__ == "__main__":
+    main()

havrin-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+# Builds the public `havrin` package: the meter only (MIT). The rest of this repo is private and must never
+# enter the wheel or sdist, so both targets list exactly what they ship.
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "havrin"
+dynamic = ["version"]
+description = "See where your Claude Code usage goes, from your own local session logs"
+readme = "havrin/README.md"
+license = "MIT"
+license-files = ["havrin/LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Gavin Schiller" }]
+keywords = ["claude", "claude-code", "llm", "usage", "cost"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://havrin.dev"
+
+[project.scripts]
+havrin = "havrin.__main__:main"
+
+[tool.hatch.version]
+path = "havrin/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["havrin"]
+exclude = ["havrin/README.md", "havrin/LICENSE"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"hybrid/meter.py" = "havrin/meter.py"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["havrin", "hybrid/meter.py", "pyproject.toml"]