This tool addresses the need for transparent tracking of token consumption and associated costs for local AI agents like Claude Code and Codex. It targets developers and researchers utilizing these models locally, providing real-time insights into usage, rate limits, and equivalent expenses, thereby enabling better resource management and cost control.

How It Works

The tracker integrates directly with Claude Code via its custom StatusLine API, pulling precise, local data on token usage, quota status (5h/7d sliding windows with countdowns), and context window utilization. For Codex, which lacks native StatusLine support, it monitors usage through available means. A central CLI Dashboard aggregates data from multiple agents, offering session-specific details and comprehensive daily, weekly, and monthly cost and usage reports. Its zero-configuration approach automatically detects installed agents, simplifying setup and ensuring data remains purely local for enhanced privacy.

Quick Start & Requirements

• Primary install: Execute curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/install.sh | bash or pip install --force-reinstall token-tracker.
• Prerequisites: Python 3.11+ (Rich library is automatically installed).
• Setup: Run tt setup to initialize configuration for Claude Code and Codex status lines.
• Usage: tt for the interactive Dashboard, tt claude, tt codex, tt daily, tt weekly, tt monthly, tt sessions. tt unsetup to uninstall.
• Links: Installation script available at https://raw.githubusercontent.com/stormzhang/token-tracker/main/install.sh.

Highlighted Details

• Multi-Agent Unified Dashboard: Tracks and switches between Claude Code and Codex within a single interface.
• Real-time StatusLine Integration: Automatically configures and updates status lines for Claude Code, displaying detailed quota, context, and cost information.
• Comprehensive Cost Analysis: Provides session, daily, weekly, and monthly cost breakdowns, with multi-agent grouping.
• Privacy-First Design: All data is stored and processed locally, with no user information collected or uploaded.
• Zero Configuration: Automatically detects and integrates with existing local AI agent setups.

Maintenance & Community

The provided README does not contain specific details regarding notable contributors, sponsorships, partnerships, community channels (like Discord/Slack), or a public roadmap.

Licensing & Compatibility

• License: MIT License.
• Compatibility: The MIT license is permissive and generally allows for commercial use and integration within closed-source projects without significant restrictions.

Limitations & Caveats

The project includes a TODO list for future enhancements, indicating ongoing development, particularly for additional data reports and multi-dimensional analysis. The Codex integration relies on default styling due to the lack of official StatusLine API support. The StatusLine display is designed to degrade gracefully on terminals with insufficient width.