QUANTIFY YOUR AI OUTPUT Track AI Token Usage Across All Your CLI Tools
Documentation • Dashboard • Backend API
Get started in 30 seconds:
npx vibeusage init
That's it! Your AI token usage will now automatically sync to the Dashboard 🎉
| CLI Tool | Auto-Detection | Status |
|---|---|---|
| Codex CLI | ✅ | Full Support |
| Every Code | ✅ | Full Support |
| Gemini CLI | ✅ | Full Support |
| Claude Code | ✅ | Full Support |
| Opencode | ✅ | SQLite-First Support |
| OpenClaw | ✅ | Full Support |
Whether you're using GPT-4, Claude 3.5 Sonnet, o1, or Gemini - all token consumption is unified and tracked.
VibeUsage is an intelligent token usage tracking system designed for macOS developers. Through the all-new Matrix-A Design System, it provides a high-fidelity cyberpunk-style dashboard that transforms your AI Output into quantifiable metrics, supported by the Neural Divergence Map for real-time monitoring of multi-model compute distribution.
[!TIP] Core Index: Our signature metric that reflects your flow state by analyzing token consumption rates and patterns.
High-performance dashboard built with React + Vite, featuring our cyberpunk-inspired design language with:
We believe your code and thoughts are your own. VibeUsage is built with strict privacy pillars to ensure your data never leaves your control.
| Protection | Description |
|---|---|
| 🛡️ No Content Upload | Never upload prompts or responses - only compute token counts locally |
| 📡 Local Aggregation | All analysis happens on your machine - only send 30-minute usage buckets |
| 🔐 Hashed Identity | Device tokens are SHA-256 hashed server-side - raw credentials never stored |
| 🔦 Full Transparency | Audit the sync logic yourself in src/lib/rollout.js - literally only numbers and timestamps |
Initialize your environment once - VibeUsage handles all synchronization automatically in the background:
npx vibeusage init
[!IMPORTANT] Starting with
vibeusage@0.3.0,initis the only supported command that writes local integration config. If you upgrade from an older install layout, re-runnpx vibeusage init;status,diagnostics,doctor, andsyncwill not auto-repair legacy hooks.
--link-code to authenticate via dashboard-generated codenpx vibeusage init [options]
Options:
--yes Skip consent prompts (non-interactive environments)
--dry-run Preview changes without writing files
--link-code <code> Authenticate using a link code from dashboard
--base-url <url> Override the default API endpoint
--debug Enable debug output
Once init completes, all supported CLI tools are automatically configured for data sync:
| Tool | Config Location | Method |
|---|---|---|
| Codex CLI | ~/.codex/config.toml | notify hook |
| Every Code | ~/.code/config.toml (or CODE_HOME) | notify hook |
| Gemini CLI | ~/.gemini/settings.json (or GEMINI_HOME) | SessionEnd hook |
| Opencode | OpenCode config/plugins | SQLite-first parser plugin |
| Claude Code | ~/.claude/settings.json | Stop + SessionEnd hooks |
| OpenClaw | Auto-links when installed | Session plugin (requires restart) |
No further intervention required! 🎉
If any integration drifts later, re-run npx vibeusage init. The read-only commands intentionally do not rewrite local hook/plugin state.
While sync happens automatically, you can manually trigger synchronization anytime:
# Manually sync latest local session data
npx vibeusage sync
# Check current link status
npx vibeusage status
Run comprehensive diagnostics to identify issues:
# Basic health check
npx vibeusage doctor
# JSON output for debugging
npx vibeusage doctor --json --out doctor.json
# Test against a different endpoint
npx vibeusage doctor --base-url https://your-instance.insforge.app
Enable debug output to see detailed request/response information:
VIBEUSAGE_DEBUG=1 npx vibeusage sync
# or
npx vibeusage sync --debug
# Standard uninstall (keeps data)
npx vibeusage uninstall
# Full purge - removes all data including config and cached sessions
npx vibeusage uninstall --purge
graph LR
A[Codex CLI] -->|Rollout Logs| G(Tracker CLI)
B[Every Code] -->|Rollout Logs| G
C[Gemini CLI] -->|Session Logs| G
D[Opencode] -->|SQLite DB| G
E[Claude Code] -->|Hook Output| G
F[OpenClaw] -->|Session Plugin| G
G -->|AI Tokens| H{Core Relay}
H --> I[VibeUsage Dashboard]
H --> J[AI Analytics Engine]
H --> K[Leaderboard Service]
H --> L[Public View API]
src/): Node.js CLI that parses logs from multiple AI tools and syncs token datadashboard/): React + Vite frontend for visualizationnotify-handler detects changes and triggers sync| Tool | Log Location | Override Env |
|---|---|---|
| Codex CLI | ~/.codex/sessions/**/rollout-*.jsonl | CODEX_HOME |
| Every Code | ~/.code/sessions/**/rollout-*.jsonl | CODE_HOME |
| Gemini CLI | ~/.gemini/tmp/**/chats/session-*.json | GEMINI_HOME |
| Opencode | ~/.local/share/opencode/opencode.db (legacy storage/message/**/*.json fallback) | OPENCODE_HOME |
| Claude Code | Parsed from hook output | - |
| OpenClaw | Session plugin integration | - |
| Variable | Description | Default |
|---|---|---|
VIBEUSAGE_HTTP_TIMEOUT_MS | CLI HTTP timeout in ms (0 disables, clamped 1000..120000) | 20000 |
VITE_VIBEUSAGE_HTTP_TIMEOUT_MS | Dashboard request timeout in ms (0 disables, clamped 1000..30000) | 15000 |
VIBEUSAGE_DEBUG | Enable debug output (1 or true to enable) | - |
VIBEUSAGE_DASHBOARD_URL | Custom dashboard URL | https://www.vibeusage.cc |
VIBEUSAGE_INSFORGE_BASE_URL | Custom API base URL | https://5tmappuk.us-east.insforge.app |
VIBEUSAGE_DEVICE_TOKEN | Pre-configured device token (for CI) | - |
| Variable | Description | Default |
|---|---|---|
CODEX_HOME | Codex CLI directory override | ~/.codex |
CODE_HOME | Every Code directory override | ~/.code |
GEMINI_HOME | Gemini CLI directory override | ~/.gemini |
OPENCODE_HOME | OpenCode data directory override | ~/.local/share/opencode |
npx vibeusage statusnpx vibeusage syncnpx vibeusage status --diagnosticsnpx vibeusage doctor if OpenCode usage looks incompleteinit if needed)VIBEUSAGE_DEBUG=1 npx vibeusage sync[!NOTE] Current OpenCode releases store usage in
~/.local/share/opencode/opencode.db. Legacy message JSON files are treated as fallback only. Complete OpenCode support requires thesqlite3CLI to be available onPATH.
Streak is defined as consecutive days ending today. If today's total is 0, streak will be 0.
If you expect a non-zero streak, clear cached auth/heatmap data and sign in again:
localStorage.removeItem("vibeusage.dashboard.auth.v1");
Object.keys(localStorage)
.filter((k) => k.startsWith("vibeusage.heatmap."))
.forEach((k) => localStorage.removeItem(k));
location.reload();
Complete the landing page sign-in flow again after reload.
Note: insforge-auth-token is not used by the dashboard; use vibeusage.dashboard.auth.v1.
Increase HTTP timeout for slow connections:
VIBEUSAGE_HTTP_TIMEOUT_MS=60000 npx vibeusage sync
# Clone the repository
git clone https://github.com/your-username/vibeusage.git
cd vibeusage
# Install dependencies
npm install
# Start dashboard dev server
cd dashboard
npm install
npm run dev
# Run tests
npm test
# Run local CI checks
npm run ci:local
# Validate copy registry
npm run validate:copy
# Validate UI hardcoded text
npm run validate:ui-hardcode
# Validate architecture guardrails
npm run validate:guardrails
# Build backend functions
npm run build:insforge
# Check backend build (no write)
npm run build:insforge:check
# Run smoke tests
npm run smoke
This project uses OpenSpec for spec-driven development. Before making significant changes:
openspec/project.md for project conventionsopenspec/AGENTS.md for the full OpenSpec workflowopenspec list to see active changesopenspec list --specs to see existing specificationsSee CLAUDE.md for detailed guidelines.
# Read the repository sitemap first
cat docs/repo-sitemap.md
See Issues for detailed plans.
We welcome all forms of contributions!
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)dashboard/src/content/copy.csvThis project is licensed under the MIT License.
Made with 💚 by developers, for developers
复制以下内容发送给你的 AI 助手：
请帮我安装 VibeUsage 来追踪 AI Token 用量。
执行以下命令：
npx --yes vibeusage init
安装完成后验证：
vibeusage status
或者查看完整指南: https://github.com/victorGPT/vibeusage/blob/main/docs/AI_AGENT_INSTALL.md
FAQs
Codex CLI token usage tracker (macOS-first, notify-driven).
The npm package vibeusage receives a total of 16 weekly downloads. As such, vibeusage popularity was classified as not popular.
We found that vibeusage demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.