codex-stats 1.9.0__tar.gz → 1.11.2__tar.gz

{codex_stats-1.9.0/src/codex_stats.egg-info → codex_stats-1.11.2}/PKG-INFO

@@ -1,22 +1,27 @@
 Metadata-Version: 2.4
 Name: codex-stats
-Version: 1.9.0
-Summary: Local AI usage observability dashboard for coding agent sessions.
+Version: 1.11.2
+Summary: Local-first usage dashboard and leaderboard for AI coding agent sessions: tokens, cost and activity across Codex, OpenCode, Claude Code and Hermes, read straight from the databases those tools already keep on your machine.
 Author: Vivek
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/vivek378521/codex-stats
 Project-URL: Repository, https://github.com/vivek378521/codex-stats
 Project-URL: Issues, https://github.com/vivek378521/codex-stats/issues
-Keywords: codex,cli,analytics,sqlite,usage
+Project-URL: Changelog, https://github.com/vivek378521/codex-stats/blob/main/CHANGELOG.md
+Project-URL: Leaderboard, https://codex-stats-leaderboard.vercel.app
+Project-URL: Funding, https://github.com/sponsors/vivek378521
+Keywords: ai,analytics,claude,cli,codex,cost,dashboard,developer-tools,hermes,leaderboard,local-first,metrics,observability,opencode,privacy,reporting,sqlite,terminal,tokens,usage
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -39,6 +44,7 @@ It reads local session data from every coding assistant installed on the machine
 - per-tool cost overrides and a stacked per-tool token trend on the Overview
 - anomaly-aware usage insights and recommendations
 - file-level impact tracking: a "Most Edited Files" panel showing per-file edit counts and add/delete line totals parsed from Codex and Claude Code rollouts
+- **tool behavior tracking**: a "Tool Behavior" panel showing the tools each agent actually called — normalized into shared categories (Read, Edit, Execute, Search, Web, Subagent, Plan), with per-tool failure rates, repeated-call detection, read/write ratio, and abandoned-turn counts, across every tool with recorded calls
 - shareable JPG cards and browser PDF export from the dashboard
 
 ## Data Sources

{codex_stats-1.9.0 → codex_stats-1.11.2}/README.md

@@ -12,6 +12,7 @@ It reads local session data from every coding assistant installed on the machine
 - per-tool cost overrides and a stacked per-tool token trend on the Overview
 - anomaly-aware usage insights and recommendations
 - file-level impact tracking: a "Most Edited Files" panel showing per-file edit counts and add/delete line totals parsed from Codex and Claude Code rollouts
+- **tool behavior tracking**: a "Tool Behavior" panel showing the tools each agent actually called — normalized into shared categories (Read, Edit, Execute, Search, Web, Subagent, Plan), with per-tool failure rates, repeated-call detection, read/write ratio, and abandoned-turn counts, across every tool with recorded calls
 - shareable JPG cards and browser PDF export from the dashboard
 
 ## Data Sources

codex_stats-1.11.2/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codex-stats"
+version = "1.11.2"
+description = "Local-first usage dashboard and leaderboard for AI coding agent sessions: tokens, cost and activity across Codex, OpenCode, Claude Code and Hermes, read straight from the databases those tools already keep on your machine."
+readme = "README.md"
+requires-python = ">=3.11"
+# SPDX form (PEP 639). The License classifier is deliberately absent: setuptools
+# rejects having both, and the old license = { text = ... } table is deprecated.
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Vivek" }
+]
+keywords = [
+  "ai",
+  "analytics",
+  "claude",
+  "cli",
+  "codex",
+  "cost",
+  "dashboard",
+  "developer-tools",
+  "hermes",
+  "leaderboard",
+  "local-first",
+  "metrics",
+  "observability",
+  "opencode",
+  "privacy",
+  "reporting",
+  "sqlite",
+  "terminal",
+  "tokens",
+  "usage",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Monitoring",
+  "Topic :: Utilities",
+]
+# "Typing :: Typed" is deliberately absent: it promises an inline py.typed
+# marker, and the package does not ship one. Add both together if that changes.
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+]
+
+[project.scripts]
+codex-stats = "codex_stats.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/vivek378521/codex-stats"
+Repository = "https://github.com/vivek378521/codex-stats"
+Issues = "https://github.com/vivek378521/codex-stats/issues"
+Changelog = "https://github.com/vivek378521/codex-stats/blob/main/CHANGELOG.md"
+Leaderboard = "https://codex-stats-leaderboard.vercel.app"
+Funding = "https://github.com/sponsors/vivek378521"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

{codex_stats-1.9.0 → codex_stats-1.11.2}/src/codex_stats/cli.py

@@ -8,10 +8,12 @@ from pathlib import Path
 
 from .config import Paths, PricingConfig, load_pricing_config
 from .display import format_dashboard_html
+from .leaderboard import LeaderboardConfig, LeaderboardSubmitServer
 from .metrics import (
     local_date,
     summarize_activity_heatmap_from_details,
     summarize_badges,
+    summarize_behavior_from_details,
     summarize_compare_from_details,
     summarize_costs_from_details,
     summarize_daily_from_details,
@@ -49,13 +51,45 @@ def main(argv: list[str] | None = None) -> int:
     paths = Paths.discover()
 
     dashboard = _build_dashboard(paths)
-    output_path = _write_dashboard_output(format_dashboard_html(dashboard))
+    submit_server = _start_leaderboard(dashboard)
+    output_path = _write_dashboard_output(
+        format_dashboard_html(dashboard, leaderboard=_leaderboard_preview(submit_server))
+    )
     print(f"Wrote dashboard to {output_path}")
     _open_report_in_browser(output_path)
     print(f"Opened dashboard in browser: {output_path}")
+    if submit_server is None:
+        return 0
+    print("Leaderboard enabled: use Submit to Leaderboard in the dashboard. Press Ctrl+C to stop.")
+    try:
+        submit_server.wait()
+    except KeyboardInterrupt:
+        print("\nLeaderboard submit endpoint stopped.")
+    finally:
+        submit_server.close()
     return 0
 
 
+def _start_leaderboard(dashboard: DashboardData) -> LeaderboardSubmitServer | None:
+    """Bring up the loopback submit endpoint when the leaderboard is configured.
+
+    Binding here, before the dashboard is rendered, is what lets the generated
+    HTML carry a URL that is already live.
+    """
+    config = LeaderboardConfig.from_env()
+    if config is None:
+        return None
+    server = LeaderboardSubmitServer(config, dashboard)
+    server.start()
+    return server
+
+
+def _leaderboard_preview(server: LeaderboardSubmitServer | None) -> dict[str, object] | None:
+    if server is None:
+        return None
+    return server.preview()
+
+
 def _build_dashboard(paths: Paths, now: datetime | None = None) -> DashboardData:
     current_time = now or datetime.now().astimezone()
     pricing = load_pricing_config(paths)
@@ -197,6 +231,7 @@ def _build_window(
     daily_points = summarize_daily_from_details(current_details, days=max(trend_days, 1), now=now, pricing=pricing)
     activity_heatmap = summarize_activity_heatmap_from_details(current_details, timezone=now.tzinfo)
     file_impact = summarize_files_from_details(current_details, limit=10)
+    behavior = summarize_behavior_from_details(current_details)
     return DashboardWindow(
         key=key,
         label=label,
@@ -211,7 +246,14 @@ def _build_window(
         costs=costs,
         insights=insights,
         activity_heatmap=activity_heatmap,
-        takeaways=summarize_takeaways(summary=summary, comparison=comparison, costs=costs, insights=insights, file_impact=file_impact),
+        takeaways=summarize_takeaways(
+            summary=summary,
+            comparison=comparison,
+            costs=costs,
+            insights=insights,
+            file_impact=file_impact,
+            behavior=behavior,
+        ),
         badges=summarize_badges(summary=summary, daily_points=daily_points, activity_heatmap=activity_heatmap),
         expensive_session=summarize_expensive_session(current_details, pricing),
         work_rhythm=summarize_work_rhythm(daily_points, activity_heatmap),
@@ -223,6 +265,7 @@ def _build_window(
             limit=5,
         ),
         file_impact=file_impact,
+        behavior=behavior,
         tool_breakdown=(
             summarize_source_breakdown_from_details(current_details, pricing)
             if build_tool_breakdown
@@ -265,6 +308,7 @@ def _build_all_time_window(
     daily_points = summarize_daily_from_details(trend_details, days=trend_days, now=now, pricing=pricing)
     activity_heatmap = summarize_activity_heatmap_from_details(all_details, timezone=now.tzinfo)
     file_impact = summarize_files_from_details(all_details, limit=10)
+    behavior = summarize_behavior_from_details(all_details)
     return DashboardWindow(
         key="all",
         label="All Time",
@@ -285,6 +329,7 @@ def _build_all_time_window(
             costs=costs,
             insights=insights,
             file_impact=file_impact,
+            behavior=behavior,
         ),
         badges=summarize_badges(summary=summary, daily_points=daily_points, activity_heatmap=activity_heatmap),
         expensive_session=summarize_expensive_session(all_details, pricing),
@@ -297,6 +342,7 @@ def _build_all_time_window(
             limit=5,
         ),
         file_impact=file_impact,
+        behavior=behavior,
         tool_breakdown=(
             summarize_source_breakdown_from_details(all_details, pricing)
             if build_tool_breakdown

{codex_stats-1.9.0 → codex_stats-1.11.2}/src/codex_stats/display.py

@@ -4,6 +4,7 @@ import json
 import textwrap
 from collections import defaultdict
 from html import escape
+from typing import Any
 
 from .models import DashboardData, DashboardWindow, HeatmapCell, ProjectDrilldown
 from .sources import source_label
@@ -16,7 +17,7 @@ SOURCE_CHART_COLORS: dict[str, str] = {
 }
 
 
-def format_dashboard_html(dashboard: DashboardData) -> str:
+def format_dashboard_html(dashboard: DashboardData, *, leaderboard: dict[str, Any] | None = None) -> str:
     generated_at = dashboard.generated_at.strftime("%Y-%m-%d %H:%M %Z")
     scopes = list(dashboard.scopes)
     windows = list(dashboard.windows)
@@ -66,6 +67,16 @@ def format_dashboard_html(dashboard: DashboardData) -> str:
         },
         separators=(",", ":"),
     )
+    leaderboard_json = "null"
+    leaderboard_button = ""
+    leaderboard_dialog = ""
+    if leaderboard:
+        leaderboard_json = json.dumps(leaderboard, separators=(",", ":"))
+        leaderboard_button = (
+            '<button class="action-button" type="button" data-action="submit-leaderboard">'
+            "Submit to Leaderboard</button>"
+        )
+        leaderboard_dialog = _format_leaderboard_dialog()
     return f"""<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -450,6 +461,13 @@ def format_dashboard_html(dashboard: DashboardData) -> str:
       font-size: 0.92rem;
       line-height: 1.45;
     }}
+    .panel-hint {{
+      display: block;
+      margin: 16px 0 0;
+      color: var(--muted);
+      font-size: 0.86rem;
+      line-height: 1.5;
+    }}
     .split {{
       display: grid;
       grid-template-columns: repeat(2, minmax(0, 1fr));
@@ -776,6 +794,83 @@ def format_dashboard_html(dashboard: DashboardData) -> str:
       .window.is-active {{
         display: block !important;
       }}
+      dialog {{
+        display: none !important;
+      }}
+    }}
+    .leaderboard-dialog {{
+      width: min(460px, calc(100vw - 32px));
+      padding: 0;
+      border: 1px solid var(--line);
+      border-radius: 24px;
+      background: var(--panel-strong);
+      color: var(--ink);
+      box-shadow: 0 30px 80px rgba(75, 56, 40, 0.28);
+    }}
+    .leaderboard-dialog::backdrop {{
+      background: rgba(31, 26, 23, 0.42);
+    }}
+    .leaderboard-form {{
+      display: flex;
+      flex-direction: column;
+      gap: 10px;
+      padding: 26px 28px 22px;
+    }}
+    .leaderboard-form h2 {{
+      margin: 0;
+      font-size: 22px;
+    }}
+    .leaderboard-note {{
+      margin: 0 0 4px;
+      color: var(--muted);
+      font-size: 14px;
+      line-height: 1.5;
+    }}
+    .leaderboard-label {{
+      font-size: 12px;
+      letter-spacing: 0.1em;
+      text-transform: uppercase;
+      color: var(--muted);
+      font-weight: 700;
+    }}
+    .leaderboard-input {{
+      width: 100%;
+      padding: 12px 14px;
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      background: #fff;
+      color: var(--ink);
+      font: inherit;
+    }}
+    .leaderboard-input:focus {{
+      outline: 2px solid var(--accent);
+      outline-offset: 1px;
+    }}
+    .leaderboard-preview {{
+      margin: 0;
+      padding: 12px 14px;
+      border-radius: 14px;
+      background: rgba(15, 118, 110, 0.08);
+      color: var(--ink);
+      font-size: 14px;
+      line-height: 1.5;
+    }}
+    .leaderboard-error {{
+      margin: 0;
+      color: #9f1239;
+      font-size: 14px;
+    }}
+    .leaderboard-status {{
+      margin: 0;
+      color: var(--accent);
+      font-size: 14px;
+      font-weight: 700;
+    }}
+    .leaderboard-actions {{
+      display: flex;
+      gap: 10px;
+      justify-content: flex-end;
+      margin-top: 6px;
     }}
   </style>
 </head>
@@ -801,6 +896,7 @@ def format_dashboard_html(dashboard: DashboardData) -> str:
         <div class="actions">
           <button class="action-button" type="button" data-action="copy-summary">Copy Summary</button>
           <span class="copy-feedback" data-copy-feedback></span>
+          {leaderboard_button}
           <div class="export-wrap">
             <button class="action-button primary" type="button" data-action="toggle-export">Export</button>
             <div class="export-menu" data-export-menu>
@@ -842,6 +938,7 @@ def format_dashboard_html(dashboard: DashboardData) -> str:
     {scope_sections}
     <div class="footer">Generated by codex-stats</div>
   </main>
+  {leaderboard_dialog}
   <script>
     const dashboardAssets = {assets_json};
     const dashboardSummaries = {summaries_json};
@@ -1201,6 +1298,103 @@ def format_dashboard_html(dashboard: DashboardData) -> str:
         exportMenu?.classList.remove("is-open");
       }}
     }});
+    const leaderboardConfig = {leaderboard_json};
+    const leaderboardDialog = document.querySelector("[data-leaderboard-dialog]");
+    if (leaderboardConfig && leaderboardDialog) {{
+      const leaderboardInput = leaderboardDialog.querySelector("[data-leaderboard-username]");
+      const leaderboardError = leaderboardDialog.querySelector("[data-leaderboard-error]");
+      const leaderboardStatus = leaderboardDialog.querySelector("[data-leaderboard-status]");
+      const leaderboardPreview = leaderboardDialog.querySelector("[data-leaderboard-preview]");
+      const leaderboardConfirm = leaderboardDialog.querySelector("[data-leaderboard-confirm]");
+      const leaderboardFormatter = new Intl.NumberFormat("en-US");
+
+      function formatLeaderboardCount(value) {{
+        const count = Number(value) || 0;
+        if (count >= 1000000000) {{
+          return `${{(count / 1000000000).toFixed(2)}}B`;
+        }}
+        if (count >= 1000000) {{
+          return `${{(count / 1000000).toFixed(2)}}M`;
+        }}
+        if (count >= 1000) {{
+          return `${{(count / 1000).toFixed(1)}}K`;
+        }}
+        return leaderboardFormatter.format(count);
+      }}
+
+      function setLeaderboardMessage(node, message) {{
+        node.textContent = message;
+        node.hidden = !message;
+      }}
+
+      function renderLeaderboardPreview() {{
+        const parts = (leaderboardConfig.clis ?? []).map(
+          (item) => `${{item.label}} ${{formatLeaderboardCount(item.tokens)}}`
+        );
+        leaderboardPreview.textContent = parts.length
+          ? `Sending ${{formatLeaderboardCount(leaderboardConfig.totalTokens)}} tokens across ${{parts.join(", ")}}`
+          : "No CLI usage has been recorded on this machine yet.";
+      }}
+
+      async function submitToLeaderboard() {{
+        const username = leaderboardInput.value.trim();
+        if (!/^[A-Za-z0-9_-]{{1,20}}$/.test(username)) {{
+          setLeaderboardMessage(leaderboardError, "Use 1-20 characters: letters, numbers, _ or -.");
+          return;
+        }}
+        setLeaderboardMessage(leaderboardError, "");
+        setLeaderboardMessage(leaderboardStatus, "");
+        leaderboardConfirm.disabled = true;
+        leaderboardConfirm.textContent = "Submitting…";
+        try {{
+          // Only the username is sent. Totals are read from local data by codex-stats.
+          // text/plain keeps this a CORS-simple request, so there is no preflight.
+          const response = await fetch(leaderboardConfig.submitUrl, {{
+            method: "POST",
+            headers: {{ "Content-Type": "text/plain" }},
+            body: JSON.stringify({{ username }}),
+          }});
+          const payload = await response.json();
+          if (!response.ok || !payload.ok) {{
+            throw new Error(payload.error || `Request failed with ${{response.status}}`);
+          }}
+          setLeaderboardMessage(
+            leaderboardStatus,
+            `${{payload.updated}} You are #${{payload.rank}} with ${{formatLeaderboardCount(payload.totalTokens)}} tokens.`
+          );
+          leaderboardInput.disabled = true;
+          leaderboardConfirm.textContent = "Submitted";
+        }} catch (error) {{
+          setLeaderboardMessage(leaderboardError, error.message);
+          leaderboardConfirm.disabled = false;
+          leaderboardConfirm.textContent = "Submit";
+        }}
+      }}
+
+      document.querySelector('[data-action="submit-leaderboard"]')?.addEventListener("click", () => {{
+        renderLeaderboardPreview();
+        setLeaderboardMessage(leaderboardError, "");
+        setLeaderboardMessage(leaderboardStatus, "");
+        leaderboardDialog.showModal();
+        leaderboardInput.focus();
+        leaderboardInput.select();
+      }});
+      leaderboardDialog.querySelector("[data-leaderboard-cancel]")?.addEventListener("click", () => {{
+        leaderboardDialog.close();
+      }});
+      leaderboardConfirm?.addEventListener("click", submitToLeaderboard);
+      leaderboardInput?.addEventListener("keydown", (event) => {{
+        if (event.key === "Enter") {{
+          event.preventDefault();
+          submitToLeaderboard();
+        }}
+      }});
+      leaderboardDialog.addEventListener("close", () => {{
+        leaderboardInput.disabled = false;
+        leaderboardConfirm.disabled = false;
+        leaderboardConfirm.textContent = "Submit";
+      }});
+    }}
     reflectActive();
   </script>
 </body>
@@ -1208,6 +1402,26 @@ def format_dashboard_html(dashboard: DashboardData) -> str:
 """
 
 
+def _format_leaderboard_dialog() -> str:
+    return """  <dialog class="leaderboard-dialog" data-leaderboard-dialog>
+    <form method="dialog" class="leaderboard-form">
+      <h2>Submit to the leaderboard</h2>
+      <p class="leaderboard-note">Pick a public name. Submitting again from this machine updates your existing record.</p>
+      <label class="leaderboard-label" for="leaderboard-username">Username</label>
+      <input class="leaderboard-input" id="leaderboard-username" name="username" type="text" maxlength="20"
+             pattern="[A-Za-z0-9_-]{1,20}" autocomplete="off" spellcheck="false" placeholder="ada_lovelace"
+             data-leaderboard-username>
+      <p class="leaderboard-preview" data-leaderboard-preview></p>
+      <p class="leaderboard-error" data-leaderboard-error hidden></p>
+      <p class="leaderboard-status" data-leaderboard-status hidden></p>
+      <div class="leaderboard-actions">
+        <button class="action-button" type="button" data-leaderboard-cancel>Cancel</button>
+        <button class="action-button primary" type="button" data-leaderboard-confirm>Submit</button>
+      </div>
+    </form>
+  </dialog>"""
+
+
 def format_dashboard_svg_assets(window: DashboardWindow, *, scope_label: str = "Codex") -> dict[str, str]:
     title = f"{scope_label} Stats {window.label}"
     return {
@@ -1430,6 +1644,8 @@ def _format_dashboard_window_section(
 
         {_format_file_impact_panel(window)}
 
+        {_format_behavior_panel(window)}
+
         <section class="panel">
           <div class="section-header">
             <div>
@@ -1784,6 +2000,133 @@ def _format_file_impact_panel(window: DashboardWindow) -> str:
         """
 
 
+def _format_behavior_panel(window: DashboardWindow) -> str:
+    behavior = window.behavior
+    if behavior is None or not behavior.supported or not behavior.total_calls:
+        return f"""
+        <section class="panel">
+          <div class="section-header">
+            <div>
+              <p class="section-kicker">What the Agent Did</p>
+              <h2>Tool Behavior</h2>
+            </div>
+          </div>
+          {_format_empty_showcase("No tool calls recorded for this view.", "This is either a genuinely quiet range, or a scope that does not report tool use. Tool calls are read from Codex rollouts, Claude Code transcripts, the OpenCode part table, and the Hermes message log; switch to All Time to see which applies.")}
+        </section>
+        """
+
+    category_svg = _svg_bar_chart(
+        [(entry.label, float(entry.calls)) for entry in behavior.categories],
+        bar_color="#0f766e",
+        value_formatter=lambda value: f"{int(value):,}",
+        empty_label="No tool categories recorded for this view.",
+    )
+    tool_svg = _svg_bar_chart(
+        [(entry.name, float(entry.calls)) for entry in behavior.tools[:8]],
+        bar_color="#7c3aed",
+        value_formatter=lambda value: f"{int(value):,}",
+        empty_label="No individual tools recorded for this view.",
+    )
+    rows = "".join(
+        f"""
+        <tr>
+          <td>{escape(entry.name)}</td>
+          <td>{escape(entry.category.title())}</td>
+          <td>{entry.calls:,}</td>
+          <td>{entry.errors:,}</td>
+          <td>{entry.recovered_errors:,}</td>
+          <td>{escape(_fmt_percent(entry.error_rate))}</td>
+        </tr>
+        """
+        for entry in behavior.tools[:10]
+    )
+    return f"""
+        <section class="panel">
+          <div class="section-header">
+            <div>
+              <p class="section-kicker">What the Agent Did</p>
+              <h2>Tool Behavior</h2>
+            </div>
+            <div class="spotlight-kpis">
+              <div class="spotlight-kpi"><strong>{behavior.total_calls:,}</strong><span>Tool calls</span></div>
+              <div class="spotlight-kpi"><strong>{escape(_fmt_percent(behavior.error_rate))}</strong><span>Failed</span></div>
+              <div class="spotlight-kpi"><strong>{escape(_fmt_percent(behavior.repeat_rate))}</strong><span>Repeated</span></div>
+              <div class="spotlight-kpi"><strong>{escape(_fmt_behavior_percent(behavior.repeat_time_rate))}</strong><span>Repeated time</span></div>
+              <div class="spotlight-kpi"><strong>{_fmt_behavior_ratio(behavior.read_write_ratio)}</strong><span>Read per edit</span></div>
+            </div>
+          </div>
+          <div class="chart-grid">
+            <div class="chart-card">
+              <h3>Calls by Category</h3>
+              {category_svg}
+            </div>
+            <div class="chart-card">
+              <h3>Most Used Tools</h3>
+              {tool_svg}
+            </div>
+            <div class="chart-card">
+              <h3>Failure Detail</h3>
+              <div class="table-wrap">
+                <table>
+                  <thead>
+                    <tr>
+                      <th>Tool</th>
+                      <th>Category</th>
+                      <th>Calls</th>
+                      <th>Failed</th>
+                      <th>Recovered</th>
+                      <th>Error rate</th>
+                    </tr>
+                  </thead>
+                  <tbody>{rows}</tbody>
+                </table>
+              </div>
+            </div>
+          </div>
+          <p class="panel-hint">{escape(_format_behavior_note(behavior))}</p>
+        </section>
+        """
+
+
+def _format_behavior_note(behavior) -> str:
+    sessions_noun = "session" if behavior.sessions_with_calls == 1 else "sessions"
+    note = (
+        "Categories are normalized across tools, so exec_command, Bash and bash all count "
+        f"as Execute. Repeated calls are counted within a single session, across "
+        f"{behavior.sessions_with_calls:,} {sessions_noun} with tool use."
+    )
+    if behavior.abandoned_turns:
+        turn_noun = "turn was" if behavior.abandoned_turns == 1 else "turns were"
+        note += f" {behavior.abandoned_turns} {turn_noun} abandoned before finishing."
+    else:
+        note += " Abandoned turns are only recorded where the source reports them (Codex)."
+    if behavior.total_duration_ms:
+        timed_noun = "call" if behavior.timed_calls == 1 else "calls"
+        note += (
+            f" Repeated time is the share of tool-call time spent on repeat work, measured over the "
+            f"{behavior.timed_calls:,} timed {timed_noun} (OpenCode and Claude record durations; Codex does not)."
+        )
+    else:
+        note += " This scope does not record tool-call durations, so repeated time is unavailable."
+    note += " A recovered failure is one that was later retried to success in the same session; "
+    note += "recovery is an exact command match, so a retry that changes the command is not counted."
+    return note
+
+
+def _fmt_behavior_percent(value: float | None) -> str:
+    if value is None:
+        return "n/a"
+    return f"{value * 100:.0f}%"
+
+
+def _fmt_behavior_ratio(value: float | None) -> str:
+    if value is None:
+        return "n/a"
+    if value >= 10:
+        return f"{value:.0f}"
+    return f"{value:.1f}"
+
+
 def _format_empty_showcase(title: str, detail: str) -> str:
     return f"""
     <div class="empty-showcase">