wigtoken

Self-host aggregator for Claude Code token usage. Watches the JSONL transcripts Claude Code writes locally, runs them through a single SQLite store with per-user / per-machine / per-model labels, and exposes:

• Public SSE counter — drop a single live number on a marketing page (/api/usage/totals, /api/usage/stream)
• Prometheus /metrics — labelled counters for Grafana dashboards
• Authenticated ingestion API — agents on remote dev machines push their own transcripts in (POST /api/ingest/messages)

Works for one developer on a laptop (zero-config) and for a team of N machines, with the same binary.

Quickstart — solo

You're a single developer; just want a personal cost dashboard for your own Claude Code usage.

git clone https://github.com/wigtn/wigtoken
cd wigtoken
npm install
npm start

That's it. The daemon picks up ~/.claude/projects automatically and starts on http://localhost:10103.

curl http://localhost:10103/api/usage/totals | jq
curl http://localhost:10103/metrics

Point a Grafana → Prometheus stack at localhost:10103 and import grafana/dashboard.json for the full breakdown. Or just open the JSON endpoints in a browser.

Quickstart — team

You have multiple developers on multiple machines and want one consolidated view.

1. Run the server somewhere reachable (Linux box, NAS, container in your cluster):

   docker run -d --name wigtoken \
     -p 10103:10103 \
     -e MODE=team \
     -e ALLOWED_ORIGINS=https://your-site.com \
     -v $PWD/data:/data/db \
     ghcr.io/wigtn/wigtoken:latest

   Or use docker-compose.example.yml.

2. Issue an admin bootstrap token (printed once on first run) and use it to mint per-developer ingest tokens:

   ADMIN=wts_xxx
   curl -X POST https://your-server/api/admin/tokens \
     -H "Authorization: Bearer $ADMIN" \
     -H "Content-Type: application/json" \
     -d '{"user":"alice","scope":"ingest","label":"alice-laptop"}'

3. Each developer runs the agent on their machine:

   npx @wigtoken-temp/agent \
     --server https://your-server \
     --token wts_alice_token \
     --machine $(hostname)

   Or as a launchd / systemd service — see agent/README.md.

The agent watches ~/.claude/projects on each machine and streams new messages over HTTPS. Server-side dedupe by message_id makes it safe to restart, retry, or run multiple agents against the same transcripts.

Architecture

┌────────────────────────────────────────────────────────────┐
│                                                            │
│   ┌─────────────┐ scrape ┌──────────────┐ → ┌──────────┐   │
│   │ wigtoken │←──────│ Prometheus   │ →│ Grafana  │   │
│   │   server    │        └──────────────┘   └──────────┘   │
│   │             │                                          │
│   │ /api/ingest │←── HTTPS+Bearer ──┐                       │
│   │ /api/usage/*│                   │                       │
│   │ /metrics    │←── public reads ──┐│                      │
│   │ SQLite      │                   ││                      │
│   └─────────────┘                   ││                      │
└─────────────────────────────────────┼┼──────────────────────┘
                                      ││
                                      ││
┌────────────────┐ ┌────────────────┐ │ ┌──────────────────┐
│  agent (mac)   │ │ agent (linux)  │ │ │ public web hero  │
│ ~/.claude/...  │ │ ~/.claude/...  │ │ │ counter          │
│ → push batches │ │ → push batches │ │ └──────────────────┘
└────────┬───────┘ └────────┬───────┘ │
         └──────────────────┴─────────┘
                  per-user tokens

For solo: agent and server run as one process on the same box, no token, no HTTPS.

Two ways to push from a developer machine

Both end up calling POST /api/ingest/messages with an ingest-scope bearer token; you pick the trade-off:

| | Agent | Hook | |---|---|---| | Footprint | LaunchAgent / systemd unit running @wigtoken-temp/agent | one block in ~/.claude/settings.json | | Offline retry | ✅ disk queue + backoff | ❌ one-shot POST per turn | | Setup | npm install + token + plist | settings.json edit | | Best for | shared/public networks, critical usage | trusted networks, quick demos |

Full hook walkthrough → docs/HOOKS.md. Agent → agent/README.md.

API

Public (no auth)

| Method | Path | Notes | |---|---|---| | GET | /health | Liveness probe | | GET | /api/usage/totals | Single-snapshot JSON — drives the hero counter | | GET | /api/usage/stream | SSE stream; pushes a totals event whenever new tokens land | | GET | /api/usage/breakdown | JSON view of the per-label breakdown the metrics endpoint exposes | | GET | /metrics | Prometheus exposition; labels: user, machine, model, model_family, kind |

Authenticated (Authorization: Bearer <token>)

| Method | Path | Required scope | |---|---|---| | POST | /api/ingest/messages | ingest | | GET | /api/admin/tokens | admin | | POST | /api/admin/tokens | admin | | DELETE | /api/admin/tokens/:id | admin | | GET | /api/admin/audit | admin |

admin scope implicitly satisfies any other scope.

Configuration

Every knob is an environment variable; flags are on the agent side only. See .env.example for the full list. Highlights:

| Var | Default | Purpose | |---|---|---| | MODE | auto-detected | solo or team | | CLAUDE_PROJECTS_DIR | ~/.claude/projects | Where to watch (solo) or the multi-tenant root (team) | | STATS_DB_PATH | <repo>/data/stats.db | SQLite location | | PORT | 10103 | HTTP port | | ALLOWED_ORIGINS | http://localhost:3000 | CORS allowlist | | WATCH_POLLING | true | Force chokidar polling — false on native Linux/macOS for fsevents | | SCAN_INTERVAL_MS | 5000 | Backup readdir walk |

Solo vs team mode

The daemon auto-detects from CLAUDE_PROJECTS_DIR's top-level layout:

• Subdirectories starting with - (Claude Code's -encoded-cwd/ pattern) → solo
• Subdirectories that look like usernames (no leading dash) → team

MODE=solo|team overrides the heuristic.

Cost model

Costs are estimated against Anthropic's public per-token rates. All values flow from one rate table in src/pricing.ts:

| Family | input | cache_creation | cache_read | output | |---|---:|---:|---:|---:| | Opus 4.x | $15 / Mtok | $18.75 | $1.50 | $75 | | Sonnet 4.x | $3 | $3.75 | $0.30 | $15 | | Haiku 4.5 | $0.80 | $1.00 | $0.08 | $4 |

The input-equivalent weight (used for wigtn_tokens_weighted_total) follows the input-relative ratios — 1 : 1.25 : 0.1 : 5, identical across families.

These are estimates, not your bill. Max-plan flat-rate users won't pay the USD numbers shown here; the metric is for relative comparison and waste-spotting, not accounting.

Privacy

• The daemon stores counts, model identifiers, and message IDs. Message bodies are never persisted — parseLine() doesn't even read them.
• The agent ships only what's already in the request payload schema (agent/src/parser.ts); same guarantee.
• /api/admin/audit records every ingest call with token id, IP, byte count — stored in the same SQLite file, no remote logs.

Security

• HTTPS strongly recommended for any non-loopback deployment. The daemon itself binds plain HTTP — terminate TLS at nginx, Caddy, or Cloudflare.
• Bearer tokens are 256-bit random; only the SHA-256 hash is on disk.
• ingest-scope tokens can only forge data under their own user label (the user is taken from the token, never from the payload).
• Per-token rate limit defaults to ~100 req/min sustained; raise it for noisy CI.

Development

npm install
npm run dev          # hot-reload via tsx watch
npm run typecheck    # tsc --noEmit

Single-file modules; deliberately no build step. The agent is a separate package under agent/ with its own package.json.

License

MIT.