TokensBurned turns the token usage of your AI coding tools into a live SVG card for your GitHub profile. The client reads usage metadata from harnesses such as Claude Code and Codex, reduces it locally to aggregate counters, and uploads only those aggregates. Prompts, responses, and source code never leave your machine.

Features

• Live profile card. Display usage totals, a seven-day trend, an activity heatmap, tool breakdowns, and optional streak, cache, and rank badges. Embed one image link in your profile.
• Local reduction. Usage records are processed on your device. Only aggregate counts and attribution metadata are uploaded.
• Strict privacy boundary. Prompts, responses, source code, repository names, transcript paths, and API keys are never retained in usage statistics or uploaded. See Privacy and security.
• Private by default. Connecting an account and uploading aggregates does not create a public card. Publishing is a separate, explicit command.
• Accurate attribution. Harness, provider, and model are recorded as separate identities. A Claude Code session that talks to a different provider is labeled as such.
• Honest compatibility. Native hooks, plugin workflows, and the standalone CLI are labeled separately so you know how each harness is measured.

Supported harnesses

This table describes the current source. For an installed release, consult the README at its release tag.

| Harness | Install surface | Token source | Support level | | --- | --- | --- | --- | | Claude Code | Plugin marketplace | Lifecycle hooks and approved local history | Native | | Codex | Plugin marketplace | Plugin hooks and approved local history | Native | | Cline CLI / SDK / classic IDE | Cline plugin and standalone CLI | afterModel, SDK messages and classic task metrics | Format-scoped per-call capture and backfill | | OpenCode | Standalone CLI | v1/v2 SQLite and legacy message JSON | Finalized request usage; history backfill | | Gemini CLI | Gemini extension and standalone CLI | Recorded JSON/JSONL usage | Background collection and backfill | | GitHub Copilot CLI | Setup plugin and live extension | Official assistant.usage events | Live per-call capture; no transcript backfill | | Cursor, Aider, others | Standalone CLI | Integrator-supplied observed usage | No automatic capture |

TokensBurned uses reported token counts, not estimates based on prompt length or cost. Support depends on the tool version and available usage records. Details for each source are in Local collection contracts.

Quick start

Background collection requires Node.js 20 or newer and the standalone CLI:

npm install -g tokensburned

Using the CLI with plugins

Use the same BURN_HOME directory (default: ~/.burn) and connection for the CLI and plugins. Keep them on the same version. The client deduplicates supported usage records, so the background collector and plugin hooks can run together.

Do not configure separate data directories to collect the same history, or manually import records that an automatic collector already tracks. Doing so can duplicate usage.

Profile card

Cards are private until you opt in:

tokensburned privacy public

Publishing exposes totals, harness, provider, and model breakdowns, activity heatmaps, rank, and your GitHub identity. The setting belongs to your GitHub account, so every connected device shares the same choice. Then open the card builder, enter your GitHub username, pick a preset, and paste the Markdown into your profile README:

[![TokensBurned activity](https://api.tokensburned.com/v1/cards/u/YOUR_GITHUB_NAME.svg?theme=auto)](https://tokensburned.com/)

Card elements

Every card keeps the flame character, the seven-day trend, the doodles, and the caption. Optional elements are toggled with query parameters:

| Element | Parameter | Default | | --- | --- | --- | | Activity heatmap | heatmap=0\|1 | On | | Harness breakdown | stack=0\|1 | On | | Consecutive active days | streak=0\|1 | On | | Cached input share over the last seven days | cache=0\|1 | Off | | Rank badge | rank=0\|1 | Off |

theme=auto|light|dark selects the appearance. dark is used when the parameter is omitted, and auto follows the viewer's color scheme. For example:

?theme=auto&heatmap=1&stack=1&streak=1&cache=1&rank=0

Privacy settings always apply. A hidden activity history does not appear in the trend, and query parameters cannot reveal anything your account has not published. Use the card builder to generate a link with your preferred options.

Command line

The standalone CLI collects usage from the supported tools listed above and manages your connection, uploads, and privacy settings. Requires Node.js 20 or newer.

npm install -g tokensburned
tokensburned connect
tokensburned run

| Command | Purpose | | --- | --- | | tokensburned | Show local collection and upload status | | tokensburned connect | Authorize your GitHub account and create a device credential | | tokensburned run | Start background collection and enable login startup (macOS and Linux) | | tokensburned privacy [public\|private] | View or change card visibility | | tokensburned doctor | Diagnose collection, connection, and privacy | | tokensburned update | Check for a newer release and catch up recent history | | tokensburned disconnect | Revoke this device's credential |

run installs a user-level service that reads supported local sources once a minute, persists the queue, and retries on the service's schedule. It requires no root privileges. Use run --stop to remove login startup and run --foreground for diagnostics or on platforms without a supported service manager. burn is a shorter alias for tokensburned.

Maintenance commands such as scoped history backfill, authenticated totals, and account deletion are listed by tokensburned help --advanced. Command migration notes and the manual import contract are in Local collection contracts and Usage import.

Privacy and security

| Uploaded usage data | Never included in usage uploads | | --- | --- | | Aggregate token and request counts | Prompts, responses, source code, and tool payloads | | Tool, provider, and model labels | Repository names, file paths, and raw transcripts | | Activity dates and hours | Session IDs, API keys, and provider credentials |

Usage files are processed locally. Raw message content is not retained in the client's statistics. An unrecognized provider endpoint may be labeled by hostname; review your attribution with tokensburned doctor before publishing.

Cards are private by default. Use tokensburned privacy public to publish or tokensburned privacy private to hide your card. Use tokensburned disconnect to disconnect this device. For account data removal, see tokensburned help --advanced.

Read SECURITY.md for the client's data handling and vulnerability reporting policy. Current account limits are available on the usage limits page.

Documentation

• Website and card builder
• Security and privacy boundary
• Local collection contracts and command migration
• Usage import contract for integrators
• Usage limits

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for local setup, testing, and the rules for new collection paths. Report security issues privately as described in SECURITY.md before opening a public issue.

License

MIT © 2026 Parsifal1986