topgauge: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A Claude Code statusline plugin (creditgauge, formal name CreditGauge-CC) that renders MiniMax token-plan usage (5-hour and weekly windows) or DeepSeek account balance, picked by ANTHROPIC_BASE_URL. The plugin ships its own installer (scripts/install.sh) that hooks into Claude Code's statusLine slot and (optionally) chains any pre-existing statusline (e.g. ccstatusline, claude-hud) as the upstream. When ANTHROPIC_BASE_URL does not point at a supported provider, the plugin hides itself and passes upstream output through unchanged.

The plugin is shipped as a single-plugin marketplace: the repo root IS the marketplace, and .claude-plugin/plugin.json declares the plugin. Install with /plugin marketplace add cwf818/creditgauge then /plugin install creditgauge@creditgauge, then run /creditgauge:install to wire it into settings.json. Uninstall with /creditgauge:uninstall (a self-contained cleanup that works even after the cache and marketplace are gone).

v1.0.0 — Renamed from topgauge to creditgauge (hard cut, no compat shim). Full mapping in CHANGELOG; provider strings (minimax / MiniMax / DeepSeek etc.) are unchanged.

v0.7.0 — Renamed from tokenplan-usage-hud to topgauge (state-dir migration + legacy dual-strip one release).

Commands

npm install          # install dev deps (esbuild, typescript, tsx, @types/node)
npm run typecheck    # tsc --noEmit
npm test             # node:test via tsx (64 tests across api/render/cache/composition)
npm run build        # esbuild → dist/index.js (single self-contained ESM bundle, target=node18)
npm run dev          # esbuild --watch

There is no separate lint step; typecheck covers it. Tests run with built-in node:test + tsx — no vitest/jest dependency.

Architecture

src/
  index.ts            # entry — stdin drain, provider dispatch, cache, render, compose, loadConfig()
  types.ts            # Provider union + transport-free config/data types
  api.ts              # dynamic plugin loader + canonical Quota/Balance exports
  plugins/data.ts     # plugin ABI and canonical Quota/Balance shapes
  plugins/parsers.ts  # built-in field-mapping parsers
  plugins/minimax/    # standalone Quota plugin source
  plugins/deepseek/   # standalone BALANCE plugin source
  # v0.8.36+ — m_windowMemUsage is the RAM-usage sibling of
  # m_memUsage (which renders absolute bytes "Mem:X.XG/Y.YG" with
  # a fixed cyan tint). m_windowMemUsage renders a bar+percent
  # chunk (parallel of m_windowContext) — `▓▓▓▓▓░░░ 62%` — by
  # wrapping getMemUsage()'s 0..100 ratio in a synthetic Window
  # and routing through formatOneChunk / formatOneChunkColored.
  # The value color is driven by colorFor(pct, "used") so
  # thresholds.percentBands drives the hue. NO label prefix.
  # Opt-in; not in any default lineTemplate.
  render.ts           # v1.0 READ-ONLY against tickState.pending: pctBar + ANSI color thresholds + renderProviderLine (sole public entry; the legacy formatLine / formatBalanceLine shims were dropped in v0.9.x); NO setAvg/setPrevTick/setLastSpeed calls (those moved to data-processor.ts)
  data-processor.ts   # v1.0 processTick + setPrevTick + setAvg + setLastSpeed/ApiMs/TokenHitRate + computeAndCacheTickDeltaPure + getDeltaForRender — owns ALL writes to tickState.pending
  cache.ts            # TTL + stale-on-error (Map<key, {at, value}>) — TTL passed in by index.ts from configStore
  config.ts           # config loader/store and provider facade
  config.providers.ts  # provider defaults, type validation, effective mappings
  config.template.ts   # line-template defaults and template-only types
  composition.ts      # reads CREDITGAUGE_UPSTREAM env, prepends (preserving ANSI/multi-line) and appends line
  tick-state.ts       # v1.0 per-tick in-memory Store: beginTick / mark / commit; backing the data-processor's writes + the single commit() flush
  __fixtures__/       # remains.real.json, balance.real.json, balance.multi.json, …
  session-parse.ts    # parseTokenSnapshot — stdin JSON → TokenSnapshot (extracted from index.ts so unit tests don't drag index side effects)
  token-store.ts      # append-only JSONL state file at state/<projectHash>/<sessionId>.jsonl for sum/avg modules (v0.4.x+; v0.8.0 adds readAllSamples cross-project scan)
  *.test.ts           # node:test unit tests
.claude-plugin/
  plugin.json         # plugin manifest (name, version, commands, homepage)
  marketplace.json    # single-plugin marketplace wiring
commands/
  install.md          # /creditgauge:install slash command (Pattern B2 — loader-executes-script via `!`-fenced block + ${CLAUDE_PLUGIN_ROOT}; scoped allowed-tools)
  uninstall.md        # /creditgauge:uninstall slash command (Pattern B2)
  clean.md            # /creditgauge:clean slash command (Pattern B2)
  clean-cache.md      # /creditgauge:clean-cache slash command (Pattern B2)
scripts/
  wrapper.sh          # bash wrapper: CREDITGAUGE_UPSTREAM_CMD → CREDITGAUGE_UPSTREAM → us
  install.sh          # settings.json patcher (install/restore/dry-run; uninstall is its own command in v0.9.x+)
  uninstall.sh        # self-contained uninstaller (used by :uninstall and dev:uninstall)
  clean.sh            # trim old .bak.<ts> files, keeping only the most recent per file
  lib/edit-settings.mjs # ESM helper used by install.sh
  dev-uninstall.sh    # DEV-ONLY thin shim → exec uninstall.sh
  index.js            # gitignored, esbuild bundle, the actual entry point
settings.example.json # template (NEVER commit a real settings.json)