cctrack-ai 0.2.0__tar.gz → 0.3.0__tar.gz

{cctrack_ai-0.2.0 → cctrack_ai-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cctrack-ai
-Version: 0.2.0
+Version: 0.3.0
 Summary: Track and analyze AI token usage from Claude Code and other CLI agents
 Project-URL: Homepage, https://github.com/Sk786/cctrack
 Project-URL: Bug Tracker, https://github.com/Sk786/cctrack/issues
@@ -28,9 +28,11 @@ Description-Content-Type: text/markdown
 
 # cctrack
 
-Track and analyze your AI token usage from Claude Code and other CLI agents — directly in the terminal.
+Know your AI activity. Keep it local. Share a heatmap.
 
-No API key needed. Reads local session files, stores in SQLite, shows cost breakdowns with charts.
+`cctrack` tracks AI usage from Claude Code and OpenAI, then turns it into useful terminal reports and a GitHub-style activity heatmap. Claude Code tracking reads local session files—no account or API key required. Export a heatmap as SVG for your profile or README.
+
+**Local-first:** your session history stays on your machine. No account or upload is required to use the CLI.
 
 ```
 $ cctrack today
@@ -54,13 +56,25 @@ pip install cctrack-ai
 Or from source:
 
 ```bash
-git clone https://github.com/yourusername/cctrack
+git clone https://github.com/Sk786/cctrack.git
 cd cctrack
 pip install -e .
 ```
 
 ## Commands
 
+### `cctrack heatmap`
+See your AI activity across the last year, directly in the terminal. The default intensity is total tokens; choose estimated spend or active days instead.
+
+```bash
+cctrack heatmap
+cctrack heatmap --metric cost --days 90
+cctrack heatmap --metric active-days
+cctrack heatmap --output ~/ai-activity.svg
+```
+
+The exported SVG contains dates and relative activity levels only—never prompts or project names. It is generated locally and is not uploaded anywhere. Heatmap intensity is a picture of usage, not a productivity score.
+
 ### `cctrack today`
 Token usage and cost for the current day, broken down by model. Includes a stacked token-type chart.
 
@@ -183,8 +197,8 @@ $ cctrack prices
 ┃ Model              ┃  Input ┃ Output ┃ Cache Write ┃ Cache Read ┃
 ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
 │ claude-sonnet-4-6  │  $3.00 │ $15.00 │       $3.75 │      $0.30 │
-│ claude-opus-4-8    │ $15.00 │ $75.00 │      $18.75 │      $1.50 │
-│ claude-haiku-4-5   │  $0.80 │  $4.00 │       $1.00 │      $0.08 │
+│ claude-opus-4-8    │  $5.00 │ $25.00 │       $6.25 │      $0.50 │
+│ claude-haiku-4-5   │  $1.00 │  $5.00 │       $1.25 │      $0.10 │
 │ default (fallback) │  $3.00 │ $15.00 │       $3.75 │      $0.30 │
 └────────────────────┴────────┴────────┴─────────────┴────────────┘
 
@@ -236,7 +250,7 @@ cctrack-prompt --format cost    # [CC $5.43]
 2. `cctrack` parses these files and stores token counts in `~/.config/cctrack/usage.db`
 3. All commands query SQLite — fast and offline
 
-No API key needed. Everything is local.
+Claude Code tracking and local reports work offline. OpenAI usage can be imported on demand with `cctrack openai-sync` and requires an OpenAI organization API key. The CLI does not upload local transcripts.
 
 ## Customizing Prices
 
@@ -263,9 +277,11 @@ All cost values are color coded consistently across every command:
 
 ## Roadmap
 
-- **v0.2** — Codex / OpenAI support via the Usage API
-- **v0.3** — Gemini CLI support
-- **v0.4** — Budget alerts and weekly digest
+- **Available** — Claude Code tracking, OpenAI Usage API import, reports, and local activity heatmap/SVG export
+- **Exploring** — Opt-in shareable profiles and private team boards
+- **Future** — More local AI usage sources based on demand
+
+Product site: [cctrack.sandeepk.dev](https://cctrack.sandeepk.dev/)
 
 ## License
 

{cctrack_ai-0.2.0 → cctrack_ai-0.3.0}/README.md

@@ -1,8 +1,10 @@
 # cctrack
 
-Track and analyze your AI token usage from Claude Code and other CLI agents — directly in the terminal.
+Know your AI activity. Keep it local. Share a heatmap.
 
-No API key needed. Reads local session files, stores in SQLite, shows cost breakdowns with charts.
+`cctrack` tracks AI usage from Claude Code and OpenAI, then turns it into useful terminal reports and a GitHub-style activity heatmap. Claude Code tracking reads local session files—no account or API key required. Export a heatmap as SVG for your profile or README.
+
+**Local-first:** your session history stays on your machine. No account or upload is required to use the CLI.
 
 ```
 $ cctrack today
@@ -26,13 +28,25 @@ pip install cctrack-ai
 Or from source:
 
 ```bash
-git clone https://github.com/yourusername/cctrack
+git clone https://github.com/Sk786/cctrack.git
 cd cctrack
 pip install -e .
 ```
 
 ## Commands
 
+### `cctrack heatmap`
+See your AI activity across the last year, directly in the terminal. The default intensity is total tokens; choose estimated spend or active days instead.
+
+```bash
+cctrack heatmap
+cctrack heatmap --metric cost --days 90
+cctrack heatmap --metric active-days
+cctrack heatmap --output ~/ai-activity.svg
+```
+
+The exported SVG contains dates and relative activity levels only—never prompts or project names. It is generated locally and is not uploaded anywhere. Heatmap intensity is a picture of usage, not a productivity score.
+
 ### `cctrack today`
 Token usage and cost for the current day, broken down by model. Includes a stacked token-type chart.
 
@@ -155,8 +169,8 @@ $ cctrack prices
 ┃ Model              ┃  Input ┃ Output ┃ Cache Write ┃ Cache Read ┃
 ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
 │ claude-sonnet-4-6  │  $3.00 │ $15.00 │       $3.75 │      $0.30 │
-│ claude-opus-4-8    │ $15.00 │ $75.00 │      $18.75 │      $1.50 │
-│ claude-haiku-4-5   │  $0.80 │  $4.00 │       $1.00 │      $0.08 │
+│ claude-opus-4-8    │  $5.00 │ $25.00 │       $6.25 │      $0.50 │
+│ claude-haiku-4-5   │  $1.00 │  $5.00 │       $1.25 │      $0.10 │
 │ default (fallback) │  $3.00 │ $15.00 │       $3.75 │      $0.30 │
 └────────────────────┴────────┴────────┴─────────────┴────────────┘
 
@@ -208,7 +222,7 @@ cctrack-prompt --format cost    # [CC $5.43]
 2. `cctrack` parses these files and stores token counts in `~/.config/cctrack/usage.db`
 3. All commands query SQLite — fast and offline
 
-No API key needed. Everything is local.
+Claude Code tracking and local reports work offline. OpenAI usage can be imported on demand with `cctrack openai-sync` and requires an OpenAI organization API key. The CLI does not upload local transcripts.
 
 ## Customizing Prices
 
@@ -235,9 +249,11 @@ All cost values are color coded consistently across every command:
 
 ## Roadmap
 
-- **v0.2** — Codex / OpenAI support via the Usage API
-- **v0.3** — Gemini CLI support
-- **v0.4** — Budget alerts and weekly digest
+- **Available** — Claude Code tracking, OpenAI Usage API import, reports, and local activity heatmap/SVG export
+- **Exploring** — Opt-in shareable profiles and private team boards
+- **Future** — More local AI usage sources based on demand
+
+Product site: [cctrack.sandeepk.dev](https://cctrack.sandeepk.dev/)
 
 ## License
 

{cctrack_ai-0.2.0 → cctrack_ai-0.3.0}/cctrack/display.py

@@ -409,6 +409,7 @@ def render_setup_guide(projects_dir: str, db_path: str, prices_path: str, user_p
     cmds = [
         ("cctrack today",        "Token usage for today"),
         ("cctrack weekly",       "Last 7 days breakdown + bar chart"),
+        ("cctrack heatmap",      "AI activity calendar + shareable SVG export"),
         ("cctrack stats",        "All-time summary by model"),
         ("cctrack projects",     "Usage broken down by project"),
         ("cctrack prices",       "Show model pricing"),

cctrack_ai-0.3.0/cctrack/heatmap.py

@@ -0,0 +1,200 @@
+"""Daily usage aggregation and GitHub-style activity heatmaps."""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+from html import escape
+from pathlib import Path
+
+from rich.text import Text
+
+from .config import get_pricing
+
+METRICS = ("tokens", "cost", "active-days")
+_LEVEL_COLORS = ("#161b22", "#0e4429", "#006d32", "#26a641", "#39d353")
+_LEVEL_STYLES = ("#484f58", "#3fb950", "#3fb950", "#56d364", "#7ee787")
+
+
+def aggregate_daily(rows: list[dict], metric: str = "tokens") -> dict[date, float]:
+    """Aggregate stored usage rows into a date -> metric value mapping."""
+    if metric not in METRICS:
+        raise ValueError(f"metric must be one of: {', '.join(METRICS)}")
+
+    values: dict[date, float] = {}
+    prices_by_model: dict[str, dict[str, float]] = {}
+    for row in rows:
+        day = date.fromisoformat(row["timestamp"][:10])
+        tokens = sum(
+            row.get(key, 0)
+            for key in ("input_tokens", "output_tokens", "cache_write_tokens", "cache_read_tokens")
+        )
+        if metric == "tokens":
+            amount = tokens
+        elif metric == "cost":
+            model = row["model"]
+            if model not in prices_by_model:
+                prices_by_model[model], _ = get_pricing(model)
+            prices = prices_by_model[model]
+            amount = (
+                row.get("input_tokens", 0) * prices["input"]
+                + row.get("output_tokens", 0) * prices["output"]
+                + row.get("cache_write_tokens", 0) * prices["cache_write"]
+                + row.get("cache_read_tokens", 0) * prices["cache_read"]
+            ) / 1_000_000
+        else:
+            amount = 1 if tokens > 0 else 0
+        if metric == "active-days":
+            values[day] = float(bool(values.get(day, 0) or amount))
+        else:
+            values[day] = values.get(day, 0) + amount
+
+    return values
+
+
+def _levels(values: dict[date, float]) -> dict[date, int]:
+    """Map values to zero plus four relative-intensity levels."""
+    active = sorted(value for value in values.values() if value > 0)
+    if not active:
+        return {day: 0 for day in values}
+
+    result = {}
+    for day, value in values.items():
+        if value <= 0:
+            result[day] = 0
+        else:
+            rank = sum(item <= value for item in active) / len(active)
+            result[day] = min(4, max(1, int(rank * 4)))
+    return result
+
+
+def _calendar(start: date, end: date) -> tuple[date, list[list[date]]]:
+    first_monday = start - timedelta(days=start.weekday())
+    weeks: list[list[date]] = []
+    current = first_monday
+    while current <= end:
+        weeks.append([current + timedelta(days=offset) for offset in range(7)])
+        current += timedelta(days=7)
+    return first_monday, weeks
+
+
+def _metric_total(values: dict[date, float], metric: str) -> str:
+    if metric == "tokens":
+        return f"{sum(values.values()):,.0f} tokens"
+    if metric == "cost":
+        return f"${sum(values.values()):,.2f} estimated spend"
+    return f"{sum(value > 0 for value in values.values())} active days"
+
+
+def render_heatmap(
+    values: dict[date, float], start: date, end: date, metric: str = "tokens"
+) -> Text:
+    """Render a compact, accessible-in-terminal activity grid."""
+    _, weeks = _calendar(start, end)
+    level_by_day = _levels(values)
+    output = Text()
+    output.append(f"AI activity · {start:%b %d, %Y} – {end:%b %d, %Y}\n", style="bold")
+    output.append(f"{_metric_total(values, metric)} · relative intensity\n\n", style="dim")
+
+    month_labels = [" "] * len(weeks)
+    previous_month: tuple[int, int] | None = None
+    for column, week in enumerate(weeks):
+        visible_day = next((day for day in week if start <= day <= end), None)
+        if visible_day and (visible_day.year, visible_day.month) != previous_month:
+            for offset, char in enumerate(visible_day.strftime("%b")):
+                if column + offset < len(month_labels):
+                    month_labels[column + offset] = char
+            previous_month = (visible_day.year, visible_day.month)
+
+    output.append("    ")
+    output.append("".join(month_labels))
+    output.append("\n")
+
+    for weekday, label in enumerate(("Mo", "Tu", "We", "Th", "Fr", "Sa", "Su")):
+        output.append(f"{label}  ", style="dim")
+        for week in weeks:
+            day = week[weekday]
+            if day < start or day > end:
+                output.append(" ")
+                continue
+            level = level_by_day.get(day, 0)
+            output.append("■", style=_LEVEL_STYLES[level])
+        output.append("\n")
+
+    output.append("\nLess ", style="dim")
+    for level in range(5):
+        output.append("■", style=_LEVEL_STYLES[level])
+        output.append(" ")
+    output.append("More  ·  ", style="dim")
+    output.append(metric, style="bold")
+    return output
+
+
+def export_svg(
+    values: dict[date, float], start: date, end: date, metric: str, path: Path
+) -> Path:
+    """Write a self-contained SVG heatmap and return its path."""
+    _, weeks = _calendar(start, end)
+    level_by_day = _levels(values)
+    cell = 12
+    gap = 3
+    step = cell + gap
+    left = 42
+    top = 42
+    width = left + len(weeks) * step + 8
+    height = top + 7 * step + 54
+    months: list[str] = []
+    prev_month = None
+    for column, week in enumerate(weeks):
+        month_day = next((day for day in week if start <= day <= end), None)
+        if month_day and (month_day.year, month_day.month) != prev_month:
+            months.append(
+                f'<text x="{left + column * step}" y="{top - 12}" class="month">{month_day:%b}</text>'
+            )
+            prev_month = (month_day.year, month_day.month)
+
+    cells: list[str] = []
+    for column, week in enumerate(weeks):
+        for weekday, day in enumerate(week):
+            if day < start or day > end:
+                continue
+            level = level_by_day.get(day, 0)
+            x = left + column * step
+            y = top + weekday * step
+            tooltip = "no activity" if level == 0 else f"intensity {level} of 4"
+            cells.append(
+                f'<rect x="{x}" y="{y}" width="{cell}" height="{cell}" rx="3" '
+                f'fill="{_LEVEL_COLORS[level]}"><title>{day.isoformat()}: {tooltip}</title></rect>'
+            )
+
+    weekdays = "".join(
+        f'<text x="0" y="{top + i * step + 10}" class="weekday">{name}</text>'
+        for i, name in enumerate(("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"))
+    )
+    title = f"AI activity · {start:%b %d, %Y} – {end:%b %d, %Y}"
+    description = f"Selected metric: {metric}. Color shows relative daily activity intensity."
+    legend_y = top + 7 * step + 15
+    legend = (
+        f'<text x="{left}" y="{legend_y + 9}" class="legend-label">Less</text>'
+        + "".join(
+            f'<rect x="{left + 34 + level * 16}" y="{legend_y}" width="11" height="11" '
+            f'rx="3" fill="{_LEVEL_COLORS[level]}"/>'
+            for level in range(5)
+        )
+        + f'<text x="{left + 122}" y="{legend_y + 9}" class="legend-label">More</text>'
+    )
+    svg = f'''<svg xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="svg-title svg-desc"
+  viewBox="0 0 {width} {height}" width="{width}" height="{height}">
+  <title id="svg-title">{escape(title)}</title>
+  <desc id="svg-desc">{escape(description)}</desc>
+  <style>text {{ font-family: system-ui, sans-serif; fill: #c9d1d9; }}
+    .title {{ font-size: 14px; font-weight: 650; }} .subtitle {{ font-size: 11px; fill: #8b949e; }}
+    .month {{ font-size: 10px; fill: #8b949e; }} .weekday {{ font-size: 9px; fill: #8b949e; }}
+    .legend-label {{ font-size: 9px; fill: #8b949e; }}</style>
+  <rect width="100%" height="100%" rx="12" fill="#0d1117"/>
+  <text x="0" y="16" class="title">{escape(title)}</text>
+  <text x="0" y="32" class="subtitle">{escape(description)}</text>
+  {''.join(months)}{weekdays}{''.join(cells)}{legend}
+</svg>'''
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(svg, encoding="utf-8")
+    return path

{cctrack_ai-0.2.0 → cctrack_ai-0.3.0}/cctrack/main.py

@@ -1,4 +1,5 @@
 from datetime import date, timedelta
+from pathlib import Path
 
 import typer
 
@@ -9,6 +10,7 @@ from .config import (
 )
 from .storage import sync, query_range, query_all, query_by_project, get_date_bounds, get_db_path, query_today_totals
 from .stats import summarize_rows, daily_breakdown
+from .heatmap import METRICS, aggregate_daily, export_svg, render_heatmap
 from .display import (
     console,
     render_today_table,
@@ -27,7 +29,7 @@ from .display import (
 
 from rich.table import Table
 
-app = typer.Typer(help="Track AI token usage from Claude Code and other CLI agents.")
+app = typer.Typer(help="Track AI usage and visualize your activity.")
 
 
 @app.command()
@@ -107,6 +109,33 @@ def projects(no_chart: bool = typer.Option(False, "--no-chart", help="Skip the p
     print_sync_note(new)
 
 
+@app.command()
+def heatmap(
+    metric: str = typer.Option("tokens", "--metric", help="Heatmap intensity: tokens, cost, or active-days."),
+    days: int = typer.Option(365, "--days", min=1, max=1825, help="History window (1–1825 days)."),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Export a shareable SVG to this path."),
+):
+    """Show your local AI activity heatmap, or export it as an SVG."""
+    if metric not in METRICS:
+        raise typer.BadParameter(f"choose one of: {', '.join(METRICS)}", param_hint="--metric")
+
+    new = sync()
+    end = date.today()
+    start = end - timedelta(days=days - 1)
+    rows = query_range(start, end)
+    values = aggregate_daily(rows, metric)
+
+    if output:
+        saved = export_svg(values, start, end, metric, output)
+        console.print(f"[green]Heatmap saved to {saved}[/green]")
+    else:
+        console.print(render_heatmap(values, start, end, metric))
+
+    if not rows:
+        console.print("[dim]No usage in this period yet. cctrack reads supported local usage data.[/dim]")
+    print_sync_note(new)
+
+
 @app.command()
 def prompt(
     format: str = typer.Option("both", "--format", "-f", help="Output format: 'tokens', 'cost', or 'both'."),

{cctrack_ai-0.2.0 → cctrack_ai-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctrack-ai"
-version = "0.2.0"
+version = "0.3.0"
 description = "Track and analyze AI token usage from Claude Code and other CLI agents"
 readme = "README.md"
 license = { text = "MIT" }

cctrack_ai-0.3.0/site/README.md

@@ -0,0 +1,25 @@
+# Website deployment
+
+The site is a static HTML/CSS landing page in this directory. GitHub Pages serves it
+for free; there is no server, build step, JavaScript framework, or analytics.
+
+## One-time GitHub setup
+
+1. In the repository, open **Settings → Pages**.
+2. Set the build and deployment source to **GitHub Actions**.
+3. Merge the site to `master`; `.github/workflows/website.yml` will deploy it.
+4. Confirm the workflow's Pages environment reports a successful deployment.
+
+The custom domain is stored in `CNAME` as `cctrack.sandeepk.dev`. At the DNS provider
+for `sandeepk.dev` (Squarespace Domains), add a CNAME record:
+
+| Host | Type | Data |
+| --- | --- | --- |
+| `cctrack` | `CNAME` | `sk786.github.io` |
+
+Remove any conflicting record for the `cctrack` host. Once DNS resolves and Pages
+shows the custom domain as verified, enable **Enforce HTTPS** in Settings → Pages.
+DNS propagation and certificate issuance can take some time.
+
+The current preview is deliberately honest about product status: local CLI heatmaps
+are available in this branch; hosted profiles and team boards are not live yet.