{
  "markdown": "<div align=\"center\">\n  <img src=\"assets/logo.svg\" width=\"112\" alt=\"TokensBurned logo\" />\n  <h1>TokensBurned</h1>\n  <p><strong>Put your AI coding activity on GitHub without uploading prompts or source code.</strong></p>\n  <p>\n    <a href=\"https://tokensburned.com/\"><img alt=\"Website\" src=\"https://img.shields.io/badge/website-tokensburned.com-eb6733?style=flat-square\"></a>\n    <a href=\"https://github.com/Parsifal1986/TokensBurned/actions/workflows/pages.yml\"><img alt=\"GitHub Pages\" src=\"https://img.shields.io/github/actions/workflow/status/Parsifal1986/TokensBurned/pages.yml?style=flat-square&label=pages\"></a>\n    <a href=\"LICENSE\"><img alt=\"MIT License\" src=\"https://img.shields.io/badge/license-MIT-f1eadf?style=flat-square\"></a>\n  </p>\n  <p>\n    <strong>English</strong> · <a href=\"docs/readme/README.zh-CN.md\">简体中文</a> · <a href=\"docs/readme/README.ja.md\">日本語</a> · <a href=\"docs/readme/README.ko.md\">한국어</a> · <a href=\"docs/readme/README.es.md\">Español</a> · <a href=\"docs/readme/README.fr.md\">Français</a>\n  </p>\n  <h3><a href=\"https://tokensburned.com/#card-builder\">Open the interactive card builder →</a></h3>\n  <p><sub>Choose a layout, light/dark/auto theme, and profile elements. The preview uses fictional local data.</sub></p>\n</div>\n\nTokensBurned collects token counts and model metadata from AI coding harnesses, aggregates them into 15 minute buckets, and serves a live SVG for your GitHub profile. The card can show 24 hour, 7 day, 30 day, and all-time totals, daily and hourly heatmaps, harness/provider/model comparisons, and an anonymous site-wide rank.\n\n<div align=\"center\">\n  <img src=\"assets/demo-card-builder.gif\" width=\"840\" alt=\"TokensBurned card builder switching between full, compact, and meme cards\" />\n</div>\n\n## Why TokensBurned\n\n- **One live link.** Your profile updates without scheduled jobs or noisy README commits.\n- **Observed usage.** Harness, provider, and model stay separate. TokensBurned does not call every Claude Code session “Claude.”\n- **Local reduction.** Raw sessions are reduced on your machine before upload.\n- **Hard privacy boundary.** Prompts, responses, source code, repository names, transcript paths, and API keys are not uploaded.\n- **Private until you publish.** Connecting and uploading aggregates do not create a public card; publishing is a separate explicit command.\n- **Honest compatibility.** Native hooks, plugin workflows, and the CLI fallback are labeled separately.\n\n## Install for your harness\n\n<div align=\"center\">\n  <img src=\"assets/demo-install.gif\" width=\"840\" alt=\"TokensBurned installer switching between Claude Code, Codex, and Gemini CLI\" />\n</div>\n\n<table>\n  <tr>\n    <td width=\"50%\" valign=\"top\">\n      <h3>Claude Code</h3>\n      <p><strong>Native plugin + SessionEnd hook</strong></p>\n      <pre><code>/plugin marketplace add Parsifal1986/TokensBurned\n/plugin install tokensburned@tokensburned\n/reload-plugins\n/tokensburned:connect</code></pre>\n      <p>Optional history:</p>\n      <pre><code>/tokensburned:backfill --dry-run --days 90</code></pre>\n    </td>\n    <td width=\"50%\" valign=\"top\">\n      <h3>Codex</h3>\n      <p><strong>Native marketplace plugin + focused skills</strong></p>\n      <pre><code>codex plugin marketplace add Parsifal1986/TokensBurned\ncodex plugin add tokensburned@tokensburned</code></pre>\n      <p>Start a new task, then use:</p>\n      <pre><code>$tokensburned:connect\n$tokensburned:backfill\n$tokensburned:server\n$tokensburned:privacy\n$tokensburned:update\n$tokensburned:doctor</code></pre>\n      <p>SessionStart checks for a newer release at most once per day. It prompts with the native plugin-manager command but never installs silently.</p>\n    </td>\n  </tr>\n  <tr>\n    <td width=\"50%\" valign=\"top\">\n      <h3>Gemini CLI</h3>\n      <p><strong>Official extension + CLI collection</strong></p>\n      <pre><code>gemini extensions install https://github.com/Parsifal1986/TokensBurned\ngemini\n/tokensburned:connect\n/tokensburned:privacy\n/tokensburned:update\n/tokensburned:doctor</code></pre>\n      <p>The extension provides the setup skills. Gemini CLI's built-in telemetry exporter cannot authenticate against the TokensBurned API, so token totals come from the explicit CLI import path. Do not point an exporter at the API.</p>\n    </td>\n    <td width=\"50%\" valign=\"top\">\n      <h3>GitHub Copilot CLI</h3>\n      <p><strong>Open Plugin Spec + CLI collection</strong></p>\n      <pre><code>copilot plugin install https://github.com/Parsifal1986/TokensBurned</code></pre>\n      <p>Ask Copilot to connect TokensBurned. Copilot hooks currently expose lifecycle events but not token totals, so the data path remains CLI assisted.</p>\n    </td>\n  </tr>\n  <tr>\n    <td width=\"50%\" valign=\"top\">\n      <h3>Cline CLI</h3>\n      <p><strong>Native afterRun usage hook</strong></p>\n      <pre><code>cline plugin install https://github.com/Parsifal1986/TokensBurned.git</code></pre>\n      <p>The plugin uploads only the usage object returned by Cline. Cline plugins currently apply to CLI, SDK, and Kanban, not the VS Code or JetBrains extensions.</p>\n    </td>\n    <td width=\"50%\" valign=\"top\">\n      <h3>OpenCode, Cursor, Aider, other</h3>\n      <p><strong>Standalone CLI</strong></p>\n      <pre><code>npm install -g tokensburned\ntokensburned connect\ntokensburned doctor</code></pre>\n      <p>Use an explicit batch import when the harness exposes observed token fields. TokensBurned does not estimate usage from prompt text and does not accept telemetry-exporter traffic.</p>\n    </td>\n  </tr>\n</table>\n\n### Compatibility at a glance\n\n| Harness | Install surface | Token source | Current level |\n| --- | --- | --- | --- |\n| Claude Code | Plugin marketplace | Session hook + approved local history | Native |\n| Codex | Plugin marketplace | Plugin hook + approved local history | Native |\n| Gemini CLI | Gemini extension | Explicit CLI import | Plugin workflow |\n| Cline CLI / SDK | Cline Git plugin | `afterRun().result.usage` | Native telemetry |\n| GitHub Copilot CLI | Open Plugin Spec | Explicit CLI import | Plugin workflow |\n| OpenCode | Standalone CLI | Explicit batch import | Fallback |\n| Cursor, Aider, others | Standalone CLI | Explicit batch import | Fallback |\n\n## Build your profile card\n\nFirst opt in with `tokensburned privacy public`. This publishes totals, harness/provider/model breakdowns, activity heatmaps, rank, and your GitHub identity. The policy belongs to the verified GitHub account, so every connected device inherits the same choice without asking again. Then open the [interactive card builder](https://tokensburned.com/#card-builder), enter your GitHub username, choose a preset, and copy the generated Markdown. Query parameters can hide published sections, but cannot enable fields disabled by the account's server-side policy.\n\nThe full card is the default:\n\n```markdown\n[![TokensBurned activity](https://api.tokensburned.com/v1/cards/u/YOUR_GITHUB_NAME.svg?theme=auto)](https://tokensburned.com/)\n```\n\nThe preview below is bundled fictional data. Rendering this README does not call the TokensBurned API.\n\n<div align=\"center\">\n  <img src=\"public/demo/card-full.svg\" width=\"840\" alt=\"Static TokensBurned card with fictional sample data\" />\n</div>\n\n### Card presets and options\n\n| Result | Query | Good for |\n| --- | --- | --- |\n| Full report | `?layout=full&heatmap=1&compare=1&rank=1&meme=0` | Profile overview |\n| Compact totals | `?layout=compact&compare=0&rank=1` | Small README footprint |\n| Meme receipt | `?layout=full&heatmap=0&compare=0&rank=1&meme=1` | A shorter, less serious card |\n| Private rank | Add `&rank=0` | Hide the site-wide rank |\n| Totals + comparison | `?layout=full&heatmap=0&compare=1` | Keep breakdowns, remove heatmaps |\n| Follow system theme | Add `&theme=auto` | Switch with the viewer's light/dark preference |\n| Fixed light or dark | Add `&theme=light` or `&theme=dark` | Keep one appearance everywhere |\n\nSupported query parameters:\n\n- `layout=full|compact`\n- `heatmap=0|1` (compact layout always disables heatmaps)\n- `compare=0|1`\n- `rank=0|1`\n- `meme=0|1`\n- `theme=auto|light|dark` (`auto` uses `prefers-color-scheme` inside the SVG)\n\n## CLI fallback\n\nThe standalone CLI is the stable escape hatch for any harness:\n\n```bash\nnpm install -g tokensburned\ntokensburned connect\n```\n\n| Command | Purpose |\n| --- | --- |\n| `tokensburned connect` | Authorize GitHub and create a 180-day device credential; the public card stays off. |\n| `tokensburned backfill --harness codex --dry-run` | Preview Codex history without uploading. |\n| `tokensburned backfill --harness claude-code --days 30` | Import an approved Claude Code range. |\n| `tokensburned backfill --all-harnesses --days 30` | Explicitly import every recognized local harness. |\n| `tokensburned server` | Show server totals and the public SVG URL. |\n| `tokensburned update` | Force a release check and print the current harness's plugin-manager command when an update is available. |\n| `tokensburned privacy` | Show the GitHub account's current public-card policy without changing it. |\n| `tokensburned privacy public` | Explicitly publish aggregate activity tied to your GitHub identity. |\n| `tokensburned privacy private` | Disable the public route and remove the stored SVG (GitHub's image cache may show the old card for up to 1 hour). |\n| `tokensburned disconnect` | Revoke this device credential; keep history and reserve its slot for up to 30 days. |\n| `tokensburned delete-server-data` | Delete server aggregates, devices, identity, and public card. |\n| `tokensburned doctor` | Show detected harnesses and data boundaries. |\n\n`burn` remains a shorter alias for `tokensburned`.\n\nThe `Stop` and `SessionEnd` hooks reduce the current transcript into the local\noutbox after every turn (parsing even a large transcript takes well under\n100 ms in a detached process), and `SessionStart` re-merges transcripts touched\nin the last two days so nothing is lost when a session never ends cleanly.\nUploads to the server happen at most once per UTC hour, aligned to the hour\nboundary the server enforces; a day the server has deferred waits on its own\nwithout holding back the others. When days are pending but the window is closed, the hook leaves behind a single waiting worker per\nmachine that uploads once the window opens and then exits, so the last data of\na session reaches the server even if no hook fires again; the server acknowledges\nonly days it actually stored and the client keeps everything else pending until\nthe next window. `tokensburned backfill` uploads immediately.\n\nWhile TokensBurned is installed but not connected, the SessionStart hook asks the\nassistant to mention the connect command at most three times (tracked in\n`~/.burn/config.json` under `onboarding.connect_notices`), then stays silent.\n\nInstalled harness plugins also perform a best-effort release check at SessionStart,\nthrottled to once every 24 hours; while the installed version is older than the\npublished one, every SessionStart reminds the assistant to mention it. Update\nfailures never block startup, and applying an available update always requires\nan explicit user request. `tokensburned update` also merges the last two days of\nevery installed harness and uploads whatever is due, so it doubles as a manual\n\"make sure everything reached the server\".\n\n## Privacy boundary\n\n| Uploaded | Never uploaded |\n| --- | --- |\n| Token counts | Prompts and responses |\n| Harness, provider, model (an unrecognized gateway is recorded by hostname only) | Source code and tool payloads |\n| Hashed session identifier | Repository names and paths |\n| 15 minute time bucket | Transcript files and paths |\n| Request count | API keys and provider credentials |\n\nThe lifecycle upload is short and best effort. Server aggregates are retained until you run `tokensburned delete-server-data`; credentials expire after 180 days and can be revoked sooner. TokensBurned installs no cron job, daemon, proxy, or Git synchronization task. See [SECURITY.md](SECURITY.md) for the complete boundary.\n\n## License\n\n[MIT](LICENSE) © 2026 [parsifal1986](https://github.com/Parsifal1986). Issues and pull requests are welcome; contributor and implementation notes live in [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [`docs/`](docs/).\n\n### Free device slots\n\nEach GitHub account has 5 device slots, shared across active devices and devices\nin a 30-day cooldown. Disconnecting revokes access immediately but reserves that\nslot for the same device for up to 30 days. Reconnecting the same device reuses the\nslot; disconnecting it again restarts the cooldown. Credential expiry releases\nthe slot immediately, including during cooldown. Reconnecting after expiry needs\na free slot and consumes a connection allowance. Other free slots remain usable.\n\nKeep the local device ID in `~/.burn` to reconnect as the same device. Disconnect\ndoes not delete cloud history. The CLI shows the server-confirmed slot release\ntime after disconnecting. Deleting local files does not release a cloud slot.\nSuccessful connections, including reconnections and credential rotations, are\nlimited per GitHub account to 5 per rolling 10 minutes and 10 per rolling 24 hours.\nDisconnecting does not refund that allowance; authorization polling does not use it.\n\nDeleting all server data removes usage, credentials, the account profile, and the\npublic card, but does not refund allowances. A keyed account identifier, recent\nconnection times, and outstanding slot release times remain until their normal\ndeadlines. Connection windows last up to 24 hours; deleted device reservations\nlast up to 30 days or credential expiry, whichever comes first. Expired records\nare cleaned up regularly. See [all usage limits](https://tokensburned.com/limits.html).\n",
  "bytes": 13716,
  "sha": "5dfc927e2ce5bda59aed276be4d808cb0fb9747e3489434db181554ed75d1e7d",
  "repo_slug": "parsifal1986/tokensburned",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_parsifal1986_tokensburned_d7d92df1/readme"
}