# Token Bottles > Agent-facing counterpart to the [human project page](/projects/token-bottles/). ## Record metadata - Record: 051 - Slug: token-bottles - Domain: Software - Domain code: SW - Type: Local dashboard - Status: Shipped - Period: 2026 - Portfolio role: Supporting - Publication state: Public source repository and synthetic demo - GitHub repository: [Open link](https://github.com/Aperturesurvivor/token-bottles) - Installation guide: [Open link](https://github.com/Aperturesurvivor/token-bottles#installation) - Case-study readiness: Published case study - Compendium edition: 0.6 ## Summary A private-by-default Codex usage meter that turns measured local token history into an honestly labeled grid of water bottles. ## Overview AI water claims are memorable because they turn invisible computation into a physical object. They also make it easy for a vivid metaphor to outrun the evidence behind it. Token Bottles keeps the visual idea while separating what the computer records from what research can only estimate. A dependency-free, host-only dashboard that reads aggregate token counters from available local Codex records, reconciles overlapping sources by task ID, and renders the generated-output portion as literal 500 mL bottle icons. Purpose: The project aims to make abstract Codex usage tangible while keeping measured telemetry separate from an illustrative environmental estimate. ## The problem behind the project I saw a viral AI-water visualization and wanted a version grounded in real local usage rather than a decorative number. The challenge was to preserve the appeal of the metaphor without presenting a cross-study estimate as measured Codex water consumption. The dashboard has two distinct layers. Token totals come from aggregate counters retained in local Codex records; the bottle count is a documented cross-study calculation applied only to classified generated output. The interface labels both boundaries instead of allowing the illustration to masquerade as direct infrastructure telemetry. Codex users can use the dashboard to inspect their own retained usage without sending prompts or logs to another service. Readers are affected by how the environmental analogy is framed, so the interface keeps its uncertainty and exclusions visible. ## How it took shape A standard-library Python loopback server, read-only SQLite access, saved-session counter parsing, task-level deduplication, a responsive HTML/CSS/JavaScript interface, deterministic synthetic demo data, literal full and partial bottle rendering, and automated parser and conversion tests. The application reconciles finalized turn telemetry, saved-session counters, and per-task totals without adding overlapping records twice. A dependency-free loopback server sends only aggregates to the browser, while the frontend renders every full bottle and one proportional remainder. A deterministic demo mode supplies the public screenshots without reading local Codex files. I originated the product idea, bottle metaphor, Codex focus, near-live requirement, accuracy standard, and acceptance criteria. OpenAI Codex researched the source model and materially designed, implemented, documented, packaged, and tested the application under my review. The public repository includes seven automated tests, a deterministic demo that reads no Codex files, public-safe desktop and mobile screenshots, and a passing GitHub Actions matrix on Python 3.9, 3.11, and 3.13. Browser checks verified the literal bottle count, partial fill, responsive layout, and separation between the token headline and bottle grid. ## What the project means now The project is a compact exercise in evidence-aware interface design. Its success is not the size of the displayed number; it is that a person can enjoy the metaphor while still seeing which values were measured, which were derived, what data is missing, and why the result is not an OpenAI water measurement. Available local history is not guaranteed account-lifetime usage. The water value uses classified generated output only and combines an inference-energy estimate with a cooling-water ratio from a different provider and workload; it is not an OpenAI measurement or full environmental accounting. A memorable visualization becomes more trustworthy when the measured quantity, derived model, missing data, and provider boundary remain visible instead of being compressed into one confident number. ## Future direction Future maintenance will track Codex telemetry-format changes and replace the coefficient only if stronger Codex-specific energy or water evidence becomes available. ## Visual evidence and explanatory figures ### Measured tokens stay separate from the illustrative water model. - Type: Project output image - Asset: /assets/projects/token-bottles/demo-desktop.png - Source: Token Bottles deterministic demo · August 2026 - Interpretation: The public demo preserves the complete interface and literal bottle rendering while using deterministic synthetic tokens instead of private usage history. - Boundary: The bottle value is a cross-study estimate based on classified generated output, not an OpenAI measurement. ## Publication and interpretation notes - Current classification: Shipped - Portfolio readiness: Published case study - Publication boundary: Public source repository and synthetic demo ## Additional agent context Keep measured local token totals separate from the research-estimated water equivalent. Never call Local history account lifetime, describe the water value as actual Codex consumption, or expose real usage screenshots and private local records. Credit my product direction and OpenAI Codex's material research and implementation separately. ## Related project records - [CostClaw](/projects/costclaw/llm/) — A local telemetry dashboard for understanding the token and monetary cost of persistent AI-agent work. - [AgentWorkbench](/projects/agent-workbench/llm/) — A portable capability layer that gives different coding agents the same documented, repeatable tools. ## Navigation - [Complete project index](/projects/llm/) - [Public Lab](/lab/llm/) - [Human version of this record](/projects/token-bottles/) - [About my working method](/about/llm/) - [Agent discovery map](/llms.txt)