VibeUsage

Track token usage across AI coding CLIs.
Local parsing, minimal data collection, and a shareable dashboard for Codex CLI, Claude Code, Gemini CLI, OpenCode, Hermes, OpenClaw, and more.

Let your agent install VibeUsage · Open Dashboard · Visit Website

Give the install guide to ChatGPT, Claude, Codex, or your preferred agent — it can set up VibeUsage for you.

Wherever you work, whichever agent you use, VibeUsage keeps your AI usage in one place.

Docs · Backend API · npm · English · 中文说明

---

VibeUsage is a token usage tracker for AI agent CLIs. It installs lightweight local hooks/plugins, reads usage from local logs or local databases, aggregates usage into time buckets on your machine, and syncs only the data needed to power a dashboard, cost breakdowns, project usage views, public profiles, and leaderboards.

It is currently macOS-first, with support focused on real developer workflows around Codex CLI, Every Code, Claude Code, Gemini CLI, OpenCode, Hermes, and OpenClaw.

Why VibeUsage

• Agent-first onboarding — hand the install guide to your AI agent, or run npx --yes vibeusage init yourself when you want manual setup.
• Multi-client tracking — unify usage across multiple AI coding CLIs in one timeline.
• Privacy-first by design — prompts, responses, code, and transcripts stay local.
• Project-aware analytics — view usage by public GitHub repository when repo identity can be resolved.
• Useful dashboard, not just raw numbers — see totals, model breakdowns, cost estimates, heatmaps, trends, and project usage.
• Shareable presence — optional public profile and leaderboard participation.
• OpenClaw support with a sanitized path — integrates through a local usage ledger instead of transcript parsing.

Quickstart

Requirements

• Node.js 20.x
• macOS is the primary supported environment today
• sqlite3 on PATH for full OpenCode support

Install and link your device

npx --yes vibeusage init

What happens next:

1. VibeUsage detects supported local AI CLIs.
2. It installs lightweight hooks/plugins where needed.
3. It opens browser auth by default, or accepts a dashboard-issued link code.
4. It performs an initial sync.

Then keep using your normal AI tools — sync runs automatically in the background.

[!IMPORTANT] Since [email protected], init is the only command that mutates local integration config. If you upgrade from an older install layout, re-run npx vibeusage init.

Install with a dashboard link code

npx --yes vibeusage init --link-code <code>

This is useful when you want to copy an install command from the dashboard or let another AI assistant perform the install for you.

Supported clients

Tool	Detection	Sync trigger / install method	Primary local data source
Codex CLI	Auto-detected	notify hook	~/.codex/sessions/**/rollout-*.jsonl
Every Code	Auto-detected	notify hook	~/.code/sessions/**/rollout-*.jsonl
Claude Code	Auto-detected	Stop + SessionEnd hooks	local hook output
Gemini CLI	Auto-detected	SessionEnd hook	~/.gemini/tmp/**/chats/session-*.json
OpenCode	Auto-detected	plugin + local parsing	~/.local/share/opencode/opencode.db (SQLite is the only supported local accounting source)
Hermes	Auto-detected when installed	plugin + local parsing	~/.vibeusage/tracker/hermes.usage.jsonl
OpenClaw	Auto-detected when installed	session plugin	local sanitized usage ledger

Hermes note

Hermes uses a dedicated plugin-ledger path:

vibeusage init installs Hermes plugin → Hermes lifecycle hooks append ~/.vibeusage/tracker/hermes.usage.jsonl → vibeusage sync parses only that ledger

• no prompt / response content upload
• no fallback parsing of ~/.hermes/state.db, ~/.hermes/sessions/, or trajectory files
• plugin hooks collect locally only; upload still happens in vibeusage sync

OpenClaw note

OpenClaw uses a dedicated privacy-preserving path:

OpenClaw session plugin → local sanitized usage ledger → vibeusage sync --from-openclaw

• no transcript parsing
• no prompt / response content upload
• requires an OpenClaw gateway restart after plugin linking

See docs/openclaw-integration.md for the exact contract.

What VibeUsage tracks

VibeUsage focuses on usage accounting, not content capture.

Tracked fields include:

• source / tool name
• model identity
• input tokens
• cached input tokens
• output tokens
• reasoning output tokens
• total tokens
• time bucket metadata
• project / public repo attribution when resolvable

What VibeUsage does not upload

VibeUsage does not upload:

• prompts
• responses
• source code
• chat transcripts
• OpenClaw transcript content
• raw workspace contents
• secrets, tokens, or credentials

For OpenClaw specifically, the supported path is limited to sanitized local usage metadata plus token counts.

How it works

graph LR
    A[Codex CLI] --> G[VibeUsage CLI]
    B[Every Code] --> G
    C[Claude Code] --> G
    D[Gemini CLI] --> G
    E[OpenCode] --> G
    F[Hermes] --> G
    H[OpenClaw] --> G
    G --> I[Local aggregation into 30-min UTC buckets]
    I --> J[VibeUsage backend]
    J --> K[Dashboard]
    J --> L[Project usage]
    J --> M[Public profile / leaderboard]

At a high level:

This is the beginning of the README. Read the rest at the original. Read the full README ↗