tkntracker

Local-first AI token usage tracker for every coding agent you use.

One command. Beautiful dashboard. Your data never leaves your machine.

npm i -g tkntracker
tkntracker web

That’s it. Syncs your tools, opens a screenshot-ready dashboard at http://127.0.0.1:7777.

---

Why

You bounce between Claude Code, Codex, Cursor, Grok, Qwen, OpenCode, Gemini… and have no single view of how many tokens you burn each month.

tkntracker reads each tool’s local logs and databases (token counts only), stores them in SQLite on your machine, and shows a dashboard — plus terminal reports when you want them.

One command	tkntracker web
Cross-platform	macOS · Linux · Windows
No account	No API keys, no cloud signup
Privacy-first	Never prompts, responses, or secrets
24 tools	Passive readers — no hooks required

---

Install

Requirements: Node.js 22.5+ (uses built-in node:sqlite)

npm install -g tkntracker

Or try without installing:

npx tkntracker web

---

Quick start

tkntracker          # same as `tkntracker web`
tkntracker web      # sync all tools + open dashboard
tkntracker month    # terminal summary for this month
tkntracker status   # which tools were found on this machine

Command	What it does
tkntracker / web / dashboard	Sync all tools + open the local dashboard
tkntracker month [YYYY-MM]	Monthly token + cost summary in the terminal
tkntracker overview	All-time totals
tkntracker status	Detection status for every supported tool
tkntracker sync	Scan tools and update the DB (no browser)
tkntracker doctor	Health check (Node version, paths, detected tools)
tkntracker help	Full CLI help
tkntracker version	Print version

Common flags

tkntracker web --port 8080
tkntracker web --no-open          # print URL only
tkntracker web --no-sync          # reopen dashboard without rescan
tkntracker month 2026-07
tkntracker sync --only claude-code,codex,cursor
tkntracker status --json
tkntracker month --json           # machine-readable output

Data location

Path	Purpose
~/.tkntracker/	Default data directory
~/.tkntracker/data.db	SQLite database

Override with environment variables:

Variable	Description
TKNTRACKER_HOME	Data directory (default ~/.tkntracker)
TKNTRACKER_DB	Full path to SQLite file
TKNTRACKER_PORT / PORT	Dashboard port (default 7777)

Per-tool homes can also be overridden (e.g. CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME, CURSOR_STATE_DB). See src/paths.ts for the full list.

---

Supported tools (24)

Tool	Provider id	How we read tokens	Notes
Claude Code	claude-code	~/.claude/projects/**/*.jsonl assistant usage	Native per-request; requestId dedup
Codex CLI	codex	Rollout token_count → last_token_usage	Native per-turn (not cumulative)
xAI Grok CLI	grok	updates.jsonl cumulative totalTokens	Turn deltas; I/O split estimated
Cursor	cursor	state.vscdb bubble tokenCount	Native when present
OpenCode	opencode	opencode.db step-finish tokens	Native
Qwen CLI	qwen	usage/token-usage-*.jsonl	Native
Gemini CLI	gemini	Session / history JSON	When usage fields present
Antigravity	antigravity	Transcript JSONL	When usage fields present
GitHub Copilot	copilot	Session-store / OTEL	When local metrics exist
Kimi Code	kimi	wire.jsonl	When usage fields present
Hermes Agent	hermes	SQLite	When token columns / JSON present
Goose	goose	sessions.db	When present
Zed Agent	zed	threads.db	When usage in thread data
Roo Code / Cline	roo	ui_messages.json	Native when logged
Kilo CLI / Code	kilo	kilo.db + ui_messages	Native when present
pi	pi	Session JSONL	When usage fields present
oh-my-pi	oh-my-pi	Session JSONL	When usage fields present
Droid (Factory)	droid	~/.factory	When usage fields present
CodeBuddy	codebuddy	Claude-fork JSONL	Native per-request
WorkBuddy	workbuddy	Claude-fork JSONL	Native per-request
Windsurf	windsurf	state.vscdb	When token fields present
Qoder	qoder	Local SQLite	When present
Mimo Code	mimo	Local SQLite	When present
ZCode	zcode	Local SQLite	When present

Accuracy notes

• We prefer provider-native per-request / per-turn counters when available.
• Events are deduped by stable IDs (e.g. request IDs) so the same call isn’t counted twice.
• Cost is an API list-price estimate — not your subscription invoice (Claude Max, Cursor Pro, etc.).
• Some tools only expose partial metrics; coverage improves as those tools log richer usage data.
• Grok currently exposes cumulative totals; turn deltas are computed and input/output split is estimated.

---

How it works

Your AI tools write local logs / DBs
            │
            ▼
   tkntracker sync / web
   (passive readers — no hooks, no agents modified)
            │
            ▼
   ~/.tkntracker/data.db   (SQLite)
            │
            ▼
   localhost dashboard + CLI reports

1. Each provider detects whether a tool is installed and collects UsageEvent records (tokens, model, timestamp — never message content).
2. Pricing applies approximate public list rates so months are comparable across tools.
3. Events are upserted into a local SQLite DB with stable IDs for deduplication.
4. The dashboard (and CLI) read from that DB only.

Local HTTP API (dashboard)

When the server is running (tkntracker web):

Endpoint	Description
GET /	Dashboard UI
GET /api/health	Liveness check
GET /api/overview	All-time totals
GET /api/status	Provider detection + last sync
GET /api/month/YYYY-MM	Monthly breakdown
POST /api/sync	Trigger a resync

Bound to 127.0.0.1 only (not exposed on LAN/public interfaces).

---

Privacy

Stored	Never stored
Token counts	Prompts / user messages
Model names	Assistant responses
Timestamps	File contents / diffs
Provider id	Secrets / API keys
Optional session ids	Network credentials

• 100% local by default — nothing is uploaded.
• Readers only open tool log files and local databases already on your disk.
• You can delete everything by removing ~/.tkntracker/.

---

Cross-platform paths

OS	Editor data (Cursor, Windsurf, …)	Tool homes (Claude, Codex, …)
macOS	~/Library/Application Support/{App}/…	~/.claude, ~/.codex, …
Linux	~/.config/{App}/…	~/.claude, ~/.codex, …
Windows	%APPDATA%\{App}\…	%USERPROFILE%\.claude, …

---

Development

git clone https://github.com/junaiddshaukat/tkntracker.git
cd tkntracker
npm install
npm run build
node bin/tkntracker.js web
npm test

Script	Purpose
npm run build	Compile TypeScript → dist/
npm run dev	Run CLI via tsx (no build)
npm test	Run tests
npm run typecheck	tsc --noEmit
npm start / npm run web	Run built CLI

Project layout

src/
  cli.ts                 CLI entry
  sync.ts                Orchestrates provider collection
  pricing.ts             List-price cost estimates
  extract.ts             Shared usage-field extractors
  paths.ts / platform.ts Cross-platform path helpers
  db/store.ts            SQLite storage
  providers/             One module per coding agent
  server/                Local dashboard + HTTP API
test/                    Node test runner suites
bin/tkntracker.js        Production bin (loads dist/)

Adding a provider

1. Create src/providers/your-tool.ts implementing the Provider interface (detect + collect).
2. Emit only UsageEvent fields (tokens / model / timestamp) — never message bodies.
3. Register it in src/providers/index.ts.
4. Add a row to this README’s supported-tools table.
5. Prefer stable event IDs for dedup.

See CONTRIBUTING.md for full guidelines.

---

Publishing (maintainers)

npm login
npm version patch   # or minor / major
npm publish

prepublishOnly builds TypeScript and runs tests. The published package includes bin/, dist/, LICENSE, and README.md only.

---

Contributing

Contributions are welcome — new providers, better extractors, dashboard polish, docs, and tests.

• Read CONTRIBUTING.md
• Follow the Code of Conduct
• Report security issues via SECURITY.md

---

Changelog

See CHANGELOG.md.

---

License

MIT © Muhammad Junaid

---

Disclaimer

tkntracker is an unofficial community tool. It is not affiliated with Anthropic, OpenAI, xAI, Google, Cursor, or any other vendor. Token totals depend on what each tool logs locally. Cost figures are estimates based on public API list prices and may not match subscription billing or negotiated rates.