QUANTIFY YOUR AI OUTPUT
Real-time AI Analytics for Codex CLI
English β’ δΈζθ―΄ζ
Documentation β’ Dashboard β’ Backend API
VibeUsage is an intelligent token usage tracking system designed specifically 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.
We believe your code and thoughts are your own. VibeUsage is built with strict privacy pillars to ensure your data never leaves your control.
- π‘οΈ No Content Upload: We never upload prompts or responses. We only compute token counts locally and send counts plus minimal metadata (timestamps, model, device).
- π‘ Local Aggregation: All token consumption analysis happens on your machine. We only relay quantized 30-minute usage buckets to the cloud.
- π Hashed Identity: Device tokens are hashed using SHA-256 server-side. Your raw credentials never exist in our database.
- π¦ Full Transparency: Audit the sync logic yourself in
src/lib/rollout.js. We literally only capture numbers and timestamps.
- π‘ Auto-Sync: Real-time interception of Codex CLI pipes with automatic background synchronization. Once initialized, your tokens are tracked and synced without any manual commands.
- π§ Universal-Sync: Native support for Codex CLI, Every Code, and the latest Claude Code. Whether it's GPT-4, Claude 3.5 Sonnet, or o1/Gemini, token consumption from all models is unified and counted.
- π Matrix Dashboard: High-performance dashboard built with React + Vite, featuring the new Matrix-A design language.
- Neural Divergence Map: Visualize multi-engine load balancing and compute distribution.
- Cost Intelligence: Real-time, multi-dimensional cost breakdown and forecasting.
- Smart Notifications: Non-intrusive system-level alerts using a Golden (Gold/Amber) visual style for high-value information.
- β‘ AI Analytics: Deep analysis of Input/Output tokens, with dedicated tracking for Cached and Reasoning components.
- π Identity Core: Robust authentication and permission management to secure your development data.
Initialize your environment once and forget it. VibeUsage handles all synchronization in the background automatically.
npx --yes vibeusage initNote: init shows a consent prompt in interactive shells. Use --yes to skip prompts in non-interactive environments.
Optional: --dry-run previews planned changes without writing files.
Note: If ~/.code/config.toml exists (or CODE_HOME), init also configures Every Code notify automatically. No further user intervention is required for data sync.
Note: If Gemini CLI home exists, init installs a SessionEnd hook in ~/.gemini/settings.json and sets tools.enableHooks = true so hooks execute. This enables all Gemini hooks; disable by setting tools.enableHooks = false (or disabling the vibeusage-tracker hook).
While sync happens automatically, you can manually trigger a synchronization or check status anytime:
```bash
# Manually sync latest local session data (Optional)
npx --yes vibeusage sync
# Check current link status
npx --yes vibeusage status# Run health checks
npx --yes vibeusage doctor
# Emit JSON report (and write to file)
npx --yes vibeusage doctor --json --out doctor.json
# Override base URL (diagnostics only)
npx --yes vibeusage doctor --base-url https://example.invalid- Codex CLI logs:
~/.codex/sessions/**/rollout-*.jsonl(override withCODEX_HOME) - Every Code logs:
~/.code/sessions/**/rollout-*.jsonl(override withCODE_HOME) - Gemini CLI logs:
~/.gemini/tmp/**/chats/session-*.json(override withGEMINI_HOME)
VIBEUSAGE_HTTP_TIMEOUT_MS: CLI HTTP timeout in ms (default20000,0disables, clamped to1000..120000).VITE_VIBEUSAGE_HTTP_TIMEOUT_MS: Dashboard request timeout in ms (default15000,0disables, clamped to1000..30000).VIBEUSAGE_ROLLUP_ENABLED: Currently ignored; rollup aggregation is disabled in code until the daily rollup table is deployed.GEMINI_HOME: Override Gemini CLI home (defaults to~/.gemini).
- 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-tokenis not used by the dashboard; usevibeusage.dashboard.auth.v1.
graph TD
A[Codex CLI] -->|Rollout Logs| B(Tracker CLI)
B -->|AI Tokens| C{Core Relay}
C --> D[VibeUsage Dashboard]
C --> E[AI Analytics Engine]
To run locally or contribute:
# Install dependencies
cd dashboard
npm install
# Start dev server
npm run devWhen debug=1 is included in a usage endpoint request, the response adds a debug object that helps the dashboard attribute slow queries without relying on response headers.
const res = await fetch(
`${baseUrl}/functions/vibeusage-usage-summary?from=2025-12-30&to=2025-12-30&debug=1`,
{
headers: { Authorization: `Bearer ${userJwt}` }
}
);
const data = await res.json();
if (data.debug) {
console.debug('usage debug', {
requestId: data.debug.request_id,
status: data.debug.status,
queryMs: data.debug.query_ms,
slowThresholdMs: data.debug.slow_threshold_ms,
slowQuery: data.debug.slow_query
});
}# Validate Copy Registry
npm run validate:copy
# Run smoke tests
npm run smoke# Generate a focused canvas for a top-level module
node scripts/ops/architecture-canvas.cjs --focus src
# Alias: --module
node scripts/ops/architecture-canvas.cjs --module dashboardThis project is licensed under the MIT License.
"More Tokens. More Vibe."