A unified, lightweight usage and counter statusline engine for Claude Code, Gemini CLI, ChatGPT, Codex, and GitHub Copilot.
This utility is completely platform-agnostic (compatible with Linux Debian/Arch, macOS, and Windows) and session-agnostic (automatically parsing active directories). It serves four distinct functions:
- Live statusLine Mode (Claude Code): Hooks directly into Claude Code's native
statusLinecommand interface to show real-time context window usage, branch git changes, session cost, and 5h/7d rate-limits in your terminal. - Interactive Live Hooks (Gemini CLI): Integrates with Gemini CLI's
SessionStartandAfterAgenthook architecture. It outputs a beautiful 3-line real-time statusline directly tostderrfor perfect inline rendering in the terminal (displaying the active folder, git branch status, colour-coded context usage, session cost, and rolling 24h/7d cumulative turn quotas) while passing a compliant JSON payload. - Standalone Executive Report: A command-line dashboard (
cognitive-report) that recursively aggregates logs across all five providers (Claude Code, Gemini CLI, ChatGPT, Codex, and GitHub Copilot) using standard log and extension folders to produce an executive cognitive allocation report.
The interactive webview dashboard inside VS Code shows live aggregated usage across all providers:
The live status bar item shows total estimated cost at a glance, refreshing every minute:
The executive dashboard aggregates your cognitive usage statistics across all projects:
The live statusline renders directly beneath your active CLI prompts:
Copilot and ChatGPT/Codex log integrations are automatically traced and displayed in the Standalone Dashboard:
The vscode-extension/ directory contains a fully compiled TypeScript extension providing:
- Status Bar Item: Live aggregated token count and estimated cost (
⚡ AI: $1.23), refreshing every 60 seconds. Clicking it opens the dashboard. - Sidebar Tree View: Activity bar panel breaking down usage per provider (Claude Code, Gemini CLI, ChatGPT, Codex, GitHub Copilot) with per-provider cost and token counts.
- Webview Dashboard (
AI Usage: Show Dashboardcommand orCtrl+Shift+P → AI Usage): Full interactive breakdown using the Navy#0d1b3e/ Gold#c8a82cbrand palette.
# Build from source (requires Node.js 18+):
cd vscode-extension
npm install
npm run compile
npx @vscode/vsce package --no-dependencies
# Install the packaged extension:
code --install-extension vscode-extension/generativeai-usage-counter-1.0.0.vsixThe extension reads the same log directories as the Python engine — no additional configuration required.
- Unified Resource Tracking: Parses and de-duplicates transaction turns for Claude Code (JSONL project logs), Gemini CLI (JSON/JSONL logs), ChatGPT JSON session history (
~/.openai/), Codex JSON session history (~/.codex/), and GitHub Copilot telemetry logs. - Executive Cognitive Reports: Detailed summary of active sessions, total token volumes (input, output, cache-write, cache-read), and estimated costs for each platform.
- Project Allocation Analysis: Breakdowns of your resource consumption sorted by filesystem directory and AI tool.
- Interactive Terminal Statuslines (Claude & Gemini):
- High-resolution progress bars showing context window usage with adaptive green/yellow/red colour-coding.
- Rate-limit and rolling turn-limit indicators (with countdown timers for Claude, and rolling 24h/7d historical limit indicators for Gemini).
- Git repository branch name overlays with staged (
+) and modified (~) indicators.
- Purely Local & Safe: Operates entirely offline with standard logs. No data is transmitted externally.
- Python 3.6+ (built-in libraries only — no external packages required)
- Claude Code (v2.1.90 or later for the full JSON payload schema)
- Gemini CLI (for Gemini session directories, tracking, and settings)
To ensure both CLI frameworks are installed globally, execute:
# Install Claude Code
npm install -g @anthropic/code
# Install Gemini CLI
npm install -g @google/gemini-cliClone this repository and run the automated installer:
git clone git@github.com:neilmanfredit/GenerativeAI-usage-Counter.git
cd GenerativeAI-usage-Counter
# On Linux and macOS:
./install.sh
# On Windows (or as a cross-platform alternative):
python install.pyThis installer automatically detects which tools are available and configures them natively:
- For Claude Code: Copies the
statusline.pystatistics engine into~/.claude/(along with an OS-appropriate command wrapper) and registers it securely inside~/.claude/settings.jsonafter making a safety backup. - For Gemini CLI: Copies
statusline.pyinto~/.gemini/and registers real-timeSessionStartandAfterAgentstatus hooks inside~/.gemini/settings.jsonafter making a safety backup. - CLI Command Shortcut: Places a convenient executable
cognitive-report(orcognitive-report.baton Windows) in~/.local/bin/so you can generate your corporate resource dashboard instantly from any directory.
Run the unified command from any directory:
cognitive-reportOutputs an executive, board-ready corporate report summarizing cognitive allocation and estimated costs across all 5 AI providers with a project-by-project breakdown.
The statistics engine scans for JSON-formatted session history files inside:
- ChatGPT:
~/.openai/ - Codex:
~/.codex/
Any local tools or clients that export session histories into these folders are automatically tracked, displaying their token transmission, completion details, and estimated OpenAI API equivalent costs in the dashboard.
The paths resolution module automatically scans the standard directories where the VS Code and Visual Studio Copilot extensions write their telemetry and transaction logs:
- Windows: %LOCALAPPDATA%\GitHub Copilot (VS Code), %APPDATA%\Microsoft\VisualStudio (Visual Studio), and %APPDATA%\Code\logs
- macOS:
~/Library/Logs/GitHub Copilot/and~/Library/Application Support/Code/logs - Linux:
~/.config/github-copilot/and~/.config/Code/logs
Simply use Copilot normally in VS Code or Visual Studio, and run cognitive-report to see your Copilot token volume integrated alongside your Claude Code and Gemini CLI resource metrics.
The statusline loads automatically every time you launch Claude Code:
claudeYou can customise both the Claude Code and Gemini CLI statusline displays by setting these environment variables in your shell configuration profile (e.g., ~/.bashrc, ~/.zshrc, or Windows System Environment Variables):
| Variable | Default | Description |
|---|---|---|
CC_BAR_WIDTH |
10 |
Character width of progress bars |
CC_SHOW_GIT |
1 |
Show/hide the Git repository status |
CC_SHOW_RATE_LIMITS |
1 |
Show/hide the subscriber rate/turn limit line |
CC_SHOW_COST |
1 |
Show/hide the running turn cost on line 2 |
GEMINI_DAILY_TURN_QUOTA |
200 |
Turn count quota used for Gemini's 24h limit indicator |
GEMINI_WEEKLY_TURN_QUOTA |
1000 |
Turn count quota used for Gemini's 7d limit indicator |
CLAUDE_DAILY_TURN_QUOTA |
100 |
Turn count quota used for Claude's 24h static fallback indicator |
CLAUDE_WEEKLY_TURN_QUOTA |
500 |
Turn count quota used for Claude's 7d static fallback indicator |
Set CC_ variables to 0 to disable those respective features.
To cleanly remove all statusline wrappers, custom backend engines, CLI shortcuts, and settings/theme customisations, run:
# On Linux and macOS:
./uninstall.sh
# On Windows (or as a cross-platform alternative):
python uninstall.pyCC BY-NC-SA 4.0 — see LICENSE.