{
  "markdown": "# vaper\n\nA Claude Code status line widget that converts today's token energy into one of four absurd units: water boiled, Big Macs, 9mm rounds, or 2010-era BTC mined.\n\n```\n🚬💧 7.63 L boiled today                   # default\n🫦🍔 8.40 Big Macs' calories burned today  # /vaper:mode calories\n💥🔫 10,173 9mm rounds today               # /vaper:mode bullets\n🤞₿ 5.49 BTC (2010) mined today            # /vaper:mode btc\n```\n\nIt scans your Claude Code session transcripts on disk, sums today's token usage across every project, multiplies by per-token-type joule estimates to get a total energy in joules, then divides by the chosen mode's denominator. Same joule total, four different jokes — switch modes with `/vaper:mode <name>`.\n\n## Install\n\n```\n/plugin install vaper\n/vaper:init\n```\n\nRestart Claude Code and the widget appears at the bottom of the screen, refreshing on its own after every assistant turn.\n\n`/vaper:init` writes a launcher to vaper's plugin data directory and adds a `statusLine` block to `~/.claude/settings.json` pointing at it. The launcher is a 4-line `sh` script — no glob, no PATH lookup, no wrapper-finding logic at refresh time. Vaper composes cleanly into any existing `statusLine` (e.g. a persona-kit `statusline-multi.sh`) by appending itself at the innermost position.\n\nA `SessionStart` hook keeps the launcher in sync with the latest installed `water-meter.py`, so `/plugin update` and reinstalls are transparent — no further action required.\n\n## Modes\n\nSame joules total, four different jokes. Switch with `/vaper:mode <name>`:\n\n```\n/vaper:mode water\n/vaper:mode calories\n/vaper:mode bullets\n/vaper:mode btc\n```\n\nMode is stored as a one-line text file in vaper's plugin data directory; the launcher reads it on every refresh. No restart, no `settings.json` edit, no mode flag in your status line command.\n\n| Mode | What it shows | Constant |\n| --- | --- | --- |\n| `water` (default) | L of water heated from 20°C and fully vaporized | 2,592 J/mL |\n| `calories` | Big Macs of food energy | 2.36 MJ/Big Mac |\n| `bullets` | 9mm rounds' worth of chemical energy (powder, not muzzle) | 1,944 J/round |\n| `btc` | BTC you could have mined in 2010 with that energy | 3.6 MJ/BTC (1 kWh) |\n\nAll four numbers come from the same joules total — different denominators, same energy. The constants are tunable in `scripts/water-meter.py` if you have stronger opinions about powder loads or 2010 mining hash rates.\n\n## Manage\n\nWhile installed, you can pause and resume the widget without uninstalling:\n\n| Command | Effect |\n| --- | --- |\n| `/plugin` | Opens the four-tab UI: Discover, Installed, Marketplaces, Errors |\n| `/plugin disable vaper` | Pauses the plugin (cache stays on disk) |\n| `/plugin enable vaper` | Resumes a previously disabled plugin |\n| `/reload-plugins` | Picks up changes after editing the script in `~/.claude/plugins/cache/...` without restarting |\n\nThere are `claude plugin <cmd>` CLI equivalents (`claude plugin disable vaper`, etc.) for shell scripts.\n\n## Uninstall\n\n```\n/vaper:uninstall\n/plugin uninstall vaper\n```\n\n`/vaper:uninstall` removes vaper from your `statusLine` (preserving any wrapper around it) and deletes the launcher. `/plugin uninstall vaper` then removes the plugin and its data directory. Nothing else lingers — no stable wrappers in `~/.local/bin`, no temp files, no daemons, no global git config, no hooks. If you skip `/vaper:uninstall`, the only residue is a stale `statusLine.command` path in your `settings.json` pointing at a (now-deleted) launcher; the status line will simply go blank until you remove the entry.\n\n## Tuning\n\nThe four energy coefficients are constants at the top of `scripts/water-meter.py`. Open the installed copy and edit them in place:\n\n| Constant | Default | Meaning |\n| --- | --- | --- |\n| `J_PER_OUTPUT_TOKEN` | `3.0` | Each generated token needs a full forward pass — dominant cost. |\n| `J_PER_INPUT_TOKEN` | `0.6` | Prefill is parallelized, so input tokens are ~5× cheaper than output. |\n| `J_PER_CACHE_CREATION_TOKEN` | `0.6` | Same compute path as fresh input. |\n| `J_PER_CACHE_READ_TOKEN` | `0.03` | Mostly memory I/O — the KV cache is already populated. |\n\nBigger numbers = bigger meter. Smaller numbers = smaller meter. They are estimates, not measurements (see *Caveats*).\n\n## How it works\n\nClaude Code already writes every session as JSONL under `~/.claude/projects/<project>/<session-id>.jsonl`, and every assistant message line carries `message.usage` with input/output/cache token counts and an ISO timestamp. The script:\n\n1. Computes the local-midnight cutoff.\n2. Globs all session files, fast-skipping any whose mtime is older than today.\n3. Reads remaining files line-by-line, summing today's tokens by category.\n4. Multiplies by the per-type joule coefficients above to get a total in joules.\n5. Divides that total by the chosen mode's denominator — 2591.88 J/mL for water (sensible heat 20°C → 100°C plus latent heat of vaporization), 2,355,592 J/Big Mac for calories, 1944 J for bullets, 3.6 MJ for btc.\n6. Prints one line in the mode's unit.\n\nA full scan takes ~25 ms on a busy day; the status line debounce is 300 ms.\n\n## Caveats\n\n- The energy coefficients are **estimates**, derived from public LLM-energy research (Patterson 2021, Luccioni 2023, EPRI 2024). Anthropic does not publish per-token figures. If you have better numbers, edit the constants.\n- Scope is **all projects on this machine**. If you only want one project, change `SESSIONS_GLOB` in the script.\n- \"Today\" is **local midnight**.\n\n## Privacy\n\nvaper runs entirely on your local machine. It reads Claude Code's session transcript files at `~/.claude/projects/*/*.jsonl` — files Claude Code already writes locally for its own use — and sums today's token counts.\n\n- It transmits **nothing** to any server, ever.\n- It collects no telemetry, analytics, or usage stats.\n- It has no network code: no `requests`, no `urllib`, no sockets.\n- The displayed value is computed locally and never leaves your machine.\n- The only files it writes are its own launcher and a one-line mode file inside the plugin data directory.\n\nThe whole script is at [`scripts/water-meter.py`](scripts/water-meter.py).\n\n## Develop\n\nTo work on the plugin locally:\n\n```\ngit clone https://github.com/year-of-the/vaper\ncd vaper\nchmod +x scripts/water-meter.py\necho '{}' | scripts/water-meter.py    # should print \"🚬💧 ... boiled today\"\n```\n\nFor a tighter dev loop, point `statusLine.command` at the absolute path of the cloned `scripts/water-meter.py` directly. No marketplace install needed.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 6583,
  "sha": "fe6245799946a0efd3c5b7d7342d2f854424fd802b025d2534b03a24d3a38fa2",
  "repo_slug": "year-of-the/vaper",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_year_of_the_vaper_vaper_30f27aab/readme"
}