g3usage 0.1.0 → 0.2.0

package/README.md

@@ -1,92 +1,392 @@
-# g3usage
+<div align="center">
 
-**ccusage for Grok Build** — analyze local Grok Build token usage and estimate costs.
+<img src="assets/logo.png" alt="G3usage" width="180" />
+
+# <img src="assets/icon.png" alt="" width="42" height="42" align="absmiddle" /> G3usage
+
+### ccusage — but for **Grok Build**
+
+<p>
+  <img src="assets/icon-64.png" alt="" width="20" height="20" align="absmiddle" />
+  &nbsp;<strong>npm package</strong>
+  <code><a href="https://www.npmjs.com/package/g3usage">g3usage</a></code>
+</p>
+
+Local CLI that turns your `~/.grok` session logs into **daily / weekly / monthly / session** reports with estimated tokens & API-equivalent cost.
+
+<br />
+
+[![npm version](https://img.shields.io/npm/v/g3usage?color=111827&labelColor=f9fafb&style=for-the-badge)](https://www.npmjs.com/package/g3usage)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Bun](https://img.shields.io/badge/bun-%3E%3D1.0-fbf0df?style=for-the-badge&logo=bun&logoColor=black)](https://bun.sh)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
+[![Zero deps](https://img.shields.io/badge/dependencies-0-success?style=for-the-badge)](#-features)
+
+<br />
+
+```bash
+npx g3usage@latest
+# or
+bunx g3usage@latest
+```
+
+</div>
+
+---
+
+## Why G3usage?
+
+If you use [Grok Build](https://x.ai/build) heavily, you eventually want the same visibility [ccusage](https://github.com/ccusage/ccusage) gives Claude / Codex users:
+
+| Question | G3usage answer |
+|----------|----------------|
+| How many tokens did I burn this week? | `g3usage weekly` |
+| Which days were expensive? | `g3usage daily` |
+| Which session ate my context? | `g3usage session` |
+| What would this cost on the public API? | Cost column (API-equivalent) |
+| Does any of this leave my machine? | **No** — 100% local |
+
+---
+
+## Features
+
+- **Local only** — reads `~/.grok/sessions`, never uploads usage
+- **ccusage-style reports** — `daily` · `weekly` · `monthly` · `session`
+- **JSON export** — pipe into scripts, dashboards, Notion, whatever
+- **Date filters & timezones** — `--since` / `--until` / `--timezone`
+- **Model-aware pricing** — Grok 4.5, Composer 2.5 Fast/Standard, grok-build, …
+- **Zero runtime dependencies** — single small npm package (~10 KB)
+- **Node & Bun** — `npx` / `bunx` / global install, same binary
+
+---
 
 ## Quick start
 
+### Run without installing
+
+**npm / Node**
+
 ```bash
 npx g3usage@latest
+npx g3usage@latest daily
+npx g3usage@latest session --json
+```
+
+**Bun** (same package, native runtime)
+
+```bash
+bunx g3usage@latest
+bunx g3usage@latest daily
+bunx g3usage@latest monthly
+bunx g3usage@latest session --json
 ```
 
-Or install globally:
+### Install globally
 
 ```bash
+# npm
 npm install -g g3usage
+
+# bun
+bun install -g g3usage
+
 g3usage
-g3usage monthly
-g3usage session --json
+g3usage weekly
+g3usage session -s 2026-03-01
 ```
 
-From this repo (dev):
+### From source
 
 ```bash
+git clone https://github.com/GhaythBenAbid/G3usage.git
+cd G3usage
+
+# Node
 node bin/g3usage.js daily
+
+# Bun
+bun bin/g3usage.js daily
+# or
+bun run start:bun -- daily
 ```
 
-## What it does
+Requires **Node.js 18+** or **Bun 1.0+**. Zero dependencies either way.
 
-Reads **local** session logs from:
+---
 
-```
-$GROK_HOME/sessions/*/*/   # default: ~/.grok/sessions/
-```
+## Example output
+
+_Sample only — dummy numbers, not real usage._
 
-For each session it uses:
+```text
+╭───────────────────────────────────────────────────────────╮
+│ Grok Build Usage Report - Daily                           │
+╰───────────────────────────────────────────────────────────╯
 
-| File | Role |
-|------|------|
-| `updates.jsonl` | `_meta.totalTokens` (cumulative context size per event) |
-| `summary.json` | session id, cwd, title, model, timestamps |
-| `signals.json` | models used, context peak fallback |
+┌────────────┬──────────────────────────────────┬───────────┬──────────┬───────────┬──────────┬────────────┐
+│ Date       │ Models                           │     Input │   Output │     Total │ Sessions │ Cost (USD) │
+├────────────┼──────────────────────────────────┼───────────┼──────────┼───────────┼──────────┼────────────┤
+│ 2026-03-12 │ grok-4.5                         │   412,500 │   88,200 │   500,700 │        4 │      $1.35 │
+│ 2026-03-13 │ grok-4.5, grok-composer-2.5-fast │   980,000 │  210,000 │ 1,190,000 │        7 │      $5.12 │
+│ 2026-03-14 │ grok-composer-2.5-fast           │   256,000 │   64,000 │   320,000 │        3 │      $1.73 │
+├────────────┼──────────────────────────────────┼───────────┼──────────┼───────────┼──────────┼────────────┤
+│ Total      │ grok-4.5, grok-composer-2.5-fast │ 1,648,500 │  362,200 │ 2,010,700 │       14 │      $8.20 │
+└────────────┴──────────────────────────────────┴───────────┴──────────┴───────────┴──────────┴────────────┘
 
-Nothing is uploaded. Same idea as [ccusage](https://github.com/ccusage/ccusage), scoped to Grok Build only.
+  Costs are API-equivalent estimates. SuperGrok / subscription usage may not bill per token.
+  Input/Output estimated from cumulative context sizes in local session logs.
+```
+
+> Numbers above are **fake demo data** for the README. Run `npx g3usage@latest` to see your own local totals.
+
+---
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `daily` (default) | Group by date |
-| `weekly` | Group by ISO week |
-| `monthly` | Group by month |
-| `session` | One row per session |
+| Command | Description | Example |
+|---------|-------------|---------|
+| `daily` | Group usage by calendar day **(default)** | `g3usage` or `g3usage daily` |
+| `weekly` | Group by ISO week (`YYYY-Www`) | `g3usage weekly` |
+| `monthly` | Group by month (`YYYY-MM`) | `g3usage monthly` |
+| `session` | One row per Grok Build session | `g3usage session` |
 
 ### Options
 
+| Flag | Description |
+|------|-------------|
+| `-j`, `--json` | Machine-readable JSON (great for scripts) |
+| `-s`, `--since <date>` | Include from date (`YYYY-MM-DD` or `YYYYMMDD`) |
+| `-u`, `--until <date>` | Include until date (inclusive) |
+| `-z`, `--timezone <tz>` | IANA timezone for day/week/month boundaries (default: system) |
+| `--no-cost` | Hide the cost column |
+| `--path <dir>` | Override Grok home (default: `$GROK_HOME` or `~/.grok`) |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Print version |
+
+### Recipes
+
+```bash
+# Last few days only
+g3usage daily -s 2026-03-01 -u 2026-03-14
+
+# Tokyo calendar days
+g3usage daily -z Asia/Tokyo
+
+# Export all sessions as JSON
+g3usage session --json > sessions.json
+
+# Tokens only, no dollar column
+g3usage monthly --no-cost
+
+# Custom Grok install location
+g3usage --path /path/to/grok-home daily
+```
+
+---
+
+## How it works
+
+### Data source
+
+G3usage walks:
+
+```text
+$GROK_HOME/sessions/<project>/<session-id>/
+├── updates.jsonl    # live stream of session updates (+ totalTokens)
+├── summary.json     # id, cwd, title, model, timestamps
+└── signals.json     # models used, context peak, latency stats
+```
+
+Default home:
+
+```text
+~/.grok          # or $GROK_HOME if set
+```
+
+Nothing is sent to the network. Pricing tables are **bundled** in the package (not fetched live).
+
+### Token estimation methodology
+
+Grok Build currently records a **cumulative context size** as `_meta.totalTokens` on session updates — **not** a clean billed split of input / output / cache.
+
+For each user turn (`promptId`), G3usage approximates:
+
+| Metric | Formula | Meaning |
+|--------|---------|---------|
+| **Input** | first `totalTokens` in the turn | Context size when the turn starts |
+| **Output** | `max(0, peak − first)` within the turn | How much the context grew during the turn |
+| **Total** | input + output | Estimated tokens for reporting |
+
+**Caveats (important):**
+
+- Growth includes **tool results**, not only model generations → **output can be an upper bound**
+- Compaction / rewinds can make curves non-monotonic
+- Treat totals as **directional analytics**, not an invoice
+
+### Cost estimation
+
+Costs are **API-equivalent** using published rates (see `src/pricing.js`).
+
+If you authenticate with **SuperGrok / X Premium+**, Grok Build is usually **subscription-based** — you may not pay these per-token rates. The cost column answers:
+
+> “What would this usage roughly cost on public list prices?”
+
+Not:
+
+> “What will my card be charged?”
+
+#### Pricing highlights (per 1M tokens)
+
+| Model | Input | Cached input | Output | Source |
+|-------|------:|-------------:|-------:|--------|
+| `grok-4.5` | $2.00 | $0.50 | $6.00 | [xAI pricing](https://docs.x.ai/developers/pricing) |
+| `grok-4.3` / `grok-4.20-*` | $1.25 | $0.20 | $2.50 | [xAI pricing](https://docs.x.ai/developers/pricing) |
+| `grok-build-0.1` | $1.00 | $0.20 | $2.00 | [xAI Code API](https://docs.x.ai/developers/pricing) |
+| `composer-2.5` / `grok-composer-2.5` | $0.50 | $0.20 | $2.50 | [Cursor Composer 2.5](https://cursor.com/blog/composer-2-5) |
+| **`composer-2.5-fast` / `grok-composer-2.5-fast`** | **$3.00** | **$0.50** | **$15.00** | [Cursor docs](https://cursor.com/docs/models/cursor-composer-2-5) |
+
+> **Fast is ~6× standard** Composer pricing. Fast is the default interactive tier in Cursor product docs — and matches the `*-fast` model ids in Grok Build logs.
+
+Unknown models fall back to **Grok 4.5** rates (`$2 / $6`).
+
+---
+
+## JSON output
+
+```bash
+g3usage daily --json -s 2026-03-12
 ```
--j, --json              JSON output
--s, --since <date>      From date (YYYY-MM-DD or YYYYMMDD)
--u, --until <date>      Until date (inclusive)
--z, --timezone <tz>     IANA timezone for grouping
-    --no-cost           Hide cost column
-    --path <dir>        Grok home override (default ~/.grok)
--h, --help
--v, --version
+
+Shape (simplified):
+
+```json
+{
+  "command": "daily",
+  "timezone": "America/New_York",
+  "grokHome": "/Users/you/.grok",
+  "sessionsPath": "/Users/you/.grok/sessions",
+  "totals": {
+    "inputTokens": 412500,
+    "outputTokens": 88200,
+    "totalTokens": 500700,
+    "cost": 1.35,
+    "models": ["grok-4.5"],
+    "sessions": 4
+  },
+  "rows": [
+    {
+      "key": "2026-03-12",
+      "inputTokens": 412500,
+      "outputTokens": 88200,
+      "totalTokens": 500700,
+      "cost": 1.35,
+      "models": ["grok-4.5"],
+      "sessions": 4
+    }
+  ]
+}
 ```
 
-## Token estimates
+Useful with `jq`:
+
+```bash
+g3usage monthly --json | jq '.totals'
+g3usage session --json | jq '[.rows[] | {title, totalTokens, cost}]'
+```
 
-Grok Build currently logs **cumulative context size** (`totalTokens`), not billed input/output/cache splits.
+---
 
-g3usage estimates per user turn (`promptId`):
+## Environment
 
-- **Input** ≈ first `totalTokens` seen in the turn (context at start)
-- **Output** ≈ growth during the turn (`peak − first`)
+| Variable | Purpose |
+|----------|---------|
+| `GROK_HOME` | Override Grok data directory (default `~/.grok`) |
+| `NO_COLOR` | Disable ANSI colors |
+| `FORCE_COLOR` | Force colors (when supported) |
 
-Growth includes tool results, so output is an **upper-bound** estimate. Treat numbers as directional, not invoices.
+---
 
-## Cost estimates
+## Project layout
 
-Costs use public xAI API rates (see `src/pricing.js`). If you use **SuperGrok / X Premium+** subscription auth, you may not be billed per token — figures are **API-equivalent**.
+```text
+g3usage/
+├── bin/g3usage.js      # CLI entry (npx / global bin)
+├── src/
+│   ├── cli.js          # commands, args, report wiring
+│   ├── load.js         # parse ~/.grok/sessions
+│   ├── aggregate.js    # daily / weekly / monthly / session
+│   ├── pricing.js      # model → $/1M rates
+│   └── table.js        # terminal tables (no deps)
+├── package.json
+└── README.md
+```
 
-## Install
+---
+
+## Comparison
+
+| | [ccusage](https://github.com/ccusage/ccusage) | **G3usage** |
+|--|-----------------------------------------------|-------------|
+| Focus | Many coding agents (Claude, Codex, …) | **Grok Build only** |
+| Data | Agent-specific local logs | `~/.grok/sessions` |
+| Reports | daily / weekly / monthly / session / … | daily / weekly / monthly / session |
+| Network | Optional pricing fetch | Fully offline pricing table |
+| Runtime deps | Full CLI stack | **Zero** |
+
+---
+
+## Limitations & honesty
+
+1. **No true I/O billing logs** in Grok Build yet → input/output are **estimates**
+2. **Cache tokens** are not available in local logs → cache cost usually `$0` in reports
+3. **Subscription users** should treat `$` as **API-equivalent**, not actual spend
+4. **Tool-call fees** (web search, etc. on the public API) are **not** included
+5. Pricing tables can drift — open a PR when xAI / Cursor change rates
+
+---
+
+## Contributing
+
+PRs welcome — especially for:
+
+- Better token math when Grok exposes real usage fields
+- Pricing updates
+- New report modes (e.g. by project path, by model only)
+- Tests & CI
 
 ```bash
-npm install -g .
-# then:
-g3usage
-g3usage session -s 2026-07-01
+node bin/g3usage.js --help
+node bin/g3usage.js daily --json | head
+```
+
+---
+
+## Publish notes (maintainers)
+
+```bash
+npm login
+npm publish --otp=<code>    # 2FA required
+npm version patch && npm publish --otp=<code>
+```
+
+Users always get the latest with:
+
+```bash
+npx g3usage@latest
 ```
 
+---
+
 ## License
 
-MIT
+[MIT](./LICENSE)
+
+---
+
+<div align="center">
+
+**G3usage — built for people who live in the terminal with Grok.**
+
+`npx g3usage@latest`
+
+</div>

package/assets/grok-mark.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" fill="none" role="img" aria-label="Grok">
+  <path d="M395.479 633.828L735.91 381.105C752.599 368.715 776.454 373.548 784.406 392.792C826.26 494.285 807.561 616.253 724.288 699.996C641.016 783.739 525.151 802.104 419.247 760.277L303.556 814.143C469.49 928.202 670.987 899.995 796.901 773.282C896.776 672.843 927.708 535.937 898.785 412.476L899.047 412.739C857.105 231.37 909.358 158.874 1016.4 10.6326C1018.93 7.11771 1021.47 3.60279 1024 0L883.144 141.651V141.212L395.392 633.916" fill="white"/>
+  <path d="M325.226 695.251C206.128 580.84 226.662 403.776 328.285 301.668C403.431 226.097 526.549 195.254 634.026 240.596L749.454 186.994C728.657 171.88 702.007 155.623 671.424 144.2C533.19 86.9942 367.693 115.465 255.323 228.382C147.234 337.081 113.244 504.215 171.613 646.833C215.216 753.423 143.739 828.818 71.7385 904.916C46.2237 931.893 20.6216 958.87 0 987.429L325.139 695.339" fill="white"/>
+</svg>

package/assets/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="G3usage">
+  <rect width="512" height="512" rx="110" fill="#0a0a0a"/>
+  <g transform="translate(64 64) scale(0.375)">
+    <path d="M395.479 633.828L735.91 381.105C752.599 368.715 776.454 373.548 784.406 392.792C826.26 494.285 807.561 616.253 724.288 699.996C641.016 783.739 525.151 802.104 419.247 760.277L303.556 814.143C469.49 928.202 670.987 899.995 796.901 773.282C896.776 672.843 927.708 535.937 898.785 412.476L899.047 412.739C857.105 231.37 909.358 158.874 1016.4 10.6326C1018.93 7.11771 1021.47 3.60279 1024 0L883.144 141.651V141.212L395.392 633.916" fill="white"/>
+    <path d="M325.226 695.251C206.128 580.84 226.662 403.776 328.285 301.668C403.431 226.097 526.549 195.254 634.026 240.596L749.454 186.994C728.657 171.88 702.007 155.623 671.424 144.2C533.19 86.9942 367.693 115.465 255.323 228.382C147.234 337.081 113.244 504.215 171.613 646.833C215.216 753.423 143.739 828.818 71.7385 904.916C46.2237 931.893 20.6216 958.87 0 987.429L325.139 695.339" fill="white"/>
+  </g>
+</svg>

package/assets/logo.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="G3usage">
+  <rect width="512" height="512" rx="110" fill="#0a0a0a"/>
+  <g transform="translate(96 72) scale(0.3125)">
+    <path d="M395.479 633.828L735.91 381.105C752.599 368.715 776.454 373.548 784.406 392.792C826.26 494.285 807.561 616.253 724.288 699.996C641.016 783.739 525.151 802.104 419.247 760.277L303.556 814.143C469.49 928.202 670.987 899.995 796.901 773.282C896.776 672.843 927.708 535.937 898.785 412.476L899.047 412.739C857.105 231.37 909.358 158.874 1016.4 10.6326C1018.93 7.11771 1021.47 3.60279 1024 0L883.144 141.651V141.212L395.392 633.916" fill="white"/>
+    <path d="M325.226 695.251C206.128 580.84 226.662 403.776 328.285 301.668C403.431 226.097 526.549 195.254 634.026 240.596L749.454 186.994C728.657 171.88 702.007 155.623 671.424 144.2C533.19 86.9942 367.693 115.465 255.323 228.382C147.234 337.081 113.244 504.215 171.613 646.833C215.216 753.423 143.739 828.818 71.7385 904.916C46.2237 931.893 20.6216 958.87 0 987.429L325.139 695.339" fill="white"/>
+  </g>
+  <text x="256" y="430" text-anchor="middle" font-family="Helvetica Neue, Helvetica, Arial, sans-serif" font-size="52" font-weight="700" fill="#f5f5f5">G3usage</text>
+</svg>

package/bin/g3usage.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+/**
+ * Works with Node.js (npx / npm) and Bun (bunx / bun run).
+ * Bun is a Node-compatible runtime — same entry point, zero deps.
+ */
 import { main } from "../src/cli.js";
 
 main(process.argv.slice(2)).catch((err) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "g3usage",
-  "version": "0.1.0",
-  "description": "Analyze Grok Build token usage and estimated costs from local session data (ccusage for Grok)",
+  "version": "0.2.0",
+  "description": "G3usage — analyze Grok Build token usage and estimated costs from local session data (ccusage for Grok)",
   "type": "module",
   "bin": {
     "g3usage": "bin/g3usage.js"
@@ -9,15 +9,19 @@
   "files": [
     "bin",
     "src",
+    "assets",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "start": "node bin/g3usage.js",
+    "start:bun": "bun bin/g3usage.js",
+    "g3usage": "node bin/g3usage.js",
     "prepublishOnly": "node bin/g3usage.js --version"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=18",
+    "bun": ">=1.0.0"
   },
   "keywords": [
     "grok",
@@ -27,16 +31,18 @@
     "tokens",
     "cli",
     "ccusage",
-    "cost"
+    "cost",
+    "bun",
+    "bunx"
   ],
   "author": "",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/YOUR_USER/g3usage.git"
+    "url": "git+https://github.com/GhaythBenAbid/G3usage.git"
   },
   "bugs": {
-    "url": "https://github.com/YOUR_USER/g3usage/issues"
+    "url": "https://github.com/GhaythBenAbid/G3usage/issues"
   },
-  "homepage": "https://github.com/YOUR_USER/g3usage#readme"
+  "homepage": "https://github.com/GhaythBenAbid/G3usage#readme"
 }

package/src/cli.js

@@ -15,14 +15,17 @@ import {
   c,
 } from "./table.js";
 
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 
 const HELP = `
-${c.bold("g3usage")} — Grok Build usage analysis (ccusage for Grok)
+${c.bold("G3usage")} — Grok Build usage analysis (ccusage for Grok)
+  npm package / CLI: g3usage  ·  Node & Bun
 
 ${c.bold("USAGE")}
   g3usage [daily] [options]
   g3usage <command> [options]
+  npx g3usage@latest
+  bunx g3usage@latest
 
 ${c.bold("COMMANDS")}
   daily      Show usage grouped by date (default)
@@ -191,10 +194,10 @@ function alignFor(mode, noCost) {
 function printReport(mode, rows, opts) {
   const t = totals(rows);
   const titleMap = {
-    daily: "Grok Build Usage Report - Daily",
-    weekly: "Grok Build Usage Report - Weekly",
-    monthly: "Grok Build Usage Report - Monthly",
-    session: "Grok Build Usage Report - Session",
+    daily: "G3usage · Grok Build — Daily",
+    weekly: "G3usage · Grok Build — Weekly",
+    monthly: "G3usage · Grok Build — Monthly",
+    session: "G3usage · Grok Build — Session",
   };
 
   const headers = headersFor(mode, opts.noCost);