claude-cache-analyzer 0.1.0__tar.gz

claude_cache_analyzer-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: claude-cache-analyzer
+Version: 0.1.0
+Summary: Analyze Claude Code session cache efficiency
+Author-email: Eugene Smith <easmith@mail.ru>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AgiMateIo/claude-cache-analyzer
+Project-URL: Repository, https://github.com/AgiMateIo/claude-cache-analyzer
+Project-URL: Issues, https://github.com/AgiMateIo/claude-cache-analyzer/issues
+Keywords: claude,cache,anthropic,cli,prompt-caching
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+
+# Claude Code Cache Efficiency Analyzer
+
+Based on https://habr.com/ru/companies/bitrix/articles/1008320/
+
+It helps to analyze you Claude Agent SDK usage.
+
+CLI tool that reads Claude Code JSONL session files, computes prompt cache efficiency metrics using the Bitrix24/Habr formula, and displays results as rich terminal tables.
+
+## Formula
+
+```
+C = S × [(1−h) × P_miss + h × P_hit] + D × P_miss + O × P_out
+```
+
+Where: **S** = cacheable tokens, **h** = hit rate, **D** = dynamic input tokens, **O** = output tokens.
+
+## Install
+
+```bash
+uv sync
+```
+
+## Usage
+
+```bash
+# Analyze all sessions in ~/.claude
+uv run python cli.py
+
+# Last 5 sessions
+uv run python cli.py --top 5
+
+# Specific project
+uv run python cli.py --project-name my-project
+
+# Export metrics to JSON
+uv run python cli.py --export-json metrics.json
+
+# Analyze a specific path
+uv run python cli.py ~/.claude/projects/abc123
+```
+
+## Metrics
+
+| Metric | Description |
+|--------|-------------|
+| Cache hit rate | `cache_read / (cache_creation + cache_read)` |
+| Actual cost | Real cost with cache pricing applied |
+| Cost without cache | Hypothetical cost if all tokens were at input price |
+| Savings | `cost_no_cache - actual_cost` |
+| Net savings | Savings minus cache write overhead |
+| Efficiency score | `hit_rate × (cacheable / (input + cacheable))` — range [0..1] |
+
+## Grades
+
+| Grade | Efficiency Score |
+|-------|-----------------|
+| **A** | ≥ 0.70 |
+| **B** | ≥ 0.50 |
+| **C** | ≥ 0.30 |
+| **D** | ≥ 0.10 |
+| **F** | < 0.10 |
+
+## Tests
+
+```bash
+uv run pytest -v
+```

claude_cache_analyzer-0.1.0/README.md

@@ -0,0 +1,67 @@
+# Claude Code Cache Efficiency Analyzer
+
+Based on https://habr.com/ru/companies/bitrix/articles/1008320/
+
+It helps to analyze you Claude Agent SDK usage.
+
+CLI tool that reads Claude Code JSONL session files, computes prompt cache efficiency metrics using the Bitrix24/Habr formula, and displays results as rich terminal tables.
+
+## Formula
+
+```
+C = S × [(1−h) × P_miss + h × P_hit] + D × P_miss + O × P_out
+```
+
+Where: **S** = cacheable tokens, **h** = hit rate, **D** = dynamic input tokens, **O** = output tokens.
+
+## Install
+
+```bash
+uv sync
+```
+
+## Usage
+
+```bash
+# Analyze all sessions in ~/.claude
+uv run python cli.py
+
+# Last 5 sessions
+uv run python cli.py --top 5
+
+# Specific project
+uv run python cli.py --project-name my-project
+
+# Export metrics to JSON
+uv run python cli.py --export-json metrics.json
+
+# Analyze a specific path
+uv run python cli.py ~/.claude/projects/abc123
+```
+
+## Metrics
+
+| Metric | Description |
+|--------|-------------|
+| Cache hit rate | `cache_read / (cache_creation + cache_read)` |
+| Actual cost | Real cost with cache pricing applied |
+| Cost without cache | Hypothetical cost if all tokens were at input price |
+| Savings | `cost_no_cache - actual_cost` |
+| Net savings | Savings minus cache write overhead |
+| Efficiency score | `hit_rate × (cacheable / (input + cacheable))` — range [0..1] |
+
+## Grades
+
+| Grade | Efficiency Score |
+|-------|-----------------|
+| **A** | ≥ 0.70 |
+| **B** | ≥ 0.50 |
+| **C** | ≥ 0.30 |
+| **D** | ≥ 0.10 |
+| **F** | < 0.10 |
+
+## Tests
+
+```bash
+uv run pytest -v
+```

claude_cache_analyzer-0.1.0/claude_cache_analyzer/__init__.py

@@ -0,0 +1,3 @@
+"""Claude Code Cache Efficiency Analyzer."""
+
+__version__ = "0.1.0"

claude_cache_analyzer-0.1.0/claude_cache_analyzer/cli.py

@@ -0,0 +1,219 @@
+"""CLI entry point for Claude Code Cache Efficiency Analyzer."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from claude_cache_analyzer import __version__
+from claude_cache_analyzer.metrics import aggregate, compute_session_metrics
+from claude_cache_analyzer.parser import discover_sessions, find_session_by_id, parse_session_file
+from claude_cache_analyzer.report import (
+    print_grouped_report,
+    print_no_sessions_message,
+    print_project_report,
+    print_session_detail,
+)
+
+app = typer.Typer(
+    help="Analyze Claude Code session cache efficiency.",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+console = Console()
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        console.print(f"claude-cache-analyzer {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def main(
+    project_path: Optional[Path] = typer.Argument(
+        None,
+        help="Root of Claude data (~/.claude) or a specific project directory.",
+    ),
+    project_name: Optional[str] = typer.Option(
+        None, "--project-name", "-p", help="Filter by project directory name."
+    ),
+    top: Optional[int] = typer.Option(
+        None, "--top", "-n", help="Show only the N most recent sessions."
+    ),
+    min_turns: int = typer.Option(
+        1, "--min-turns", help="Minimum number of turns to include a session."
+    ),
+    session: Optional[str] = typer.Option(
+        None, "--session", "-s", help="Show detailed view for a specific session (full or partial ID)."
+    ),
+    group_by_project: bool = typer.Option(
+        False, "--group-by-project", "-g", help="Group results by project."
+    ),
+    export_json: Optional[Path] = typer.Option(
+        None, "--export-json", help="Export raw metrics to a JSON file."
+    ),
+    version: Optional[bool] = typer.Option(
+        None, "--version", callback=version_callback, is_eager=True, help="Show version."
+    ),
+) -> None:
+    """Analyze Claude Code prompt cache efficiency."""
+    if project_path is None:
+        project_path = Path.home() / ".claude"
+
+    project_path = project_path.expanduser().resolve()
+
+    # Determine if path points to a specific project or the root
+    if (project_path / "projects").is_dir():
+        # Root claude dir
+        sessions = discover_sessions(project_path)
+    elif project_path.is_dir():
+        # Might be a specific project directory — look for JSONL files directly
+        jsonl_files = list(project_path.glob("*.jsonl"))
+        if jsonl_files:
+            sessions = []
+            for f in jsonl_files:
+                s = parse_session_file(f)
+                if s.turns:
+                    sessions.append(s)
+            sessions.sort(
+                key=lambda s: s.started_at or datetime.min, reverse=True
+            )
+        else:
+            # Maybe it's a projects/ parent
+            sessions = discover_sessions(project_path)
+    else:
+        console.print(f"[red]Path does not exist: {project_path}[/red]")
+        raise typer.Exit(1)
+
+    if not sessions:
+        print_no_sessions_message()
+        raise typer.Exit()
+
+    # Session detail mode
+    if session:
+        match, candidates = find_session_by_id(sessions, session)
+        if match is None and not candidates:
+            console.print(f"[red]No session found matching '{session}'[/red]")
+            raise typer.Exit(1)
+        if match is None:
+            console.print(f"[yellow]Ambiguous session ID '{session}'. Candidates:[/yellow]")
+            for c in candidates:
+                date_str = c.started_at.strftime("%Y-%m-%d %H:%M") if c.started_at else "—"
+                console.print(f"  {c.session_id}  ({date_str}, {c.num_turns} turns)")
+            raise typer.Exit(1)
+
+        sm = compute_session_metrics(match)
+        print_session_detail(sm)
+
+        if export_json:
+            export_data = {
+                "session_id": match.session_id,
+                "project": match.project,
+                "model": match.model,
+                "started_at": match.started_at.isoformat() if match.started_at else None,
+                "num_turns": match.num_turns,
+                "hit_rate": sm.hit_rate,
+                "efficiency_score": sm.cache_efficiency_score,
+                "grade": sm.grade(),
+                "actual_cost": sm.actual_cost,
+                "cost_no_cache": sm.cost_no_cache,
+                "savings": sm.savings,
+                "net_savings": sm.net_savings,
+                "savings_pct": sm.savings_pct,
+                "turns": [
+                    {
+                        "timestamp": tm.turn.timestamp.isoformat() if tm.turn.timestamp else None,
+                        "model": tm.turn.model,
+                        "input_tokens": tm.turn.input_tokens,
+                        "output_tokens": tm.turn.output_tokens,
+                        "cache_creation_tokens": tm.turn.cache_creation_tokens,
+                        "cache_read_tokens": tm.turn.cache_read_tokens,
+                        "hit_rate": tm.turn.hit_rate,
+                        "actual_cost": tm.actual_cost,
+                        "cost_no_cache": tm.cost_no_cache,
+                        "savings": tm.savings,
+                        "savings_pct": tm.savings_pct,
+                    }
+                    for tm in sm.turns
+                ],
+            }
+            export_json.write_text(json.dumps(export_data, indent=2))
+            console.print(f"\n[green]Metrics exported to {export_json}[/green]")
+        raise typer.Exit()
+
+    # Filter by project name
+    if project_name:
+        sessions = [s for s in sessions if project_name in s.project]
+
+    # Filter by min turns
+    sessions = [s for s in sessions if s.num_turns >= min_turns]
+
+    if not sessions:
+        print_no_sessions_message()
+        raise typer.Exit()
+
+    # Limit to top N
+    if top is not None:
+        sessions = sessions[:top]
+
+    # Compute metrics
+    sessions_metrics = [compute_session_metrics(s) for s in sessions]
+
+    # Print report
+    if group_by_project:
+        print_grouped_report(sessions_metrics)
+    else:
+        display_name = project_name or (
+            sessions[0].project
+            if len(set(s.project for s in sessions)) == 1
+            else "all projects"
+        )
+        print_project_report(sessions_metrics, display_name)
+
+    # Export JSON
+    if export_json:
+        agg = aggregate(sessions_metrics)
+        export_data = {
+            "aggregate": {
+                k: v
+                for k, v in agg.items()
+                if k not in ("best_session", "worst_session")
+            },
+            "sessions": [],
+        }
+        for sm in sessions_metrics:
+            sess = sm.session
+            export_data["sessions"].append(
+                {
+                    "session_id": sess.session_id,
+                    "project": sess.project,
+                    "model": sess.model,
+                    "started_at": (
+                        sess.started_at.isoformat() if sess.started_at else None
+                    ),
+                    "num_turns": sess.num_turns,
+                    "total_input": sess.total_input,
+                    "total_output": sess.total_output,
+                    "total_cacheable": sess.total_cacheable,
+                    "hit_rate": sm.hit_rate,
+                    "efficiency_score": sm.cache_efficiency_score,
+                    "grade": sm.grade(),
+                    "actual_cost": sm.actual_cost,
+                    "cost_no_cache": sm.cost_no_cache,
+                    "savings": sm.savings,
+                    "net_savings": sm.net_savings,
+                    "savings_pct": sm.savings_pct,
+                }
+            )
+        export_json.write_text(json.dumps(export_data, indent=2))
+        console.print(f"\n[green]Metrics exported to {export_json}[/green]")
+
+
+if __name__ == "__main__":
+    app()

claude_cache_analyzer-0.1.0/claude_cache_analyzer/metrics.py

@@ -0,0 +1,163 @@
+"""Compute cost metrics and efficiency scores for sessions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .parser import Session, TurnUsage
+from .pricing import cost_per_token, get_pricing
+
+
+@dataclass
+class TurnMetrics:
+    turn: TurnUsage
+    actual_cost: float
+    cost_no_cache: float
+    cache_write_overhead: float
+
+    @property
+    def savings(self) -> float:
+        return self.cost_no_cache - self.actual_cost
+
+    @property
+    def net_savings(self) -> float:
+        return self.savings - self.cache_write_overhead
+
+    @property
+    def savings_pct(self) -> float:
+        if self.cost_no_cache == 0:
+            return 0.0
+        return self.savings / self.cost_no_cache * 100
+
+
+@dataclass
+class SessionMetrics:
+    session: Session
+    turns: list[TurnMetrics] = field(default_factory=list)
+
+    @property
+    def actual_cost(self) -> float:
+        return sum(t.actual_cost for t in self.turns)
+
+    @property
+    def cost_no_cache(self) -> float:
+        return sum(t.cost_no_cache for t in self.turns)
+
+    @property
+    def cache_write_overhead(self) -> float:
+        return sum(t.cache_write_overhead for t in self.turns)
+
+    @property
+    def savings(self) -> float:
+        return self.cost_no_cache - self.actual_cost
+
+    @property
+    def net_savings(self) -> float:
+        return self.savings - self.cache_write_overhead
+
+    @property
+    def savings_pct(self) -> float:
+        if self.cost_no_cache == 0:
+            return 0.0
+        return self.savings / self.cost_no_cache * 100
+
+    @property
+    def hit_rate(self) -> float:
+        return self.session.hit_rate
+
+    @property
+    def cache_efficiency_score(self) -> float:
+        total_input = self.session.total_input
+        total_cacheable = self.session.total_cacheable
+        denom = total_input + total_cacheable
+        if denom == 0:
+            return 0.0
+        return self.hit_rate * (total_cacheable / denom)
+
+    def grade(self) -> str:
+        score = self.cache_efficiency_score
+        if score >= 0.70:
+            return "A"
+        if score >= 0.50:
+            return "B"
+        if score >= 0.30:
+            return "C"
+        if score >= 0.10:
+            return "D"
+        return "F"
+
+
+def _compute_turn_metrics(turn: TurnUsage) -> TurnMetrics:
+    pricing = get_pricing(turn.model)
+    ppt = cost_per_token(pricing)
+
+    s = turn.cacheable_tokens
+    h = turn.hit_rate
+    d = turn.input_tokens
+    o = turn.output_tokens
+
+    # Actual cost: C = S * [(1-h)*P_miss + h*P_hit] + D*P_miss + O*P_out
+    # But actual_cost should reflect what was actually charged, including cache_write pricing
+    # cache_creation tokens are charged at cache_write rate, cache_read at cache_read rate,
+    # input_tokens at input rate, output at output rate
+    actual_cost = (
+        turn.cache_creation_tokens * ppt["cache_write"]
+        + turn.cache_read_tokens * ppt["cache_read"]
+        + d * ppt["input"]
+        + o * ppt["output"]
+    )
+
+    # Baseline without cache: all input tokens at normal input price
+    cost_no_cache = (s + d) * ppt["input"] + o * ppt["output"]
+
+    # Overhead: cache_write is more expensive than regular input
+    cache_write_overhead = turn.cache_creation_tokens * (ppt["cache_write"] - ppt["input"])
+
+    return TurnMetrics(
+        turn=turn,
+        actual_cost=actual_cost,
+        cost_no_cache=cost_no_cache,
+        cache_write_overhead=cache_write_overhead,
+    )
+
+
+def compute_session_metrics(session: Session) -> SessionMetrics:
+    turn_metrics = [_compute_turn_metrics(t) for t in session.turns]
+    return SessionMetrics(session=session, turns=turn_metrics)
+
+
+def aggregate(sessions_metrics: list[SessionMetrics]) -> dict:
+    """Compute aggregate statistics across all sessions."""
+    if not sessions_metrics:
+        return {
+            "total_actual_cost": 0.0,
+            "total_cost_no_cache": 0.0,
+            "total_savings": 0.0,
+            "total_net_savings": 0.0,
+            "avg_hit_rate": 0.0,
+            "avg_efficiency_score": 0.0,
+            "best_session": None,
+            "worst_session": None,
+        }
+
+    total_actual = sum(sm.actual_cost for sm in sessions_metrics)
+    total_no_cache = sum(sm.cost_no_cache for sm in sessions_metrics)
+    total_savings = total_no_cache - total_actual
+    total_overhead = sum(sm.cache_write_overhead for sm in sessions_metrics)
+    total_net = total_savings - total_overhead
+    avg_hit = sum(sm.hit_rate for sm in sessions_metrics) / len(sessions_metrics)
+    avg_eff = sum(sm.cache_efficiency_score for sm in sessions_metrics) / len(sessions_metrics)
+
+    best = max(sessions_metrics, key=lambda s: s.cache_efficiency_score)
+    worst = min(sessions_metrics, key=lambda s: s.cache_efficiency_score)
+
+    return {
+        "total_actual_cost": total_actual,
+        "total_cost_no_cache": total_no_cache,
+        "total_savings": total_savings,
+        "total_net_savings": total_net,
+        "avg_hit_rate": avg_hit,
+        "avg_efficiency_score": avg_eff,
+        "best_session": best,
+        "worst_session": worst,
+    }