codex-stats 1.6.2__tar.gz → 1.7.0__tar.gz

{codex_stats-1.6.2/src/codex_stats.egg-info → codex_stats-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-stats
-Version: 1.6.2
+Version: 1.7.0
 Summary: Local AI usage observability CLI for Codex sessions.
 Author: Vivek
 License: MIT
@@ -27,18 +27,36 @@ Dynamic: license-file
 
 # codex-stats
 
-`codex-stats` is a local analytics tool for Codex usage.
+`codex-stats` is a local analytics tool for coding agents.
 
-It reads your local Codex state from `~/.codex` and surfaces:
+It reads local session data from every coding assistant installed on the machine and surfaces:
 
-- a browser dashboard with day, week, month, and all-time tabs
+- a browser dashboard with an **Overview** tab for every tool combined, plus one tab per tool (Codex, OpenCode, Claude Code, Hermes)
+- day, week, month, and all-time windows inside every tab
 - model and project breakdowns
 - recent session history
-- estimated token-based cost
+- estimated token-based cost (or each tool's own recorded cost when available)
+- per-tool cost overrides and a stacked per-tool token trend on the Overview
 - anomaly-aware usage insights and recommendations
 - export for cross-device snapshots
 - shareable JPG cards and browser PDF export from the dashboard
 
+## Data Sources
+
+Each source is detected automatically and skipped when no data is present:
+
+| Tool | Location | Notes |
+| --- | --- | --- |
+| Codex | `~/.codex` | `state_5.sqlite` + rollout JSONL files |
+| OpenCode | `~/.local/share/opencode/opencode.db` | recorded cost + tokens per session |
+| Claude Code | `~/.claude/projects/**/*.jsonl` | per-project transcripts |
+| Hermes | `~/.hermes/state.db` | recorded cost + tokens per session |
+
+Use these environment variables to point at non-default locations (also used for test isolation):
+
+- `CODEX_HOME` (Codex), `CODEX_STATS_OPENCODE_HOME` (OpenCode),
+  `CODEX_STATS_CLAUDE_PROJECTS_DIR` (Claude), `CODEX_STATS_HERMES_HOME` (Hermes)
+
 ## Install
 
 ```bash
@@ -59,6 +77,8 @@ python3 -m pip install codex-stats
   Write the dashboard HTML to a fixed path.
 - `codex-stats --output codex-stats-dashboard.html --no-open`
   Write the dashboard HTML without opening the browser.
+- `codex-stats --source codex --source opencode`
+  Restrict the dashboard to the given tool scopes (repeat the flag to pick multiple).
 - `codex-stats export codex-stats-export.json`
   Export normalized local stats to JSON.
 - `codex-stats export codex-stats-export.json --since 30d`
@@ -66,23 +86,31 @@ python3 -m pip install codex-stats
 
 Inside the dashboard, use the action bar to:
 
-- switch between `Day`, `Week`, `Month`, and `All Time`
-- print the active tab to PDF
+- switch tools with the **Overview / Codex / OpenCode / Claude Code / Hermes** tab row
+- switch between `Day`, `Week`, `Month`, and `All Time` inside the active tool
+- print the active tool and window to PDF
 - download shareable JPG cards for summary, cost, focus, and project share
 
 ## How It Works
 
-`codex-stats` does not proxy or intercept Codex API traffic.
+`codex-stats` does not proxy or intercept API traffic. It reads local artifacts:
+Codex `state_5.sqlite` and rollout files, the OpenCode database, Claude Code project
+transcripts, and the Hermes database, then normalizes everything into one session model.
 
-It reads local Codex artifacts, including:
+## Notes
 
-- `state_5.sqlite` for session metadata
-- rollout JSONL files for request and token snapshots
+- Costs are estimates by default. When a tool records its own cost (OpenCode, Hermes),
+  that value wins for the session. Per-tool rates can be set in `~/.config/codex-stats/config.toml`:
 
-## Notes
+  ```toml
+  [pricing.source_usd_per_1k_tokens]
+  codex = 0.01
+  opencode = 0.01
+  claude = 0.015
+  hermes = 0.008
+  ```
 
-- Costs are estimates, not billing values.
-- Output depends on local Codex file formats remaining compatible.
+- Output depends on local file formats remaining compatible.
 - `export --since Nd` limits snapshots to a rolling window before sharing.
 
 ## Roadmap

{codex_stats-1.6.2 → codex_stats-1.7.0}/README.md

@@ -1,17 +1,35 @@
 # codex-stats
 
-`codex-stats` is a local analytics tool for Codex usage.
+`codex-stats` is a local analytics tool for coding agents.
 
-It reads your local Codex state from `~/.codex` and surfaces:
+It reads local session data from every coding assistant installed on the machine and surfaces:
 
-- a browser dashboard with day, week, month, and all-time tabs
+- a browser dashboard with an **Overview** tab for every tool combined, plus one tab per tool (Codex, OpenCode, Claude Code, Hermes)
+- day, week, month, and all-time windows inside every tab
 - model and project breakdowns
 - recent session history
-- estimated token-based cost
+- estimated token-based cost (or each tool's own recorded cost when available)
+- per-tool cost overrides and a stacked per-tool token trend on the Overview
 - anomaly-aware usage insights and recommendations
 - export for cross-device snapshots
 - shareable JPG cards and browser PDF export from the dashboard
 
+## Data Sources
+
+Each source is detected automatically and skipped when no data is present:
+
+| Tool | Location | Notes |
+| --- | --- | --- |
+| Codex | `~/.codex` | `state_5.sqlite` + rollout JSONL files |
+| OpenCode | `~/.local/share/opencode/opencode.db` | recorded cost + tokens per session |
+| Claude Code | `~/.claude/projects/**/*.jsonl` | per-project transcripts |
+| Hermes | `~/.hermes/state.db` | recorded cost + tokens per session |
+
+Use these environment variables to point at non-default locations (also used for test isolation):
+
+- `CODEX_HOME` (Codex), `CODEX_STATS_OPENCODE_HOME` (OpenCode),
+  `CODEX_STATS_CLAUDE_PROJECTS_DIR` (Claude), `CODEX_STATS_HERMES_HOME` (Hermes)
+
 ## Install
 
 ```bash
@@ -32,6 +50,8 @@ python3 -m pip install codex-stats
   Write the dashboard HTML to a fixed path.
 - `codex-stats --output codex-stats-dashboard.html --no-open`
   Write the dashboard HTML without opening the browser.
+- `codex-stats --source codex --source opencode`
+  Restrict the dashboard to the given tool scopes (repeat the flag to pick multiple).
 - `codex-stats export codex-stats-export.json`
   Export normalized local stats to JSON.
 - `codex-stats export codex-stats-export.json --since 30d`
@@ -39,23 +59,31 @@ python3 -m pip install codex-stats
 
 Inside the dashboard, use the action bar to:
 
-- switch between `Day`, `Week`, `Month`, and `All Time`
-- print the active tab to PDF
+- switch tools with the **Overview / Codex / OpenCode / Claude Code / Hermes** tab row
+- switch between `Day`, `Week`, `Month`, and `All Time` inside the active tool
+- print the active tool and window to PDF
 - download shareable JPG cards for summary, cost, focus, and project share
 
 ## How It Works
 
-`codex-stats` does not proxy or intercept Codex API traffic.
+`codex-stats` does not proxy or intercept API traffic. It reads local artifacts:
+Codex `state_5.sqlite` and rollout files, the OpenCode database, Claude Code project
+transcripts, and the Hermes database, then normalizes everything into one session model.
 
-It reads local Codex artifacts, including:
+## Notes
 
-- `state_5.sqlite` for session metadata
-- rollout JSONL files for request and token snapshots
+- Costs are estimates by default. When a tool records its own cost (OpenCode, Hermes),
+  that value wins for the session. Per-tool rates can be set in `~/.config/codex-stats/config.toml`:
 
-## Notes
+  ```toml
+  [pricing.source_usd_per_1k_tokens]
+  codex = 0.01
+  opencode = 0.01
+  claude = 0.015
+  hermes = 0.008
+  ```
 
-- Costs are estimates, not billing values.
-- Output depends on local Codex file formats remaining compatible.
+- Output depends on local file formats remaining compatible.
 - `export --since Nd` limits snapshots to a rolling window before sharing.
 
 ## Roadmap

{codex_stats-1.6.2 → codex_stats-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-stats"
-version = "1.6.2"
+version = "1.7.0"
 description = "Local AI usage observability CLI for Codex sessions."
 readme = "README.md"
 requires-python = ">=3.11"

{codex_stats-1.6.2 → codex_stats-1.7.0}/src/codex_stats/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "1.6.2"
+__version__ = "1.7.0"

{codex_stats-1.6.2 → codex_stats-1.7.0}/src/codex_stats/cli.py

@@ -21,12 +21,19 @@ from .metrics import (
     summarize_insights_from_details,
     summarize_project_drilldowns_from_details,
     summarize_projects_from_details,
+    summarize_source_breakdown_from_details,
+    summarize_source_daily_from_details,
     summarize_takeaways,
     summarize_top_sessions_from_details,
     summarize_work_rhythm,
 )
-from .ingest import iter_session_details
-from .models import DashboardData, DashboardWindow, SessionDetails
+from .models import (
+    DashboardData,
+    DashboardScope,
+    DashboardWindow,
+    SessionDetails,
+)
+from .sources import Source, iter_sources
 from .transfer import write_export
 
 
@@ -41,6 +48,13 @@ def build_parser() -> argparse.ArgumentParser:
         help="Write dashboard HTML to a file instead of a temp file.",
     )
     parser.add_argument("--no-open", action="store_true", help="Write the dashboard without opening the browser.")
+    parser.add_argument(
+        "--source",
+        action="append",
+        dest="sources",
+        metavar="SOURCE",
+        help="Only include the given tool scope (codex, opencode, claude, hermes). Repeatable: --source codex --source opencode.",
+    )
     subparsers = parser.add_subparsers(dest="command")
 
     export_parser = subparsers.add_parser("export", help="Export normalized local stats to JSON.")
@@ -63,7 +77,7 @@ def main(argv: list[str] | None = None) -> int:
         parser.print_help()
         return 1
 
-    dashboard = _build_dashboard(paths)
+    dashboard = _build_dashboard(paths, sources=args.sources)
     output_path = _write_dashboard_output(format_dashboard_html(dashboard), args.dashboard_output)
     print(f"Wrote dashboard to {output_path}")
     if not args.no_open:
@@ -72,62 +86,118 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
-def _build_dashboard(paths: Paths, now: datetime | None = None) -> DashboardData:
+def _build_dashboard(paths: Paths, now: datetime | None = None, sources: list[str] | None = None) -> DashboardData:
     current_time = now or datetime.now().astimezone()
     pricing = load_pricing_config(paths)
-    all_details = iter_session_details(paths)
+    all_sources = iter_sources(paths)
+    if sources:
+        requested = set(sources)
+        missing = sorted(requested - {source.key for source in all_sources})
+        if missing:
+            known = ", ".join(sorted(source.key for source in all_sources)) or "none"
+            raise ValueError(f"Unknown source(s): {', '.join(missing)}. Known sources: {known}")
+        selected_sources = [source for source in all_sources if source.key in requested]
+    else:
+        selected_sources = all_sources
+    source_details = {source.key: source.ingest() for source in selected_sources}
+    all_details = [detail for source in selected_sources for detail in source_details[source.key]]
+
+    overview = _build_scope(
+        key="overview",
+        label="Overview",
+        description="Every tool combined. Start here to see total activity, spend, and where the work happened.",
+        source="all",
+        details=all_details,
+        pricing=pricing,
+        now=current_time,
+        build_tool_breakdown=True,
+    )
+    tool_scopes = [
+        _build_scope(
+            key=source.key,
+            label=source.label,
+            description=source.description,
+            source=source.key,
+            details=source_details[source.key],
+            pricing=pricing,
+            now=current_time,
+        )
+        for source in selected_sources
+    ]
+    return DashboardData(generated_at=current_time, scopes=[overview, *tool_scopes])
 
-    today_details = _details_for_last_days(all_details, 1, current_time)
-    week_details = _details_for_last_days(all_details, 7, current_time)
-    month_details = _details_for_last_days(all_details, 30, current_time)
 
+def _build_scope(
+    *,
+    key: str,
+    label: str,
+    description: str,
+    source: str,
+    details: list[SessionDetails],
+    pricing: PricingConfig,
+    now: datetime,
+    build_tool_breakdown: bool = False,
+) -> DashboardScope:
+    today_details = _details_for_last_days(details, 1, now)
+    week_details = _details_for_last_days(details, 7, now)
+    month_details = _details_for_last_days(details, 30, now)
     windows = [
         _build_window(
             key="day",
             label="Day",
             description="Today’s usage with a direct comparison to yesterday.",
             current_details=today_details,
-            previous_details=_details_for_previous_window(all_details, 1, current_time),
+            previous_details=_details_for_previous_window(details, 1, now),
             current_label="today",
             previous_label="yesterday",
             trend_days=1,
-            all_details=all_details,
+            all_details=details,
             pricing=pricing,
-            now=current_time,
+            now=now,
+            build_tool_breakdown=build_tool_breakdown,
         ),
         _build_window(
             key="week",
             label="Week",
             description="Rolling 7-day totals, recent trend, and the busiest sessions this week.",
             current_details=week_details,
-            previous_details=_details_for_previous_window(all_details, 7, current_time),
+            previous_details=_details_for_previous_window(details, 7, now),
             current_label="last 7 days",
             previous_label="previous 7 days",
             trend_days=7,
-            all_details=all_details,
+            all_details=details,
             pricing=pricing,
-            now=current_time,
+            now=now,
+            build_tool_breakdown=build_tool_breakdown,
         ),
         _build_window(
             key="month",
             label="Month",
             description="Rolling 30-day totals with project concentration and cost pressure.",
             current_details=month_details,
-            previous_details=_details_for_previous_window(all_details, 30, current_time),
+            previous_details=_details_for_previous_window(details, 30, now),
             current_label="last 30 days",
             previous_label="previous 30 days",
             trend_days=30,
-            all_details=all_details,
+            all_details=details,
             pricing=pricing,
-            now=current_time,
+            now=now,
+            build_tool_breakdown=build_tool_breakdown,
         ),
         _build_all_time_window(
-            all_details=all_details,
+            all_details=details,
             pricing=pricing,
-            now=current_time,
+            now=now,
+            build_tool_breakdown=build_tool_breakdown,
         ),
     ]
-    return DashboardData(generated_at=current_time, windows=windows)
+    return DashboardScope(
+        key=key,
+        label=label,
+        description=description,
+        source=source,
+        windows=windows,
+    )
 
 
 def _build_window(
@@ -143,6 +213,7 @@ def _build_window(
     all_details: list[SessionDetails],
     pricing: PricingConfig,
     now: datetime,
+    build_tool_breakdown: bool = False,
 ) -> DashboardWindow:
     summary = summarize_details(current_label, current_details, pricing)
     comparison = summarize_compare_from_details(
@@ -189,6 +260,21 @@ def _build_window(
             pricing=pricing,
             limit=5,
         ),
+        tool_breakdown=(
+            summarize_source_breakdown_from_details(current_details, pricing)
+            if build_tool_breakdown
+            else None
+        ),
+        tool_daily_points=(
+            summarize_source_daily_from_details(
+                current_details,
+                days=max(trend_days, 1),
+                now=now,
+                pricing=pricing,
+            )
+            if build_tool_breakdown
+            else None
+        ),
     )
 
 
@@ -197,6 +283,7 @@ def _build_all_time_window(
     all_details: list[SessionDetails],
     pricing: PricingConfig,
     now: datetime,
+    build_tool_breakdown: bool = False,
 ) -> DashboardWindow:
     summary = summarize_details("all time", all_details, pricing)
     recent_details = _details_for_last_days(all_details, 30, now)
@@ -244,6 +331,21 @@ def _build_all_time_window(
             pricing=pricing,
             limit=5,
         ),
+        tool_breakdown=(
+            summarize_source_breakdown_from_details(all_details, pricing)
+            if build_tool_breakdown
+            else None
+        ),
+        tool_daily_points=(
+            summarize_source_daily_from_details(
+                all_details,
+                days=trend_days,
+                now=now,
+                pricing=pricing,
+            )
+            if build_tool_breakdown
+            else None
+        ),
     )
 
 

{codex_stats-1.6.2 → codex_stats-1.7.0}/src/codex_stats/config.py

@@ -15,6 +15,13 @@ default_usd_per_1k_tokens = 0.01
 # gpt-5.4 = 0.02
 # gpt-5-mini = 0.005
 
+[pricing.source_usd_per_1k_tokens]
+# Per-tool overrides when a tool does not record its own cost.
+# codex = 0.01
+# opencode = 0.01
+# claude = 0.015
+# hermes = 0.008
+
 [display]
 color = "auto"
 history_limit = 10
@@ -51,12 +58,18 @@ class Paths:
 class PricingConfig:
     default_usd_per_1k_tokens: float = 0.01
     model_rates: dict[str, float] | None = None
+    source_rates: dict[str, float] | None = None
 
     def rate_for_model(self, model: str | None) -> float:
         if model and self.model_rates and model in self.model_rates:
             return self.model_rates[model]
         return self.default_usd_per_1k_tokens
 
+    def rate_for_source(self, source: str, model: str | None) -> float:
+        if source and self.source_rates and source in self.source_rates:
+            return self.source_rates[source]
+        return self.rate_for_model(model)
+
 
 @dataclass(frozen=True)
 class DisplayConfig:
@@ -79,6 +92,7 @@ def load_config(paths: Paths) -> AppConfig:
     pricing = payload.get("pricing", {})
     default_rate = float(pricing.get("default_usd_per_1k_tokens", 0.01))
     model_rates = _flatten_model_rates(pricing.get("model_usd_per_1k_tokens", {}))
+    source_rates = {str(k): float(v) for k, v in pricing.get("source_usd_per_1k_tokens", {}).items()}
     display = payload.get("display", {})
     color = str(display.get("color", "auto"))
     if color not in {"auto", "always", "never"}:
@@ -90,7 +104,11 @@ def load_config(paths: Paths) -> AppConfig:
     if compare_days <= 0:
         raise ValueError("display.compare_days must be greater than 0")
     return AppConfig(
-        pricing=PricingConfig(default_usd_per_1k_tokens=default_rate, model_rates=model_rates),
+        pricing=PricingConfig(
+            default_usd_per_1k_tokens=default_rate,
+            model_rates=model_rates,
+            source_rates=source_rates,
+        ),
         display=DisplayConfig(color=color, history_limit=history_limit, compare_days=compare_days),
     )
 
@@ -110,6 +128,7 @@ def load_config_view(paths: Paths) -> ConfigView:
         exists=paths.config_file.exists(),
         pricing_default_usd_per_1k_tokens=app_config.pricing.default_usd_per_1k_tokens,
         pricing_model_overrides=app_config.pricing.model_rates or {},
+        pricing_source_overrides=app_config.pricing.source_rates or {},
         display=DisplayConfigView(
             color=app_config.display.color,
             history_limit=app_config.display.history_limit,