Modern software engineering has entered an era where the primary metric of productivity is no longer just lines of code, but the volume of intelligence orchestrated through LLMs. Developers are increasingly integrating agentic tools like Claude Code and Codex into their daily workflows, yet the actual scale of this consumption remains hidden in private billing dashboards or obscure log files. There is a growing desire within the open-source community to treat AI token consumption not as a cost to be minimized, but as a badge of honor reflecting the depth of one's AI-augmented development process.

The Mechanics of Token Visualization

TokenPhage addresses this visibility gap by transforming raw usage data into dynamic GitHub README badges. The tool specifically targets the cumulative token consumption of popular AI coding interfaces, including Claude Code, Codex, and opencode. Rather than providing a static number, TokenPhage generates a comprehensive visual suite that includes a 30-day usage heatmap and a detailed breakdown of consumption by specific models. This allows developers to showcase exactly which models are driving their productivity and how their AI usage fluctuates over a monthly cycle.

To implement this, developers use the `tokenphage-cli` tool distributed via NPM. The workflow involves installing the CLI, linking a GitHub account, and allowing the tool to parse local logs. The CLI scans for critical data points including the date, the model name, and the exact token count. Once this data is harvested, TokenPhage generates a unique badge URL that can be embedded directly into a GitHub profile or project README. Because the system is designed for automation, the badges update daily, ensuring the public-facing metrics reflect the most recent coding sessions without manual intervention.

npm install -g tokenphage-cli

Customization is handled through a set of predefined themes to match the aesthetic of different developer environments. Currently, the tool supports three distinct themes: `gpu`, `claude`, and `grass-claude`. This ensures that the visual integration feels native to the project's existing design language while maintaining the clarity of the data being presented.

From Billing Metrics to Developer Identity

While many tools track token usage for the sake of budget management, TokenPhage shifts the narrative from financial cost to professional identity. The most distinct feature of the tool is the integration of an evolving mascot system. As a developer's cumulative token usage increases, the mascot within the badge evolves through five distinct stages. This mechanism effectively gamifies the act of AI-assisted coding, turning a dry utility metric into a progression system similar to the GitHub contribution graph.

This shift creates a new form of social proof in the AI era. In the past, a dense green contribution square indicated a hardworking developer; now, a high-stage TokenPhage mascot indicates a developer who has mastered the art of prompting and agentic orchestration at scale. By moving the data from a private invoice to a public README, the tool transforms token consumption into a proxy for AI fluency. The tension here lies in the transition from seeing tokens as a liability to seeing them as a testament to one's technical leverage.

This evolution suggests a future where the developer's profile is defined not just by the code they write, but by the efficiency and scale of the AI systems they manage.