opencode-usage 0.1.0__tar.gz

opencode_usage-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+

opencode_usage-0.1.0/LICENSE

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

opencode_usage-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: opencode-usage
+Version: 0.1.0
+Summary: CLI tool to track and display OpenCode token usage statistics
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# opencode-usage
+
+CLI tool to track and display [OpenCode](https://github.com/opencodeco/opencode) token usage statistics. Reads directly from OpenCode's local SQLite database — no API keys or external services needed.
+
+## Features
+
+- **Daily breakdown** — token usage and cost per day
+- **Group by dimension** — model, agent, provider, or session
+- **Agent × Model view** — see which model each agent uses
+- **Time filtering** — last N days, relative durations (`7d`, `2w`), or ISO dates
+- **JSON output** — pipe to `jq` or other tools
+- **Cross-platform** — macOS, Linux, Windows
+
+## Installation
+
+```bash
+git clone https://github.com/rchardx/opencode-usage.git
+cd opencode-usage
+uv sync
+uv tool install -e .
+```
+
+After installation, `opencode-usage` is available globally.
+
+## Usage
+
+```bash
+# Default: last 7 days, daily breakdown
+opencode-usage
+
+# Quick shortcuts
+opencode-usage today
+opencode-usage yesterday
+
+# Time filtering
+opencode-usage --days 30
+opencode-usage --since 7d
+opencode-usage --since 2025-01-01
+
+# Group by dimension
+opencode-usage --by model
+opencode-usage --by agent          # shows model per agent
+opencode-usage --by provider
+opencode-usage --by session --limit 10
+
+# JSON output
+opencode-usage --json
+opencode-usage --by model --json | jq '.rows[].label'
+```
+
+### Example output
+
+```
+╭──────────────── OpenCode Usage — Last 7 days ────────────────╮
+│   Calls: 1,280  │  Tokens: 52.3M  │  Cost: $0.00             │
+╰──────────────────────────────────────────────────────────────╯
+
+               Usage by Agent (Last 7 days)
+┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
+┃ Agent                  ┃ Model        ┃ Calls ┃   Total ┃    Cost ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━┩
+│ build                  │ deepseek-r1  │   420 │   18.2M │       - │
+│                        │ qwen-3-coder │   105 │    4.7M │       - │
+├────────────────────────┼──────────────┼───────┼─────────┼─────────┤
+│ explore                │ gemma-3      │   310 │   12.5M │       - │
+│                        │ minimax-m2.5 │   198 │    8.1M │       - │
+├────────────────────────┼──────────────┼───────┼─────────┼─────────┤
+│ librarian              │ llama-4      │   156 │    5.8M │       - │
+├────────────────────────┼──────────────┼───────┼─────────┼─────────┤
+│ oracle                 │ qwen-3-coder │    91 │    3.0M │       - │
+└────────────────────────┴──────────────┴───────┴─────────┴─────────┘
+```
+
+## Configuration
+
+| Environment Variable | Description |
+|---|---|
+| `OPENCODE_DB` | Override database path (default: auto-detected per platform) |
+
+Default database locations:
+
+- **macOS / Linux**: `~/.local/share/opencode/opencode.db`
+- **Windows**: `%LOCALAPPDATA%\opencode\opencode.db`
+
+## Development
+
+```bash
+git clone https://github.com/rchardx/opencode-usage.git
+cd opencode-usage
+uv sync
+
+# Lint & format
+uvx ruff check .
+uvx ruff format .
+
+# Install pre-commit hooks
+uvx pre-commit install
+```
+
+## License
+
+[MIT](LICENSE)

opencode_usage-0.1.0/README.md

@@ -0,0 +1,102 @@
+# opencode-usage
+
+CLI tool to track and display [OpenCode](https://github.com/opencodeco/opencode) token usage statistics. Reads directly from OpenCode's local SQLite database — no API keys or external services needed.
+
+## Features
+
+- **Daily breakdown** — token usage and cost per day
+- **Group by dimension** — model, agent, provider, or session
+- **Agent × Model view** — see which model each agent uses
+- **Time filtering** — last N days, relative durations (`7d`, `2w`), or ISO dates
+- **JSON output** — pipe to `jq` or other tools
+- **Cross-platform** — macOS, Linux, Windows
+
+## Installation
+
+```bash
+git clone https://github.com/rchardx/opencode-usage.git
+cd opencode-usage
+uv sync
+uv tool install -e .
+```
+
+After installation, `opencode-usage` is available globally.
+
+## Usage
+
+```bash
+# Default: last 7 days, daily breakdown
+opencode-usage
+
+# Quick shortcuts
+opencode-usage today
+opencode-usage yesterday
+
+# Time filtering
+opencode-usage --days 30
+opencode-usage --since 7d
+opencode-usage --since 2025-01-01
+
+# Group by dimension
+opencode-usage --by model
+opencode-usage --by agent          # shows model per agent
+opencode-usage --by provider
+opencode-usage --by session --limit 10
+
+# JSON output
+opencode-usage --json
+opencode-usage --by model --json | jq '.rows[].label'
+```
+
+### Example output
+
+```
+╭──────────────── OpenCode Usage — Last 7 days ────────────────╮
+│   Calls: 1,280  │  Tokens: 52.3M  │  Cost: $0.00             │
+╰──────────────────────────────────────────────────────────────╯
+
+               Usage by Agent (Last 7 days)
+┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
+┃ Agent                  ┃ Model        ┃ Calls ┃   Total ┃    Cost ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━┩
+│ build                  │ deepseek-r1  │   420 │   18.2M │       - │
+│                        │ qwen-3-coder │   105 │    4.7M │       - │
+├────────────────────────┼──────────────┼───────┼─────────┼─────────┤
+│ explore                │ gemma-3      │   310 │   12.5M │       - │
+│                        │ minimax-m2.5 │   198 │    8.1M │       - │
+├────────────────────────┼──────────────┼───────┼─────────┼─────────┤
+│ librarian              │ llama-4      │   156 │    5.8M │       - │
+├────────────────────────┼──────────────┼───────┼─────────┼─────────┤
+│ oracle                 │ qwen-3-coder │    91 │    3.0M │       - │
+└────────────────────────┴──────────────┴───────┴─────────┴─────────┘
+```
+
+## Configuration
+
+| Environment Variable | Description |
+|---|---|
+| `OPENCODE_DB` | Override database path (default: auto-detected per platform) |
+
+Default database locations:
+
+- **macOS / Linux**: `~/.local/share/opencode/opencode.db`
+- **Windows**: `%LOCALAPPDATA%\opencode\opencode.db`
+
+## Development
+
+```bash
+git clone https://github.com/rchardx/opencode-usage.git
+cd opencode-usage
+uv sync
+
+# Lint & format
+uvx ruff check .
+uvx ruff format .
+
+# Install pre-commit hooks
+uvx pre-commit install
+```
+
+## License
+
+[MIT](LICENSE)

opencode_usage-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "opencode-usage"
+version = "0.1.0"
+description = "CLI tool to track and display OpenCode token usage statistics"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "rich>=13.0",
+]
+
+[dependency-groups]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+opencode-usage = "opencode_usage.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opencode_usage"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/opencode_usage"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["opencode_usage"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

opencode_usage-0.1.0/src/opencode_usage/__init__.py

@@ -0,0 +1,3 @@
+"""OpenCode usage statistics CLI."""
+
+__version__ = "0.1.0"

opencode_usage-0.1.0/src/opencode_usage/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m opencode_usage`."""
+
+from .cli import main
+
+main()

opencode_usage-0.1.0/src/opencode_usage/cli.py

@@ -0,0 +1,236 @@
+"""CLI entry point for opencode-usage."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timedelta
+from typing import Any
+
+from . import render
+from .db import OpenCodeDB, UsageRow
+from .render import configure_console, render_daily, render_grouped, render_summary
+
+
+def _parse_since(value: str) -> datetime:
+    """Parse a relative duration like '7d', '2w', '30d', '3h' or an ISO date."""
+    m = re.fullmatch(r"(\d+)([dhwm])", value.strip().lower())
+    if m:
+        n, unit = int(m.group(1)), m.group(2)
+        delta = {
+            "h": timedelta(hours=n),
+            "d": timedelta(days=n),
+            "w": timedelta(weeks=n),
+            "m": timedelta(days=n * 30),
+        }[unit]
+        return datetime.now().astimezone() - delta
+
+    # Try ISO date
+    try:
+        dt = datetime.fromisoformat(value)
+        if dt.tzinfo is None:
+            dt = dt.astimezone()
+        return dt
+    except ValueError:
+        pass
+
+    raise argparse.ArgumentTypeError(
+        f"Invalid time spec: '{value}'. Use '7d', '2w', '30d', '3h', or ISO date."
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="opencode-usage",
+        description="Track and display OpenCode token usage statistics.",
+    )
+
+    p.add_argument(
+        "command",
+        nargs="?",
+        default=None,
+        choices=["today", "yesterday"],
+        help="Quick shortcut: 'today' or 'yesterday'",
+    )
+    p.add_argument(
+        "--days",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Show last N days (default: 7)",
+    )
+    p.add_argument(
+        "--since",
+        type=_parse_since,
+        default=None,
+        metavar="SPEC",
+        help="Time filter: '7d', '2w', '30d', '3h', or ISO date",
+    )
+    p.add_argument(
+        "--by",
+        choices=["model", "agent", "provider", "session", "day"],
+        default=None,
+        help="Group results by dimension",
+    )
+    p.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Max rows to display",
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Output as JSON",
+    )
+    p.add_argument(
+        "--compare",
+        action="store_true",
+        help="Compare with previous period of same length",
+    )
+    p.add_argument(
+        "--no-color",
+        action="store_true",
+        dest="no_color",
+        help="Disable colored output",
+    )
+    p.add_argument(
+        "--db",
+        default=None,
+        metavar="PATH",
+        help="Path to OpenCode database (default: auto-detect)",
+    )
+    return p
+
+
+def _resolve_since(args: argparse.Namespace) -> tuple[datetime | None, str]:
+    """Resolve the effective 'since' datetime and a human-readable period label."""
+    now = datetime.now().astimezone()
+
+    if args.command == "today":
+        since = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        return since, "Today"
+
+    if args.command == "yesterday":
+        yesterday = now - timedelta(days=1)
+        since = yesterday.replace(hour=0, minute=0, second=0, microsecond=0)
+        return since, "Yesterday & Today"
+
+    if args.since is not None:
+        return args.since, f"Since {args.since.strftime('%Y-%m-%d')}"
+
+    if args.days is not None:
+        since = now - timedelta(days=args.days)
+        return since, f"Last {args.days} days"
+
+    # Default: last 7 days
+    since = now - timedelta(days=7)
+    return since, "Last 7 days"
+
+
+def _fetch_rows(
+    db: OpenCodeDB,
+    group_by: str,
+    *,
+    since: datetime | None = None,
+    until: datetime | None = None,
+    limit: int | None = None,
+) -> list[UsageRow]:
+    """Fetch rows based on group_by dimension."""
+    if group_by == "day":
+        return db.daily(since=since, until=until, limit=limit)
+    if group_by == "model":
+        return db.by_model(since=since, until=until, limit=limit)
+    if group_by == "agent":
+        return db.by_agent(since=since, until=until, limit=limit)
+    if group_by == "provider":
+        return db.by_provider(since=since, until=until, limit=limit)
+    if group_by == "session":
+        return db.by_session(since=since, until=until, limit=limit)
+    return []
+
+
+def _compute_deltas(
+    current: list[UsageRow],
+    previous: list[UsageRow],
+) -> list[float | None]:
+    """Compute token delta percentages between current and previous rows."""
+    prev_map: dict[str, int] = {}
+    for r in previous:
+        key = f"{r.label}:{r.detail}" if r.detail else r.label
+        prev_map[key] = prev_map.get(key, 0) + r.tokens.total
+
+    deltas: list[float | None] = []
+    for r in current:
+        key = f"{r.label}:{r.detail}" if r.detail else r.label
+        prev_val = prev_map.get(key)
+        if prev_val and prev_val > 0:
+            deltas.append((r.tokens.total - prev_val) / prev_val * 100)
+        else:
+            deltas.append(None)
+    return deltas
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.no_color:
+        configure_console(no_color=True)
+
+    try:
+        db = OpenCodeDB(db_path=args.db)
+    except FileNotFoundError as e:
+        render.console.print(f"[red]Error:[/red] {e}")
+        sys.exit(1)
+
+    since, period = _resolve_since(args)
+    group_by = args.by or "day"
+
+    # Compute previous period for --compare
+    now = datetime.now().astimezone()
+    prev_since = None
+    if args.compare and since is not None:
+        period_length = now - since
+        prev_since = since - period_length
+
+    # Fetch current data
+    rows = _fetch_rows(db, group_by, since=since, limit=args.limit)
+    total = db.totals(since=since)
+
+    # Fetch previous period data for --compare
+    prev_total = None
+    prev_rows: list[UsageRow] = []
+    if prev_since is not None:
+        prev_total = db.totals(since=prev_since, until=since)
+        if group_by != "day":
+            prev_rows = _fetch_rows(db, group_by, since=prev_since, until=since, limit=args.limit)
+
+    # JSON output
+    if args.json_output:
+        output: dict[str, Any] = {
+            "period": period,
+            "total": db.to_dicts([total])[0],
+            "rows": db.to_dicts(rows),
+        }
+        if prev_total is not None:
+            output["previous_total"] = db.to_dicts([prev_total])[0]
+        if prev_rows:
+            output["previous_rows"] = db.to_dicts(prev_rows)
+        print(json.dumps(output, indent=2, ensure_ascii=False))
+        return
+
+    # Rich output
+    render_summary(total, period, prev_total=prev_total)
+    render.console.print()
+
+    deltas = _compute_deltas(rows, prev_rows) if prev_rows else None
+
+    if group_by == "day":
+        render_daily(rows, period)
+    else:
+        render_grouped(rows, group_by, period, deltas=deltas)

opencode_usage-0.1.0/src/opencode_usage/db.py

@@ -0,0 +1,332 @@
+"""SQLite query layer for OpenCode's database."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sqlite3
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+def _default_db_path() -> Path:
+    """Resolve the OpenCode database path per platform."""
+    if custom := os.environ.get("OPENCODE_DB"):
+        return Path(custom)
+
+    system = platform.system()
+    if system == "Darwin":
+        base = Path.home() / ".local" / "share"
+    elif system == "Linux":
+        base = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+    elif system == "Windows":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+    else:
+        base = Path.home() / ".local" / "share"
+
+    return base / "opencode" / "opencode.db"
+
+
+@dataclass
+class TokenStats:
+    input: int = 0
+    output: int = 0
+    reasoning: int = 0
+    cache_read: int = 0
+    cache_write: int = 0
+    total: int = 0
+
+
+@dataclass
+class UsageRow:
+    """A single aggregated usage row."""
+
+    label: str
+    calls: int = 0
+    tokens: TokenStats = field(default_factory=TokenStats)
+    cost: float = 0.0
+    detail: str | None = None
+
+
+class OpenCodeDB:
+    """Read-only access to the OpenCode SQLite database."""
+
+    def __init__(self, db_path: Path | str | None = None) -> None:
+        self.path = Path(db_path) if db_path else _default_db_path()
+        if not self.path.exists():
+            raise FileNotFoundError(
+                f"OpenCode database not found at {self.path}\nSet OPENCODE_DB env var to override."
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(f"file:{self.path}?mode=ro", uri=True)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    # ── query helpers ─────────────────────────────────────────────
+
+    def _time_filter(
+        self,
+        since: datetime | None,
+        until: datetime | None = None,
+        *,
+        col: str = "data",
+    ) -> tuple[str, list[Any]]:
+        """Return WHERE clause fragments and params for time filtering."""
+        clauses: list[str] = []
+        params: list[Any] = []
+        if since is not None:
+            ts_ms = int(since.timestamp() * 1000)
+            clauses.append(f"AND json_extract({col}, '$.time.created') >= ?")
+            params.append(ts_ms)
+        if until is not None:
+            ts_ms = int(until.timestamp() * 1000)
+            clauses.append(f"AND json_extract({col}, '$.time.created') < ?")
+            params.append(ts_ms)
+        return " ".join(clauses), params
+
+    def _base_query(
+        self,
+        group_expr: str,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        order: str = "total_tokens DESC",
+        limit: int | None = None,
+    ) -> list[UsageRow]:
+        time_clause, params = self._time_filter(since, until)
+
+        sql = f"""
+            SELECT
+                {group_expr} AS label,
+                COUNT(*)                                           AS calls,
+                COALESCE(SUM(json_extract(data, '$.tokens.input')),     0) AS input_tokens,
+                COALESCE(SUM(json_extract(data, '$.tokens.output')),    0) AS output_tokens,
+                COALESCE(SUM(json_extract(data, '$.tokens.reasoning')), 0) AS reasoning_tokens,
+                COALESCE(SUM(json_extract(data, '$.tokens.cache.read')),  0) AS cache_read,
+                COALESCE(SUM(json_extract(data, '$.tokens.cache.write')), 0) AS cache_write,
+                COALESCE(SUM(json_extract(data, '$.tokens.total')),    0) AS total_tokens,
+                COALESCE(SUM(json_extract(data, '$.cost')),            0) AS cost
+            FROM message
+            WHERE json_extract(data, '$.role') = 'assistant'
+              AND json_extract(data, '$.tokens.total') IS NOT NULL
+              {time_clause}
+            GROUP BY label
+            ORDER BY {order}
+        """
+        if limit:
+            sql += f" LIMIT {limit}"
+
+        conn = self._connect()
+        try:
+            rows = conn.execute(sql, params).fetchall()
+        finally:
+            conn.close()
+
+        return [
+            UsageRow(
+                label=r["label"] or "(unknown)",
+                calls=r["calls"],
+                tokens=TokenStats(
+                    input=r["input_tokens"],
+                    output=r["output_tokens"],
+                    reasoning=r["reasoning_tokens"],
+                    cache_read=r["cache_read"],
+                    cache_write=r["cache_write"],
+                    total=r["total_tokens"],
+                ),
+                cost=r["cost"],
+            )
+            for r in rows
+        ]
+
+    # ── public API ────────────────────────────────────────────────
+
+    def daily(
+        self,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        limit: int | None = None,
+    ) -> list[UsageRow]:
+        return self._base_query(
+            group_expr=(
+                "date(json_extract(data, '$.time.created') / 1000, 'unixepoch', 'localtime')"
+            ),
+            since=since,
+            until=until,
+            order="label DESC",
+            limit=limit,
+        )
+
+    def by_model(
+        self,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        limit: int | None = None,
+    ) -> list[UsageRow]:
+        return self._base_query(
+            group_expr="json_extract(data, '$.modelID')",
+            since=since,
+            until=until,
+            limit=limit,
+        )
+
+    def by_agent(
+        self,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        limit: int | None = None,
+    ) -> list[UsageRow]:
+        """Group by agent x model, showing which model each agent uses."""
+        time_clause, params = self._time_filter(since, until)
+
+        sql = f"""
+            SELECT
+                json_extract(data, '$.agent')   AS agent,
+                json_extract(data, '$.modelID') AS model,
+                COUNT(*)                                           AS calls,
+                COALESCE(SUM(json_extract(data, '$.tokens.input')),     0) AS input_tokens,
+                COALESCE(SUM(json_extract(data, '$.tokens.output')),    0) AS output_tokens,
+                COALESCE(SUM(json_extract(data, '$.tokens.reasoning')), 0) AS reasoning_tokens,
+                COALESCE(SUM(json_extract(data, '$.tokens.cache.read')),  0) AS cache_read,
+                COALESCE(SUM(json_extract(data, '$.tokens.cache.write')), 0) AS cache_write,
+                COALESCE(SUM(json_extract(data, '$.tokens.total')),    0) AS total_tokens,
+                COALESCE(SUM(json_extract(data, '$.cost')),            0) AS cost
+            FROM message
+            WHERE json_extract(data, '$.role') = 'assistant'
+              AND json_extract(data, '$.tokens.total') IS NOT NULL
+              {time_clause}
+            GROUP BY agent, model
+            ORDER BY agent, total_tokens DESC
+        """
+        if limit:
+            sql += f" LIMIT {limit}"
+
+        conn = self._connect()
+        try:
+            rows = conn.execute(sql, params).fetchall()
+        finally:
+            conn.close()
+
+        return [
+            UsageRow(
+                label=r["agent"] or "(unknown)",
+                calls=r["calls"],
+                tokens=TokenStats(
+                    input=r["input_tokens"],
+                    output=r["output_tokens"],
+                    reasoning=r["reasoning_tokens"],
+                    cache_read=r["cache_read"],
+                    cache_write=r["cache_write"],
+                    total=r["total_tokens"],
+                ),
+                cost=r["cost"],
+                detail=r["model"],
+            )
+            for r in rows
+        ]
+
+    def by_provider(
+        self,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        limit: int | None = None,
+    ) -> list[UsageRow]:
+        return self._base_query(
+            group_expr="json_extract(data, '$.providerID')",
+            since=since,
+            until=until,
+            limit=limit,
+        )
+
+    def by_session(
+        self,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        limit: int | None = None,
+    ) -> list[UsageRow]:
+        """Group by session, using session title as label."""
+        time_clause, params = self._time_filter(since, until, col="m.data")
+
+        sql = f"""
+            SELECT
+                COALESCE(s.title, m.session_id) AS label,
+                COUNT(*)                                           AS calls,
+                COALESCE(SUM(json_extract(m.data, '$.tokens.input')),     0) AS input_tokens,
+                COALESCE(SUM(json_extract(m.data, '$.tokens.output')),    0) AS output_tokens,
+                COALESCE(SUM(json_extract(m.data, '$.tokens.reasoning')), 0) AS reasoning_tokens,
+                COALESCE(SUM(json_extract(m.data, '$.tokens.cache.read')),  0) AS cache_read,
+                COALESCE(SUM(json_extract(m.data, '$.tokens.cache.write')), 0) AS cache_write,
+                COALESCE(SUM(json_extract(m.data, '$.tokens.total')),    0) AS total_tokens,
+                COALESCE(SUM(json_extract(m.data, '$.cost')),            0) AS cost
+            FROM message m
+            LEFT JOIN session s ON m.session_id = s.id
+            WHERE json_extract(m.data, '$.role') = 'assistant'
+              AND json_extract(m.data, '$.tokens.total') IS NOT NULL
+              {time_clause}
+            GROUP BY m.session_id
+            ORDER BY total_tokens DESC
+        """
+        if limit:
+            sql += f" LIMIT {limit}"
+
+        conn = self._connect()
+        try:
+            rows = conn.execute(sql, params).fetchall()
+        finally:
+            conn.close()
+
+        return [
+            UsageRow(
+                label=r["label"] or "(untitled)",
+                calls=r["calls"],
+                tokens=TokenStats(
+                    input=r["input_tokens"],
+                    output=r["output_tokens"],
+                    reasoning=r["reasoning_tokens"],
+                    cache_read=r["cache_read"],
+                    cache_write=r["cache_write"],
+                    total=r["total_tokens"],
+                ),
+                cost=r["cost"],
+            )
+            for r in rows
+        ]
+
+    def totals(
+        self,
+        since: datetime | None = None,
+        until: datetime | None = None,
+    ) -> UsageRow:
+        """Return a single aggregated row for the period."""
+        rows = self._base_query(
+            group_expr="'total'",
+            since=since,
+            until=until,
+        )
+        if rows:
+            return rows[0]
+        return UsageRow(label="total")
+
+    def to_dicts(self, rows: list[UsageRow]) -> list[dict[str, Any]]:
+        """Serialize rows for JSON output."""
+        result = []
+        for r in rows:
+            d: dict[str, Any] = {
+                "label": r.label,
+                "calls": r.calls,
+                "tokens": {
+                    "input": r.tokens.input,
+                    "output": r.tokens.output,
+                    "reasoning": r.tokens.reasoning,
+                    "cache_read": r.tokens.cache_read,
+                    "cache_write": r.tokens.cache_write,
+                    "total": r.tokens.total,
+                },
+                "cost": round(r.cost, 4),
+            }
+            if r.detail is not None:
+                d["model"] = r.detail
+            result.append(d)
+        return result

opencode_usage-0.1.0/src/opencode_usage/render.py

@@ -0,0 +1,222 @@
+"""Rich table rendering for usage stats."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from .db import UsageRow
+
+console = Console()
+
+
+def configure_console(*, no_color: bool = False) -> None:
+    """Reconfigure the module-level console (e.g. for --no-color)."""
+    global console
+    console = Console(no_color=no_color)
+
+
+def _fmt_tokens(n: int) -> str:
+    """Human-readable token count."""
+    if n >= 1_000_000_000:
+        return f"{n / 1_000_000_000:.1f}B"
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n / 1_000:.1f}K"
+    return str(n)
+
+
+def _fmt_cost(c: float) -> str:
+    if c == 0:
+        return "-"
+    if c < 0.01:
+        return f"${c:.4f}"
+    return f"${c:.2f}"
+
+
+_SPARK_CHARS = "▁▂▃▄▅▆▇█"
+
+
+def _spark_bar(value: int, max_value: int) -> str:
+    """Single-character bar proportional to value/max."""
+    if max_value <= 0 or value <= 0:
+        return "▁"
+    level = min(int(value / max_value * 7), 7)
+    return _SPARK_CHARS[level]
+
+
+def _fmt_delta(pct: float) -> str:
+    """Format a percentage delta with color and arrow."""
+    if pct > 0:
+        return f"[red]↑{pct:.0f}%[/]"
+    if pct < 0:
+        return f"[green]↓{abs(pct):.0f}%[/]"
+    return "[dim]→0%[/]"
+
+
+def _short_model(name: str) -> str:
+    """Abbreviate common model names to save table width."""
+    import re
+
+    # Strip vendor prefix: "vendor-variant-1-2-20251016" → "variant-1-2"
+    m = re.match(r"\w+-([a-z]\w+)-(\d+-\d+)(?:-\d+)?$", name)
+    if m:
+        return f"{m.group(1)}-{m.group(2)}"
+
+    # gemini-3-pro-preview → gemini-3-pro
+    name = re.sub(r"-preview$", "", name)
+    # grok-code-fast-1 → grok-fast-1
+    name = name.replace("grok-code-", "grok-")
+    # minimax-m2.5-free → minimax-m2.5
+    name = re.sub(r"-free$", "", name)
+    return name
+
+
+def _make_table(
+    title: str,
+    label_header: str,
+    rows: list[UsageRow],
+    show_breakdown: bool = True,
+    show_detail: str | None = None,
+    trend_values: list[int] | None = None,
+    deltas: list[float | None] | None = None,
+) -> Table:
+    table = Table(
+        title=title,
+        show_header=True,
+        header_style="bold cyan",
+        border_style="dim",
+        title_style="bold white",
+        pad_edge=True,
+    )
+
+    label_max = 24 if show_detail else 30
+    detail_max = 18 if show_detail else 0
+    table.add_column(label_header, style="bold", no_wrap=True, max_width=label_max)
+    if show_detail:
+        table.add_column(show_detail, style="dim cyan", no_wrap=True, max_width=detail_max)
+    table.add_column("Calls", justify="right", style="magenta", min_width=5)
+    if show_breakdown:
+        table.add_column("Input", justify="right", style="green", min_width=6)
+        table.add_column("Output", justify="right", style="yellow", min_width=6)
+        table.add_column("Cache R", justify="right", style="dim", min_width=6)
+        table.add_column("Cache W", justify="right", style="dim", min_width=6)
+    table.add_column("Total", justify="right", style="bold white", min_width=7)
+    table.add_column("Cost", justify="right", style="bold red", min_width=7)
+    if trend_values is not None:
+        table.add_column("Trend", justify="center", style="cyan", no_wrap=True)
+    if deltas is not None:
+        table.add_column("Δ", justify="right", min_width=6)
+
+    # Precompute max for sparkline
+    trend_max = max(trend_values) if trend_values else 0
+
+    # Track previous label for deduplication + group separators
+    prev_label = None
+    for _i, r in enumerate(rows):
+        # Insert blank separator between agent groups
+        if show_detail and prev_label is not None and r.label != prev_label:
+            table.add_section()
+
+        display_label = r.label if r.label != prev_label else ""
+        prev_label = r.label
+
+        cols: list[str] = [display_label]
+        if show_detail:
+            cols.append(_short_model(r.detail) if r.detail else "")
+        cols.append(str(r.calls))
+        if show_breakdown:
+            cols.extend(
+                [
+                    _fmt_tokens(r.tokens.input),
+                    _fmt_tokens(r.tokens.output),
+                    _fmt_tokens(r.tokens.cache_read),
+                    _fmt_tokens(r.tokens.cache_write),
+                ]
+            )
+        cols.extend([_fmt_tokens(r.tokens.total), _fmt_cost(r.cost)])
+        if trend_values is not None:
+            tv = trend_values[_i] if _i < len(trend_values) else 0
+            cols.append(_spark_bar(tv, trend_max))
+        if deltas is not None:
+            d = deltas[_i] if _i < len(deltas) else None
+            cols.append(_fmt_delta(d) if d is not None else "[dim]-[/]")
+        table.add_row(*cols)
+
+    return table
+
+
+def render_summary(
+    total: UsageRow,
+    period: str,
+    prev_total: UsageRow | None = None,
+) -> None:
+    """Print a one-line summary panel."""
+    text = Text()
+    text.append("  Calls: ", style="dim")
+    text.append(f"{total.calls:,}", style="bold magenta")
+    if prev_total is not None and prev_total.calls > 0:
+        pct = (total.calls - prev_total.calls) / prev_total.calls * 100
+        text.append(Text.from_markup(f" {_fmt_delta(pct)}"))
+    text.append("  │  Tokens: ", style="dim")
+    text.append(_fmt_tokens(total.tokens.total), style="bold white")
+    if prev_total is not None and prev_total.tokens.total > 0:
+        pct = (total.tokens.total - prev_total.tokens.total) / prev_total.tokens.total * 100
+        text.append(Text.from_markup(f" {_fmt_delta(pct)}"))
+    text.append("  │  Cost: ", style="dim")
+    text.append(_fmt_cost(total.cost), style="bold red")
+    if prev_total is not None and prev_total.cost > 0:
+        pct = (total.cost - prev_total.cost) / prev_total.cost * 100
+        text.append(Text.from_markup(f" {_fmt_delta(pct)}"))
+    console.print(Panel(text, title=f"[bold]OpenCode Usage — {period}[/bold]", border_style="blue"))
+
+
+def render_daily(rows: list[UsageRow], period: str) -> None:
+    """Render the daily breakdown table."""
+    trend = [r.tokens.total for r in rows]
+    table = _make_table(
+        title=f"Daily Usage ({period})",
+        label_header="Date",
+        rows=rows,
+        show_breakdown=True,
+        trend_values=trend,
+    )
+    console.print(table)
+
+
+def render_grouped(
+    rows: list[UsageRow],
+    group_by: str,
+    period: str,
+    deltas: list[float | None] | None = None,
+) -> None:
+    """Render a grouped breakdown table."""
+    label_map = {
+        "model": "Model",
+        "agent": "Agent",
+        "provider": "Provider",
+        "session": "Session",
+    }
+    label_header = label_map.get(group_by, group_by.title())
+
+    # Agent view has extra Model column — skip breakdown to save width
+    show_breakdown = group_by not in ("session", "agent")
+
+    # For agent view, show model as an extra column
+    show_detail = "Model" if group_by == "agent" else None
+
+    table = _make_table(
+        title=f"Usage by {label_header} ({period})",
+        label_header=label_header,
+        rows=rows,
+        show_breakdown=show_breakdown,
+        show_detail=show_detail,
+        deltas=deltas,
+    )
+    console.print(table)