Skip to content

duthaho/skillhub / .claude/skills/cachewise

cachewise

Verified

Prompt-cache economics forensics — why your Claude Code tokens burn so fast, with the numbers to prove it. Parses local ~/.claude transcripts (0 tokens, a bundled Python script does the counting) and attributes every cache-miss rebuild to a cause — idle gaps past the 5-min TTL, mid-session model/effort switches, prefix churn (MCP tool-lists, edited CLAUDE.md, dynamic content), and cold re-boots of a session you could have resumed — each priced in real USD, then prescribes the fixes ranked by dollars saved. Tracks before/after in out/cachewise/tracker.md so the next run measures whether a fix worked. Use when the user asks why they hit usage limits so fast, wants their cache hit rate or token spend analyzed, or where their tokens are going — e.g. "/cachewise", "analyze my prompt cache", "what's burning my tokens". For recurring behavior mistakes use tune; for today's schedule use daybrief.

FileKindSize
SKILL.mdskill md6.0 KB
scripts/analyze.pyscript17.9 KB
scripts/test_analyze.pyscript17.8 KB

scripts/test_analyze.py

View on GitHub
import json
import os
import tempfile
import unittest
from datetime import datetime, timedelta, timezone

import analyze


def entry(ts, session="s1", project="/proj", model="claude-opus-4-8",
          effort="high", read=0, creation=0, c5m=None, c1h=0, inp=1,
          out=10, sidechain=False, kind="assistant"):
    if c5m is None:
        c5m = creation - c1h
    e = {
        "type": kind,
        "isSidechain": sidechain,
        "sessionId": session,
        "cwd": project,
        "timestamp": ts,
        "effort": effort,
        "message": {
            "model": model,
            "usage": {
                "input_tokens": inp,
                "cache_read_input_tokens": read,
                "cache_creation_input_tokens": creation,
                "output_tokens": out,
                "cache_creation": {
                    "ephemeral_5m_input_tokens": c5m,
                    "ephemeral_1h_input_tokens": c1h,
                },
            },
        },
    }
    return e


def iso(dt):
    return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")


def write_jsonl(dirpath, name, entries):
    os.makedirs(os.path.join(dirpath, "projects", "p"), exist_ok=True)
    path = os.path.join(dirpath, "projects", "p", name)
    with open(path, "w") as f:
        for e in entries:
            f.write(json.dumps(e) + "\n")
    return path


class TmpClaude:
    def __enter__(self):
        self.d = tempfile.mkdtemp()
        return self

    def __exit__(self, *a):
        import shutil
        shutil.rmtree(self.d, ignore_errors=True)


class TestParsing(unittest.TestCase):
    def test_totals_and_hit_rate(self):
        base = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)
        entries = [
            entry(iso(base), read=0, creation=1000, inp=5),
            entry(iso(base + timedelta(minutes=1)), read=1000, creation=0, inp=3),
        ]
        with TmpClaude() as t:
            write_jsonl(t.d, "a.jsonl", entries)
            turns, stats = analyze.load_turns(t.d, days=3650, now=base + timedelta(minutes=2))
        self.assertEqual(len(turns), 2)
        tot = analyze.totals(turns)
        self.assertEqual(tot["cache_read"], 1000)
        self.assertEqual(tot["cache_creation"], 1000)
        self.assertAlmostEqual(tot["hit_rate"], 1000 / (1000 + 1000 + 8))

    def test_malformed_and_missing_fields_skipped(self):
        base = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)
        good = entry(iso(base), read=5, creation=0)
        with TmpClaude() as t:
            path = write_jsonl(t.d, "a.jsonl", [good])
            with open(path, "a") as f:
                f.write("{not json}\n")
                f.write(json.dumps({"type": "assistant", "message": {}}) + "\n")
                f.write(json.dumps({"type": "user", "message": {"usage": {}}}) + "\n")
            turns, stats = analyze.load_turns(t.d, days=3650, now=base + timedelta(minutes=1))
        self.assertEqual(len(turns), 1)
        self.assertEqual(stats["malformed_lines"], 1)

    def test_garbage_numeric_field_does_not_crash(self):
        base = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)
        good = entry(iso(base), read=5, creation=0)
        bad = entry(iso(base), read=0, creation=0)
        bad["message"]["usage"]["input_tokens"] = "not-a-number"
        bad["message"]["usage"]["cache_read_input_tokens"] = ["oops"]
        with TmpClaude() as t:
            write_jsonl(t.d, "a.jsonl", [good, bad])
            turns, stats = analyze.load_turns(t.d, days=3650, now=base + timedelta(minutes=1))
        self.assertEqual(len(turns), 2)  # tolerated, not crashed
        bad_turn = [x for x in turns if x["read"] == 0][0]
        self.assertEqual(bad_turn["input"], 0)  # garbage coerced to 0

    def test_missing_timestamp_excluded_from_gap_but_counted(self):
        base = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)
        e = entry(iso(base), read=5, creation=0)
        bad = entry(None, read=0, creation=200)
        with TmpClaude() as t:
            write_jsonl(t.d, "a.jsonl", [e, bad])
            turns, stats = analyze.load_turns(t.d, days=3650, now=base + timedelta(minutes=1))
        self.assertEqual(len(turns), 2)
        self.assertEqual(stats["missing_timestamp"], 1)
        timed = [x for x in turns if x["ts"] is not None]
        self.assertEqual(len(timed), 1)

    def test_out_of_order_sorted_within_session(self):
        base = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)
        later = entry(iso(base + timedelta(minutes=5)), read=10, creation=0)
        earlier = entry(iso(base), read=0, creation=100)
        with TmpClaude() as t:
            write_jsonl(t.d, "a.jsonl", [later, earlier])
            turns, stats = analyze.load_turns(t.d, days=3650, now=base + timedelta(minutes=6))
        sessions = analyze.by_session(turns)
        seq = sessions[("/proj", "s1")]
        self.assertLess(seq[0]["ts"], seq[1]["ts"])

    def test_sidechain_partitioned(self):
        base = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)
        main = entry(iso(base), session="s1", read=0, creation=100)
        side = entry(iso(base), session="s1", sidechain=True, read=0, creation=100)
        with TmpClaude() as t:
            write_jsonl(t.d, "a.jsonl", [main, side])
            turns, stats = analyze.load_turns(t.d, days=3650, now=base + timedelta(minutes=1))
        sessions = analyze.by_session(turns)
        keys = set(sessions.keys())
        self.assertIn(("/proj", "s1"), keys)
        self.assertIn(("/proj", "s1::sidechain"), keys)

    def test_days_window_filters_old(self):
        now = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)
        old = entry(iso(now - timedelta(days=40)), read=0, creation=100)
        recent = entry(iso(now - timedelta(days=1)), read=5, creation=0)
        with TmpClaude() as t:
            write_jsonl(t.d, "a.jsonl", [old, recent])
            turns, stats = analyze.load_turns(t.d, days=30, now=now)
        self.assertEqual(len(turns), 1)


class TestPricing(unittest.TestCase):
    def test_known_model_rate(self):
        rate = analyze.rate_for("claude-opus-4-8")
        self.assertEqual(rate["input"], 5.0)
        self.assertEqual(rate["output"], 25.0)
        self.assertFalse(rate["fallback"])

    def test_opus_variants(self):
        for m in ("claude-opus-5", "claude-opus-4-7", "claude-opus-4-5"):
            self.assertEqual(analyze.rate_for(m)["input"], 5.0)

    def test_haiku_and_fable(self):
        self.assertEqual(analyze.rate_for("claude-haiku-4-5-20251001")["input"], 1.0)
        self.assertEqual(analyze.rate_for("claude-fable-5")["input"], 10.0)

    def test_unknown_model_falls_back_flagged(self):
        rate = analyze.rate_for("<synthetic>")
        self.assertTrue(rate["fallback"])
        self.assertEqual(rate["input"], 3.0)

    def test_opus_4_1_exact_vs_future_double_digit(self):
        self.assertEqual(analyze.rate_for("claude-opus-4-1")["input"], 15.0)
        # a future opus-4-10..19 must not collide with the 4.1 row
        self.assertEqual(analyze.rate_for("claude-opus-4-10")["input"], 5.0)

    def test_turn_cost_5m_write_and_read(self):
        t = {"model": "claude-opus-4-8", "input": 1000, "output": 100,
             "read": 2000, "creation": 4000, "creation_5m": 4000,
             "creation_1h": 0, "has_split": True}
        c = analyze.turn_cost(t)
        self.assertAlmostEqual(c["input"], 1000 * 5.0 / 1e6)
        self.assertAlmostEqual(c["read"], 2000 * 0.1 * 5.0 / 1e6)
        self.assertAlmostEqual(c["write"], 4000 * 1.25 * 5.0 / 1e6)
        self.assertAlmostEqual(c["output"], 100 * 25.0 / 1e6)

    def test_turn_cost_1h_write(self):
        t = {"model": "claude-opus-4-8", "input": 0, "output": 0,
             "read": 0, "creation": 1000, "creation_5m": 0,
             "creation_1h": 1000, "has_split": True}
        c = analyze.turn_cost(t)
        self.assertAlmostEqual(c["write"], 1000 * 2.0 * 5.0 / 1e6)

    def test_no_split_treated_as_5m(self):
        t = {"model": "claude-opus-4-8", "input": 0, "output": 0,
             "read": 0, "creation": 1000, "creation_5m": 0,
             "creation_1h": 0, "has_split": False}
        c = analyze.turn_cost(t)
        self.assertAlmostEqual(c["write"], 1000 * 1.25 * 5.0 / 1e6)

    def test_avoidable_usd_is_write_minus_hit(self):
        av = analyze.avoidable_usd(1000, "claude-opus-4-8", "5m")
        self.assertAlmostEqual(av, 1000 * (1.25 - 0.1) * 5.0 / 1e6)


def turn(ts, **kw):
    d = {"session": "s1", "project": "/p", "ts": ts, "model": "claude-opus-4-8",
         "effort": "high", "sidechain": False, "input": 2, "output": 50,
         "read": 0, "creation": 0, "creation_5m": 0, "creation_1h": 0,
         "has_split": True}
    d.update(kw)
    if kw.get("creation") and not kw.get("creation_5m") and not kw.get("creation_1h"):
        d["creation_5m"] = d["creation"]
    return d


class TestWithinSession(unittest.TestCase):
    B = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)

    def seq(self, *turns):
        return analyze.attribute_session(list(turns))

    def test_idle_gap_rebuild(self):
        ev = self.seq(
            turn(self.B, read=20000, creation=20000),
            turn(self.B.replace(minute=15), read=0, creation=20000),
        )
        self.assertEqual(len(ev), 1)
        self.assertEqual(ev[0]["cause"], "idle_gap")

    def test_idle_gap_with_switch_tagged(self):
        ev = self.seq(
            turn(self.B, read=20000, creation=20000),
            turn(self.B.replace(minute=15), read=0, creation=20000,
                 model="claude-opus-4-7"),
        )
        self.assertEqual(ev[0]["cause"], "idle_gap")
        self.assertIn("switch", ev[0]["tags"])

    def test_model_switch_within_ttl(self):
        ev = self.seq(
            turn(self.B, read=20000, creation=20000),
            turn(self.B.replace(minute=1), read=0, creation=20000,
                 model="claude-opus-4-7"),
        )
        self.assertEqual(ev[0]["cause"], "model_switch")

    def test_effort_switch_within_ttl(self):
        ev = self.seq(
            turn(self.B, read=20000, creation=20000),
            turn(self.B.replace(minute=1), read=0, creation=20000, effort="xhigh"),
        )
        self.assertEqual(ev[0]["cause"], "model_switch")

    def test_write_churn(self):
        ev = self.seq(
            turn(self.B, read=20000, creation=20000),
            turn(self.B.replace(minute=1), read=0, creation=20000),
        )
        self.assertEqual(ev[0]["cause"], "write_churn")

    def test_small_incremental_write_not_a_miss(self):
        ev = self.seq(
            turn(self.B, read=20000, creation=20000),
            turn(self.B.replace(minute=1), read=20000, creation=500),
        )
        self.assertEqual(ev, [])

    def test_below_cache_floor_ignored(self):
        ev = self.seq(
            turn(self.B, read=1000, creation=1000),
            turn(self.B.replace(minute=15), read=0, creation=1000),
        )
        self.assertEqual(ev, [])

    def test_missing_timestamp_unattributed(self):
        ev = self.seq(
            turn(self.B, read=20000, creation=20000),
            turn(None, read=0, creation=20000),
        )
        self.assertEqual(ev[0]["cause"], "unattributed")

    def test_cold_start_then_idle_rebuild_counted(self):
        # session whose first turn only writes cache (read=0); the later
        # idle-gap rebuild must still be attributed.
        ev = self.seq(
            turn(self.B, read=0, creation=20000),
            turn(self.B.replace(minute=15), read=0, creation=20000),
        )
        self.assertEqual(len(ev), 1)
        self.assertEqual(ev[0]["cause"], "idle_gap")

    def test_unknown_model_not_counted_as_switch(self):
        ev = self.seq(
            turn(self.B, read=20000, creation=20000, model="<synthetic>"),
            turn(self.B.replace(minute=1), read=0, creation=20000,
                 model="claude-opus-4-8"),
        )
        self.assertEqual(ev[0]["cause"], "write_churn")


class TestContextTax(unittest.TestCase):
    B = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)

    def test_sprawl_session_flagged_lean_not(self):
        lean = {("/p", "lean"): [
            turn(self.B.replace(minute=m), session="lean", read=10000)
            for m in range(0, 10)
        ]}
        # many other lean sessions to set the baseline median ~10k
        sessions = dict(lean)
        for s in range(5):
            sessions[("/p", "b%d" % s)] = [
                turn(self.B.replace(minute=m), session="b%d" % s, read=10000)
                for m in range(0, 5)
            ]
        # one bloated session carrying ~300k/turn over many turns
        sessions[("/p", "sprawl")] = [
            turn(self.B.replace(hour=12 + (m // 6), minute=(m * 7) % 60),
                 session="sprawl", read=300000)
            for m in range(0, 30)
        ]
        tax = analyze.context_tax(sessions)
        top = {t["session"]: t for t in tax["top_sessions"]}
        self.assertIn("sprawl", top)
        self.assertGreater(top["sprawl"]["excess_usd"], 0)
        self.assertNotIn("lean", top)

    def test_single_session_no_false_positive(self):
        sessions = {("/p", "solo"): [
            turn(self.B.replace(minute=m), session="solo", read=200000)
            for m in range(0, 10)
        ]}
        tax = analyze.context_tax(sessions)
        self.assertEqual(tax["total_excess_usd"], 0)

    def test_single_session_asymmetric_reads_no_false_positive(self):
        # one session, varying per-turn reads — no baseline exists, so 0
        sessions = {("/p", "solo"): [
            turn(self.B.replace(minute=0), session="solo", read=100000),
            turn(self.B.replace(minute=1), session="solo", read=300000),
        ]}
        tax = analyze.context_tax(sessions)
        self.assertEqual(tax["total_excess_usd"], 0)


class TestCrossSession(unittest.TestCase):
    B = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)

    def sessions(self, spec):
        out = {}
        for (proj, sid, suffix), turns in spec.items():
            out[(proj, sid + suffix)] = turns
        return out

    def test_dead_session_reread_detected(self):
        prior = [turn(self.B.replace(minute=m), session="p", read=30000)
                 for m in range(0, 6)]
        restart = [turn(self.B.replace(hour=12, minute=30), session="q",
                        read=0, creation=30000)]
        s = self.sessions({("/p", "p", ""): prior, ("/p", "q", ""): restart})
        ev = analyze.attribute_cross_session(s)
        self.assertEqual(len(ev), 1)
        self.assertEqual(ev[0]["cause"], "dead_session")
        self.assertTrue(ev[0]["low_confidence"])

    def test_gap_beyond_window_ignored(self):
        prior = [turn(self.B.replace(minute=m), session="p", read=30000)
                 for m in range(0, 6)]
        restart = [turn(self.B.replace(hour=15), session="q",
                        read=0, creation=30000)]
        s = self.sessions({("/p", "p", ""): prior, ("/p", "q", ""): restart})
        self.assertEqual(analyze.attribute_cross_session(s), [])

    def test_different_project_ignored(self):
        prior = [turn(self.B.replace(minute=m), session="p", read=30000)
                 for m in range(0, 6)]
        restart = [turn(self.B.replace(hour=12, minute=30), session="q",
                        project="/other", read=0, creation=30000)]
        s = self.sessions({("/p", "p", ""): prior, ("/other", "q", ""): restart})
        self.assertEqual(analyze.attribute_cross_session(s), [])

    def test_concurrent_sessions_not_paired(self):
        a = [turn(self.B.replace(minute=m), session="a", read=30000)
             for m in range(0, 40, 5)]
        b = [turn(self.B.replace(minute=2), session="b", read=0, creation=30000)]
        s = self.sessions({("/p", "a", ""): a, ("/p", "b", ""): b})
        self.assertEqual(analyze.attribute_cross_session(s), [])

    def test_sidechain_excluded(self):
        prior = [turn(self.B.replace(minute=m), session="p", read=30000)
                 for m in range(0, 6)]
        side = [turn(self.B.replace(hour=12, minute=30), session="q",
                     sidechain=True, read=0, creation=30000)]
        s = self.sessions({("/p", "p", ""): prior, ("/p", "q", "::sidechain"): side})
        self.assertEqual(analyze.attribute_cross_session(s), [])


class TestRollup(unittest.TestCase):
    def test_invariant_sum_equals_missed_creation(self):
        events = [
            {"cause": "idle_gap", "tokens": 100, "usd": 1.0},
            {"cause": "write_churn", "tokens": 50, "usd": 0.5},
            {"cause": "unattributed", "tokens": 25, "usd": 0.2},
        ]
        roll = analyze.roll_up(events)
        self.assertEqual(roll["idle_gap"]["tokens"], 100)
        self.assertEqual(sum(c["tokens"] for c in roll.values()), 175)


class TestReport(unittest.TestCase):
    def test_full_schema_and_ranked_prescriptions(self):
        base = datetime(2026, 8, 24, 12, 0, tzinfo=timezone.utc)
        # session with an idle-gap rebuild miss
        entries = [
            entry(iso(base), session="s1", read=30000, creation=30000),
            entry(iso(base.replace(minute=20)), session="s1", read=0, creation=30000),
        ]
        with TmpClaude() as t:
            write_jsonl(t.d, "a.jsonl", entries)
            rep = analyze.run(t.d, days=3650, now=base.replace(minute=21))
        for key in ("meta", "stats", "totals", "miss_attribution",
                    "dead_session", "context_tax", "top_offenders",
                    "prescriptions", "flags"):
            self.assertIn(key, rep)
        self.assertEqual(rep["meta"]["pricing_asof"], analyze.PRICING_ASOF)
        self.assertIn("idle_gap", rep["miss_attribution"]["causes"])
        usds = [p["usd"] for p in rep["prescriptions"]]
        self.assertEqual(usds, sorted(usds, reverse=True))

    def test_runs_on_empty_dir(self):
        with TmpClaude() as t:
            os.makedirs(os.path.join(t.d, "projects"))
            rep = analyze.run(t.d, days=30)
        self.assertEqual(rep["stats"]["turns"], 0)
        self.assertEqual(rep["prescriptions"], [])


if __name__ == "__main__":
    unittest.main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall