repospend 0.0.9 → 0.1.1

package/docs/data-sources.md

@@ -0,0 +1,128 @@
+# Data Sources
+
+RepoSpend only reads local files. It never mutates source client data.
+
+## Codex
+
+RepoSpend reads Codex data from:
+
+- `~/.codex/state_5.sqlite`
+- `~/.codex/sessions`
+
+The Codex adapter opens SQLite in read-only mode and recursively scans session files when the sessions directory exists. Missing files, old schemas, unreadable paths, and missing fields are reported as warnings rather than fatal errors.
+
+When Codex exposes app metadata, RepoSpend also normalizes where usage came from. It reads SQLite/session fields such as `source`, `originator`, and `thread_source`, then displays friendly labels like `VS Code`, `Terminal`, `Codex app`, or `Codex`.
+
+Codex token records can include repeated cumulative checkpoints and per-turn
+usage deltas. RepoSpend prefers `last_token_usage` per-turn deltas when present,
+because Codex can reset cumulative `total_token_usage` after compaction. It also
+keeps cache reads as a sub-bucket of input and separates reasoning output from
+visible output so each billable bucket is counted once.
+
+## Claude Code
+
+RepoSpend scans:
+
+- `~/.claude/projects`
+- `~/.config/claude/projects`
+- `~/Library/Application Support/Claude/local-agent-mode-sessions`
+- `~/.config/Claude/local-agent-mode-sessions`
+
+Claude Code session transcripts are parsed from JSONL files. Useful fields include `sessionId`, `cwd`, `gitBranch`, `timestamp`, `entrypoint`, `message.model`, and `message.usage`. When `message.usage` is present, RepoSpend sums Claude assistant usage records directly. When token counts or model names are absent in a transcript, sessions remain visible with unknown cost.
+
+RepoSpend intentionally includes Claude Desktop/local-agent session roots when
+they exist. Tools such as `ccusage` and Tokscale commonly focus on
+`~/.claude/projects`, so RepoSpend's Claude totals can be higher when local-agent
+sessions are present. In one all-time local audit, RepoSpend's
+`~/.claude/projects` slice matched `ccusage`, while the difference came from
+`~/Library/Application Support/Claude/local-agent-mode-sessions`.
+
+RepoSpend checks `~/.claude/history.jsonl` only for source status/counting. History-only entries are not imported into usage analytics because they do not include reliable token, model, or transcript data.
+
+## GitHub Copilot
+
+RepoSpend scans GitHub Copilot local files:
+
+- `~/.copilot/otel/*.jsonl`
+- the explicit file in `COPILOT_OTEL_FILE_EXPORTER_PATH`
+- `~/.copilot/session-state/*/events.jsonl`
+- VS Code `User/workspaceStorage/*/GitHub.copilot-chat/{transcripts,debug-logs}`
+
+Copilot OpenTelemetry records can include exact input, cached input, cache
+creation, output, and reasoning token fields. RepoSpend imports those directly,
+deduping lower-priority agent summary records when a more specific chat span or
+inference record is present. Copilot CLI session-state files currently expose
+repo context and output-token counts, but not a full input/cache split; RepoSpend
+shows those tokens as partial usage and leaves cost unknown rather than inventing
+missing input. VS Code Copilot Chat transcripts remain visible even when they do
+not contain token data.
+
+## Cursor
+
+Cursor support is experimental and opt-in because local Cursor files vary by
+version, platform, and product surface. Cursor may store useful transcript data
+without exact token or cost fields, and some usage data may only exist in
+account-backed services rather than local files.
+
+RepoSpend scans local Cursor paths such as:
+
+```text
+~/.cursor/
+~/.cursor/chats/
+~/.cursor/projects/
+~/.cursor/projects/*/agent-transcripts/
+~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
+~/Library/Application Support/Cursor/User/workspaceStorage/
+~/.config/Cursor/User/globalStorage/state.vscdb
+~/.config/Cursor/User/workspaceStorage/
+%APPDATA%\Cursor\User\globalStorage\state.vscdb
+%APPDATA%\Cursor\User\workspaceStorage\
+```
+
+RepoSpend prioritizes Cursor JSONL transcripts, then searches local SQLite,
+`.db`, and `.vscdb` files for chat/composer/agent-like JSON blobs. Unknown or
+locked Cursor databases are skipped with warnings. Prompt and response text is
+never uploaded.
+
+If Cursor sessions import with unknown tokens or cost, that usually means the
+local files did not include exact usage data. RepoSpend keeps the session visible
+and avoids guessing.
+
+### Troubleshooting Cursor Import
+
+To inspect what exists locally:
+
+```bash
+find ~/.cursor -type f | grep -E "jsonl|sqlite|db|vscdb|chat|transcript"
+ls -la "$HOME/Library/Application Support/Cursor/User/globalStorage"
+ls -la "$HOME/Library/Application Support/Cursor/User/workspaceStorage"
+```
+
+On Linux, replace the `Library/Application Support` paths with
+`$HOME/.config/Cursor/User/...`. On Windows, check
+`%APPDATA%\Cursor\User\globalStorage` and
+`%APPDATA%\Cursor\User\workspaceStorage`.
+
+The normalized usage shape lives in `packages/types` and is intended to support future adapters for OpenCode, Gemini CLI, and other local assistants.
+
+For details on cache, reasoning, and comparison with tools such as `ccusage` and
+Tokscale, see [token-accounting.md](token-accounting.md).
+
+## RepoSpend-Owned Data
+
+RepoSpend-owned settings are stored separately under `~/.repospend/`:
+
+```text
+~/.repospend/pricing.json
+~/.repospend/config.json
+~/.repospend/cache/
+```
+
+The default editable pricing table is `~/.repospend/pricing.json`; local app
+settings live in `~/.repospend/config.json`. RepoSpend caches parsed session
+summaries under `~/.repospend/cache/` so unchanged large transcripts reload
+faster.
+
+The Settings page includes a reset action for RepoSpend-owned files under
+`~/.repospend/`. It does not delete or edit anything under source client paths
+such as `~/.codex`, `~/.claude`, `~/.copilot`, or Cursor storage directories.

package/docs/llms.txt

@@ -0,0 +1,60 @@
+# RepoSpend
+
+Canonical description:
+RepoSpend is a local-first dashboard for tracking AI coding token usage and API-equivalent spend by repository, session, model, and tool. It supports local Codex, Claude Code, and GitHub Copilot usage data, runs with `npx repospend`, and does not upload prompts, code, transcripts, or usage data.
+
+Canonical URLs:
+- Website: https://repospend.com
+- GitHub: https://github.com/mehmetdemircs/RepoSpend
+- npm: https://www.npmjs.com/package/repospend
+- Package name: repospend
+- Run command: npx repospend
+
+What RepoSpend is:
+- A local-first AI coding token usage dashboard.
+- A repo-level AI coding cost tracker using estimated API-equivalent cost.
+- A dashboard for inspecting AI coding usage by repository, session, model, source tool, day, hour, and token type.
+- A way to compare Codex token usage, Claude Code token usage by repo, and GitHub Copilot local usage data.
+- RTK appears as token-reduction workflow context. RTK is not an AI model or coding assistant.
+- Experimental opt-in Cursor token usage tracking is available when local Cursor data includes usable transcript or token fields.
+
+Privacy guarantees:
+- Runs locally on the user's machine.
+- Binds to localhost for the dashboard/API.
+- Reads supported local source files in read-only mode.
+- Does not upload prompts, code, transcripts, or usage data.
+- Does not require login, telemetry, cloud sync, or an account.
+- Does not modify Codex, Claude Code, GitHub Copilot, Cursor, or RTK files.
+
+Supported tools and data sources:
+- Codex: strongest support; local SQLite/session data, tokens, models, repo grouping, sessions, command friction.
+- Claude Code: local project/session JSONL data, sessions, projects, timestamps, models, token usage when present.
+- GitHub Copilot: local OpenTelemetry JSONL exports, Copilot session-state files, and VS Code Copilot Chat transcript/debug files when present.
+- Cursor: experimental opt-in support for local JSONL, SQLite, db, and vscdb files; token and cost accuracy depends on local data availability.
+- RTK: token-reduction workflow context shown alongside AI usage; RTK is not an AI token source.
+
+Target users:
+- Developers using AI coding tools across multiple repositories.
+- Engineering leads who want local-first AI usage analytics without uploading prompts or code.
+- Maintainers who want to understand repo-level AI coding spend, model mix, cache reuse, high-token sessions, and agent friction.
+- Teams comparing AI coding cost estimates across Codex, Claude Code, GitHub Copilot, and experimental Cursor imports, with RTK context for reducing token waste.
+
+Useful descriptions:
+- Codex token usage dashboard
+- Claude Code token usage by repo
+- AI coding spend dashboard
+- Local-first AI usage analytics
+- Cursor token usage tracking
+- Repo-level AI coding cost tracker
+- API-equivalent AI coding cost estimates
+- Local AI coding usage dashboard
+
+Positioning:
+- RepoSpend complements CLI tools such as ccusage.
+- ccusage is useful for terminal-first Claude Code totals and daily breakdowns.
+- RepoSpend is useful for visual repo-level analytics, session inspection, source/tool comparison, model mix, token shape, cache reuse, exports, and command/agent friction.
+- RepoSpend totals can intentionally differ from ccusage or Tokscale because it includes Claude Desktop/local-agent session roots when present, treats cache reads/writes as input sub-buckets, prices Claude cache writes by recorded 5-minute vs 1-hour TTL, and separates Codex visible output from reasoning output.
+
+Cost language:
+- RepoSpend shows estimated API-equivalent cost.
+- RepoSpend does not claim to show actual bills, invoices, subscription usage, savings, credits, or account-specific charges.

package/docs/pricing.md

@@ -0,0 +1,66 @@
+# Pricing
+
+RepoSpend estimates API-equivalent cost from a local pricing table. The bundled defaults live in `packages/core/src/pricing.ts`, and the dashboard Settings page saves local overrides to `~/.repospend/pricing.json`.
+
+The bundled table is seeded from public OpenAI, Anthropic, Google, and GitHub Copilot model references and is expressed as USD per 1M tokens. Pricing changes over time, so treat RepoSpend costs as API-equivalent estimates rather than invoice-grade accounting.
+
+For Claude models, RepoSpend uses Anthropic's cache-write TTL split when local
+Claude Code usage reports expose it. Tokens recorded under
+`cache_creation.ephemeral_5m_input_tokens` use the 5-minute cache-write rate, and
+tokens recorded under `cache_creation.ephemeral_1h_input_tokens` use the 1-hour
+cache-write rate. If a source only exposes the older aggregate
+`cache_creation_input_tokens` field, RepoSpend falls back to the model's generic
+cache-write rate.
+
+Each model can define:
+
+- input tokens
+- 5-minute cache write input tokens
+- 1-hour cache write input tokens
+- generic cache write input tokens for sources without a TTL split
+- cached input tokens
+- output tokens
+- reasoning output tokens
+
+RepoSpend prices each bucket once. `inputTokens` is normalized as total input,
+including cache reads and cache writes when those are present, so the pricing
+formula first subtracts cache sub-buckets from billable input and then applies
+their cache-specific rates. This is why RepoSpend token totals can be lower than
+tools that add cache reads/writes as separate "total token" columns while still
+producing comparable API-equivalent cost.
+
+Reasoning output is also priced once. For Codex records where raw
+`output_tokens` includes `reasoning_output_tokens`, RepoSpend subtracts reasoning
+from visible output before storing and pricing both buckets. If a comparison tool
+shows output inclusive of reasoning and also prices reasoning separately, its
+cost will be higher because reasoning is counted twice.
+
+This is a known reason RepoSpend Codex API-equivalent cost can be lower than a
+tool whose output bucket remains inclusive of reasoning while also exposing a
+separate reasoning bucket. Compare visible output and reasoning separately before
+treating a cost delta as a pricing-table problem.
+
+See [token-accounting.md](token-accounting.md) for the detailed comparison model.
+
+This can differ from tools or older `ccusage` versions that price all Claude
+cache creation tokens with one cache-write rate. A single-rate calculation can
+understate sessions that mostly used Anthropic's 1-hour cache writes or overstate
+sessions that mostly used 5-minute cache writes. RepoSpend prices the buckets
+recorded in the local Claude transcript instead of forcing every cache write into
+one column.
+
+When an exact model id is not present in the pricing table, RepoSpend first tries conservative family matching for known provider naming patterns. For example, a nearby newer Claude Opus 4.x or GPT 5.x variant can inherit the closest older bundled rate so the dashboard stays useful while public rate cards catch up. Inherited rates are labeled in Settings.
+
+If RepoSpend cannot resolve a usable rate, it still displays token totals and marks cost as unknown. Unknown pricing does not stop scans, dashboard responses, CLI output, or exports.
+
+If Codex only exposes a raw token total for an older session, RepoSpend also leaves cost unknown. It does not infer an input/output split because that would make the estimate look more precise than the local data supports.
+
+Claude Code local transcripts may include token counts and model names, but they may also omit one or both depending on the local file and client version. RepoSpend leaves Claude cost unknown when the local data is insufficient instead of inventing a token split.
+
+GitHub Copilot local files vary by surface. OTEL exports can include full token
+splits and can be priced with the bundled model table. Copilot CLI session-state
+files can expose output-token counts without input/cache fields; RepoSpend shows
+those output tokens but leaves API-equivalent cost unknown because pricing only
+the output side would look more complete than the local data supports.
+
+These costs are not your actual ChatGPT, Codex, Claude, Claude Code, or GitHub Copilot bill. Your real cost may differ because of subscriptions, credits, provider terms, included usage, premium request multipliers, account-level pricing, or other billing factors.

package/docs/token-accounting.md

@@ -0,0 +1,100 @@
+# Token Accounting
+
+RepoSpend uses one normalized token shape across local clients:
+
+- `inputTokens` is total input for the request/session. When a source reports cache reads or cache writes separately, RepoSpend includes them in `inputTokens` and also stores them in sub-buckets.
+- `cachedInputTokens` is the cache-read portion of input.
+- `cacheCreationInputTokens` is the cache-write portion of input, when the source exposes it.
+- `cacheCreationInputTokens5m` and `cacheCreationInputTokens1h` preserve Anthropic's Claude cache-write TTL split when local transcripts expose `usage.cache_creation`.
+- `outputTokens` is visible/non-reasoning output.
+- `reasoningTokens` is reasoning output, when the source exposes it.
+- `totalTokens = inputTokens + outputTokens + reasoningTokens`.
+
+This keeps total tokens aligned with the amount of model work represented by the normalized session, while still preserving the billable cache buckets needed for cost.
+
+## Why `ccusage` Can Show Higher Totals
+
+`ccusage` displays cache reads and cache writes as addable token buckets. In that accounting style, a total is closer to:
+
+```text
+uncached input + cache read input + cache write input + output
+```
+
+RepoSpend instead normalizes those cache buckets under input:
+
+```text
+inputTokens + outputTokens + reasoningTokens
+```
+
+Both views can be useful, but they answer different questions. RepoSpend's total is the dashboard/product total: how much local AI coding usage belongs to a repo, session, model, or day without counting the same cached input twice. `ccusage`'s displayed total is useful as a billable-line-item view, but it will look larger when cache reuse is high.
+
+Do not make RepoSpend's total match `ccusage` by adding `cachedInputTokens` to `inputTokens`. RepoSpend already prices cached input separately in `packages/core/src/pricing.ts`:
+
+```text
+billable input = inputTokens - cachedInputTokens - cacheCreationInputTokens
+cached input = cachedInputTokens
+cache write input = cacheCreationInputTokens
+```
+
+Adding cached tokens again would inflate token totals and double-charge cached input in API-equivalent cost.
+
+## Claude Source Scope
+
+RepoSpend scans both Claude project transcripts and Claude Desktop/local-agent
+session roots:
+
+```text
+~/.claude/projects
+~/.config/claude/projects
+~/Library/Application Support/Claude/local-agent-mode-sessions
+~/.config/Claude/local-agent-mode-sessions
+```
+
+Many terminal-first usage tools focus on `~/.claude/projects`. If local-agent
+session files exist, RepoSpend can show higher Claude totals than `ccusage` or
+Tokscale without a parser bug. When comparing tools, first check whether the
+same Claude roots are included.
+
+For Claude, RepoSpend also preserves the cache-write TTL split when it is present
+in local logs:
+
+```text
+5-minute cache write = cacheCreationInputTokens5m
+1-hour cache write = cacheCreationInputTokens1h
+unclassified cache write = cacheCreationInputTokens - cacheCreationInputTokens5m - cacheCreationInputTokens1h
+```
+
+This is one reason RepoSpend API-equivalent cost can differ from `ccusage`.
+Anthropic prices 5-minute cache writes at a different rate than 1-hour cache
+writes. RepoSpend applies the recorded TTL-specific rate for each bucket; tools
+that collapse all Claude cache creation tokens into a single cache-write column
+can drift when a session mixes TTLs or when the chosen single rate does not match
+the session's actual cache usage.
+
+## Reasoning Tokens
+
+RepoSpend keeps reasoning tokens separate when the local source exposes them. The accurate treatment depends on the source's raw usage shape:
+
+- If `output_tokens` already includes `reasoning_output_tokens`, RepoSpend subtracts reasoning from output and then stores reasoning separately.
+- If a source reports visible output and reasoning as separate non-overlapping fields, RepoSpend can store both directly.
+- If a source does not expose reasoning, RepoSpend leaves reasoning at zero rather than inventing it.
+
+Codex local token records currently need the first treatment: reported `output_tokens` can include `reasoning_output_tokens`. RepoSpend therefore normalizes Codex output to visible output and prices reasoning once. A comparison tool that reports output inclusive of reasoning and also reports reasoning separately can show a higher cost because reasoning has effectively been counted twice.
+
+## What To Compare In Reviews
+
+When checking RepoSpend against `ccusage`, Tokscale, or another local usage tool:
+
+- Compare the same absolute date window and timezone.
+- Compare API-equivalent cost first.
+- Compare bucket-level values, not just headline total tokens.
+- Treat large cost differences as real discrepancies.
+- Treat token total differences as suspicious only after accounting for cache semantics, reasoning semantics, date filters, and cumulative Codex checkpoints.
+
+For Codex, RepoSpend prefers per-turn `last_token_usage` deltas and skips stale duplicate snapshots when available. This avoids under-counting sessions that compacted and avoids over-counting rebroadcast cumulative checkpoints.
+
+For GitHub Copilot, RepoSpend aligns with ccusage and Tokscale for OTEL-backed
+records, but keeps `cachedInputTokens` as a subset of `inputTokens` in the
+normalized model. Copilot CLI session-state files can expose output tokens
+without input/cache tokens; those sessions are counted as partial token data and
+left unpriced until a full OTEL usage record is available.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "repospend",
-  "version": "0.0.9",
-  "description": "Local-first dashboard for tracking AI coding token usage by repo, source, session, model, and day.",
+  "version": "0.1.1",
+  "description": "Local-first dashboard for tracking AI coding token usage and API-equivalent spend by repository, session, model, and tool.",
   "license": "Apache-2.0",
   "author": "Mehmet Mustafa Demir",
   "type": "module",
@@ -23,7 +23,11 @@
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",
+    "docs/llms.txt",
+    "docs/data-sources.md",
+    "docs/pricing.md",
     "docs/PUBLISHING.md",
+    "docs/token-accounting.md",
     "docs/screenshots/*.png",
     "LICENSE"
   ],
@@ -41,16 +45,23 @@
     "typecheck": "pnpm --filter @repospend/types --filter @repospend/core build && pnpm --stream --filter @repospend/types --filter @repospend/core --filter @repospend/server --filter @repospend/web typecheck",
     "clean": "pnpm -r clean && rm -rf dist web-dist",
     "rebuild:native": "pnpm rebuild better-sqlite3",
-    "doctor:native": "node scripts/check-native.mjs"
+    "doctor:native": "node scripts/check-native.mjs",
+    "media:capture": "node scripts/capture-release-media.mjs"
   },
   "keywords": [
     "codex",
     "openai-codex",
     "claude",
+    "claude-code",
+    "cursor",
+    "github-copilot",
     "ai-coding",
+    "ai-usage-analytics",
     "developer-tools",
     "token-usage",
     "cost-tracking",
+    "ai-cost-tracker",
+    "repo-spend",
     "local-first",
     "cli",
     "dashboard",
@@ -71,6 +82,9 @@
     "@types/node": "^22.19.1",
     "esbuild": "^0.28.0",
     "eslint": "^9.39.1",
+    "gifenc": "^1.0.3",
+    "playwright": "^1.60.0",
+    "sharp": "^0.35.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.46.4",
     "vitest": "^3.2.4"