ccgauge AGENTS.md

AGENTS.md

Working agreement for AI coding agents (Claude Code, Codex CLI, Cursor agents, etc.) editing this repo. Humans should skim it too — it captures the non-obvious parts of the codebase that aren't in the README.

What this project is

ccgauge is a local web dashboard + CLI + MCP server for inspecting Claude Code and OpenAI Codex CLI token usage and cost. Everything runs on the user's machine; there are zero outbound network calls at runtime.

Three user-facing surfaces share one data layer:

Surface	Entry	Talks to
Web dashboard	app/ (Next.js 15 RSC)	the indexer singleton
CLI (ccgauge)	bin/cli.mjs	the indexer via a bundled dist/report/index.mjs
MCP server (ccgauge mcp)	lib/mcp/entry.ts → dist/mcp/server.mjs	the indexer via a separate 'mcp'-named instance

Published to npm as ccgauge. End-users typically run npx ccgauge.

Repo layout

app/                       Next.js routes (RSC pages + /api routes)
  api/                     Server-side JSON endpoints (scan, usage, sessions,
                           projects, turns, blocks, pricing, export/usage)
  page.tsx                 Overview
  usage/, sessions/[id]/, projects/[id]/, models/, tools/, settings/
                           Drill-down pages. Sessions / Projects / Models /
                           Tools live under the "Analytics" nav dropdown.

bin/cli.mjs                Single-file CLI (commander). Imports the bundled
                           dist/report/index.mjs and dist/mcp/server.mjs lazily
                           when those subcommands run.

components/                React. All client UI atoms (KpiCard, Section,
                           usage-table, hover-card, activity-stats, …).

lib/
  providers/               Per-CLI adapters (claude, codex). Add a new provider
                           by dropping a folder + one line in lib/providers/index.ts.
                           Each adapter owns resolvePricing() + costFromUsage().
  data-loader/             scan.ts (entry), indexer.ts (singleton + watchers),
                           index-persist.ts (~/.ccgauge on-disk cache),
                           parse-jsonl.ts (claude parser), link-sidechain.ts
                           (sub-agent → parent-turn merge pass, both providers),
                           derived.ts (memoized per-scan derivations: model /
                           project lists, turn-row LRU).
  aggregator/              Pure aggregations: totals, time-buckets, by-model,
                           by-project, by-session, activity heatmap (activity.ts),
                           and tool / skill / MCP context footprint (tools.ts,
                           feeds the /tools page — Claude source only).
  api/                     error-handler.ts: the withApiErrorHandling wrapper +
                           shared badRequest shape used by every /api route.
  blocks/                  5-hour billing-block rollups (computeBlocks). Feeds
                           app/api/blocks + the block-progress components.
  pricing/                 LiteLLM-sourced. litellm-pricing.generated.js is the
                           committed snapshot (refresh: pnpm update-pricing);
                           builtin.ts gap-fills models LiteLLM lacks; store.ts
                           overlays a runtime LiteLLM cache + publishes to a
                           globalThis slot; merge.ts + litellm-transform.js hold
                           the pure merge/validate/transform; resolve.ts +
                           calculate.ts + cost-from-usage.ts do lookup + math.
  source.ts /              "Source" switch (claude / codex / merged), cookie-
  source-merge.ts          driven; folds two providers' totals + buckets into
                           one merged view.
  serialize.ts             Shape AssistantRecord[] → UsageTableRow[] /
                           UsageTurnRow[]; turn grouping lives here too.
  turns.ts                 Parent-chain walking that decides which assistant
                           records collapse into the same "turn".
  cli-report/              The pretty terminal report. Bundled into dist/report.
  mcp/                     MCP server (stdio JSON-RPC). Bundled into dist/mcp.
                           tools/ holds the 9 registered tools (usage.ts × 6,
                           activity.ts × 3); resources/ exposes provider
                           metadata; check.ts backs `ccgauge mcp --check`.
  i18n/, theme/            Cookie-driven SSR + localStorage mirror + no-flash.

scripts/                   Build & test helpers (esbuild bundlers, postbuild,
                           parser fixtures).

dist/                      esbuild output. Not source-controlled — generated
                           by `pnpm build`. Listed in package.json#files so it
                           ships in the npm tarball.

site/                      Astro 4 marketing site. Deployed twice from one
                           workflow: GitHub Pages at chengzuopeng.github.io/ccgauge
                           and EdgeOne at ccgauge.linkdiary.cn — see
                           `site/README.md#deploy`, which also records why
                           EdgeOne can't use its own Git integration and the
                           two setup traps (project must be `Upload` type;
                           the token must be a REPOSITORY secret). Source-only
                           subdirectory: commands and dependencies are managed
                           by the root `package.json` / `pnpm-lock.yaml`, while
                           site builds remain explicit via `pnpm site:*`.
                           NOT published to npm — excluded by the main
                           `package.json#files` allowlist and a
                           belt-and-suspenders `site/` line in `.npmignore`.
                           Develop with `pnpm site:dev` (runs on :4321 so it
                           doesn't clash with the dashboard on :3738).