vibe-cafe/vibe-usage

开发工具

104 stars 质量 40 趋势 40

Repository Install

Track your AI coding tool token usage and sync to vibecafe.ai.

概览

Track your AI coding tool token usage and sync to vibecafe.ai.

README

vibe-usage

Track your AI coding tool token usage and sync to vibecafe.ai.

Quick Start

npx @vibe-cafe/vibe-usage

That’s it. The CLI opens vibecafe.ai/usage/device in your browser; sign in, confirm the verification code shown in your terminal, click 「确认链接」, and the CLI receives an API key automatically.

After approval, it will:

Save your API key to ~/.vibe-usage/config.json
Detect installed AI coding tools
Run an initial sync of your usage data
Prompt you to enable the background daemon for continuous syncing (recommended)

CI / Headless

If you don’t have a local browser (CI, remote SSH session, container), pre-issue a key at vibecafe.ai/usage/setup and pass it on the command line:

npx @vibe-cafe/vibe-usage init --manual-key vbu_xxxxxxxxxxxx

Commands

npx @vibe-cafe/vibe-usage              # Init (first run, browser login) or sync (subsequent runs)
npx @vibe-cafe/vibe-usage init         # Re-run setup via browser login
npx @vibe-cafe/vibe-usage init --manual-key    # Skip browser, use pre-issued key (CI/headless)
npx @vibe-cafe/vibe-usage sync         # Manual sync
npx @vibe-cafe/vibe-usage sync --extra-codex-home /path/to/.codex  # Add another Codex Home for this run only
npx @vibe-cafe/vibe-usage summary       # Print last 7 days as markdown (cost / tokens / by model / by project)
npx @vibe-cafe/vibe-usage summary --days N  # Same, over the last N days (1-90)
npx @vibe-cafe/vibe-usage daemon       # Continuous sync (every 30m, foreground)
npx @vibe-cafe/vibe-usage daemon install    # Install background service (systemd/launchd)
npx @vibe-cafe/vibe-usage daemon uninstall  # Remove background service
npx @vibe-cafe/vibe-usage daemon status     # Show background service status
npx @vibe-cafe/vibe-usage daemon stop       # Stop background service
npx @vibe-cafe/vibe-usage daemon restart    # Restart background service
npx @vibe-cafe/vibe-usage reset        # Delete all data and re-upload from local logs
npx @vibe-cafe/vibe-usage reset --local  # Delete this host's data only and re-upload (`--host` remains a legacy alias)
npx @vibe-cafe/vibe-usage skill         # Install skill for AI coding assistants
npx @vibe-cafe/vibe-usage skill --remove  # Remove installed skills
npx @vibe-cafe/vibe-usage status       # Show config & detected tools

Supported Tools

Tool	Data Location
Alma	Electron app-data `alma/chat_threads.db` (macOS: `~/Library/Application Support/alma/chat_threads.db`; fixture/relocation override: `VIBE_USAGE_ALMA_DB`). Reads the `usage_records` ledger plus workspace names without selecting chat bodies, message metadata, provider credentials, or full workspace paths. Provider-prefixed model identifiers are normalized to their final model segment. Cache writes are included in input usage. The ledger contains assistant responses only, so Alma emits token buckets without session timing.
Claude Code + Claude Desktop Code/Cowork	Claude Code data in `~/.claude/projects/` (tokens + sessions) and `~/.claude/transcripts/` (sessions only), plus Claude Desktop Cowork’s per-session `.claude/projects/` directories. Also scans `$CLAUDE_CONFIG_DIR` and data-bearing `~/.claude-*` profiles. All variants use the existing `claude-code` source; the parser selects the most complete copy of each session so shared/copied transcripts are not counted twice. Logs are streamed and cache creation tokens are included in input usage.
Codex CLI	`$CODEX_HOME/sessions/` and `$CODEX_HOME/archived_sessions/` (default `~/.codex`), plus an optional temporary `--extra-codex-home` or manually persisted `codexExtraHome`; a versioned local index avoids re-reading unchanged rollouts and reads only safe append tails for ordinary sessions, while fork/sub-agent replay matching, duplicate suppression, and live/archive/cross-root deduplication retain their existing semantics
Grok	`$GROK_HOME/sessions///` (default `~/.grok`); token usage from `updates.jsonl` `turn_completed.usage` (per-model `modelUsage`, cache reads, reasoning); project from `summary.json` cwd; honors `GROK_HOME`
GitHub Copilot CLI	`~/.copilot/session-state/*/events.jsonl`
CraftAgent	`~/.craft-agent/workspaces//sessions//.pi-sessions/*.jsonl`; honors `$CRAFT_AGENT_DIR` / `$CRAFTAGENT_DIR`; cache writes are included in input usage
Cursor	`state.vscdb` (SQLite, reads `cursorAuth/accessToken`, fetches CSV from `cursor.com`); cloud data is stamped with a fixed `cursor-cloud` hostname so multi-machine setups don’t double-count
DimAgent	`$DIMCODE_HOME/dimcode.sqlite` (default `~/.dimcode/v2/dimcode.sqlite`); exact usage from `usage_ledger`, with forked ledger/history copies deduplicated
Gemini CLI	`~/.gemini/tmp//chats/session-.jsonl` (current line-delimited format) and legacy `session-.json`; recurses into nested subagent sessions
OpenCode	`~/.local/share/opencode/opencode.db` (SQLite, `json_extract` query)
OpenClaw	`~/.openclaw/agents/`, `~/.openclaw-/agents/` (profile deployments); cache-creation/cache-write tokens are included in input usage
Oh My Pi	`~/.omp/agent/sessions/`, `~/.omp/profiles//agent/sessions/`, and `$XDG_DATA_HOME/omp/{sessions,profiles//sessions}`; recognizes OMP’s `$PI_CODING_AGENT_DIR`, current v3 title slots and path/hashed session directories, deduplicates copied records, includes cache writes in input, and splits reasoning from OMP’s inclusive output count
pi	`~/.pi/agent/sessions/` or `$PI_CODING_AGENT_DIR/sessions/`; cache writes are included in input usage
Qwen Code	`~/.qwen/tmp/`
Kimi Code	Current `~/.kimi-code/sessions/wd__/session_/agents//wire.jsonl` (`usage.record` deltas, including retry/compaction scope and cache creation; main/subagent wires form one session), data root resolved via `$KIMI_CODE_HOME` like the CLI itself, with project names from `session_index.jsonl`; legacy `~/.kimi/sessions/` is parsed alongside (`kimi migrate` never carries usage over, so both stores are always merged)
MiMoCode	`$MIMOCODE_HOME/data/mimocode.db`, `$XDG_DATA_HOME/mimocode/mimocode.db`, or `~/.local/share/mimocode/mimocode.db` (SQLite; exact input, output, reasoning, and cache-read tokens from assistant messages; honors `MIMOCODE_DB`; cache-write tokens are included in input usage)
Amp	`~/.local/share/amp/threads/`; cache-creation tokens are included in input usage
Droid	`~/.factory/sessions/`
DeepSeek Harness	`$DSH_HOME/sessions/` (default `~/.dsh`, fixture/relocation override: `VIBE_USAGE_DSH_SESSIONS`). Reads multi-frame Zstandard `session.jsonl.zstd` logs (built-in `node:zlib` zstd on Node ≥ 22.15, `zstd` CLI fallback) and plain `session.jsonl` logs. Usage comes from `assistant/message`: cache writes join uncached input, cache reads remain separate, and reasoning is split out of inclusive output. Fork/subagent history is de-duplicated from the immutable header: `parentSession` identifies the source and `seedLength` gives the exact leading event boundary. Inherited messages are skipped only when matching source seqs remain in the parent file; missing parents fail open. `session/end-seed` positions are not used because resumes can append the marker after real history.
Hermes	`~/.hermes/state.db` + `~/.hermes/profiles//state.db` (SQLite, multi-profile)
Kiro	Kiro CLI native event streams `~/.kiro/sessions/cli/.jsonl` (estimated tokens from message text: input = prompt + tool results, output = reply + tool calls, reasoning = thinking, cacheRead = re-sent context; thinking-block signatures excluded). Falls back to `~/Library/Application Support/kiro-cli/data.sqlite3` / `~/.local/share/kiro-cli/data.sqlite3` + optional `~/.kiro_sessions/.json` archives, then IDE `q-client.log` whole-credit deltas as `kiro-credits` (floored cumulative diff — the server stores token counts as bigint); legacy IDE `dev_data/devdata.sqlite` token telemetry is opt-in with `VIBE_USAGE_KIRO_LEGACY_TOKENS=1`
Cline	Standalone `~/.cline/` plus `/User/globalStorage/saoudrizwan.claude-dev/` across VSCode-fork hosts; migrated copies are deduplicated and empty leftover extension stores no longer count as installed
Roo Code	`/User/globalStorage/rooveterinaryinc.roo-cline/{tasks/_index.json,tasks//{history_item,ui_messages}.json}` (walks all VSCode-fork hosts)
Trae CLI	macOS: `~/Library/Caches/trae-cli/sessions/`; Windows: `%LOCALAPPDATA%/trae-cli/cache/sessions/`; Linux: `~/.cache/trae-cli/sessions/` (CLI telemetry only; Trae IDE/Trae Work chats are not supported)
Antigravity	App 2.0 `~/.gemini/antigravity/conversations/.db` and `agy` CLI `~/.gemini/antigravity-cli/conversations/.db` are parsed offline (tokens, real model display name, project, sessions); legacy App `.pb` history falls back to Connect RPC while the language server is running
WorkBuddy	Current releases: `~/.workbuddy-ai/projects/*/.jsonl`; legacy releases: `~/.workbuddy/projects/*/.jsonl` (fixture/relocation override: `VIBE_USAGE_WORKBUDDY_DIRS`). Reads usage-bearing completed assistant and `function_call` records, using the routed model identifier exposed as `providerData.requestModelId`. Splits cache reads and reasoning from inclusive input/output totals, deduplicates copied record IDs, and extracts local session timing without uploading message content.
ZCode	`~/.zcode/cli/db/db.sqlite` (SQLite; reads the `message` table for per-message tokens, model, and project `cwd`/`root`, joined to `session.directory`)

How It Works

Parses local session logs from each AI coding tool
Aggregates token usage into 30-minute buckets
Extracts session metadata where the source safely exposes user/assistant timing: active time (AI generation time, excluding queue/TTFT wait), total duration, and message counts. Alma intentionally emits buckets only because its usage ledger contains assistant responses and the parser does not read chat records.
Uploads buckets + sessions to your vibecafe.ai dashboard (always gzip-compressed, ~94% smaller)
Incremental upload: every parser emits a complete local snapshot, then only buckets/sessions that are new or changed since the last successful upload are sent — a quiet machine uploads nothing. Upload state remains in ~/.vibe-usage/state.json; failed or still-indexing parsers retain their prior state, while deleted local logs are pruned. Deleting the state file triggers a one-time full re-upload, and reset clears it automatically after deleting cloud data
Incremental Codex parsing: a versioned, disposable cache under ~/.vibe-usage/cache/codex/ stores per-rollout aggregate results and parser continuation state. Unchanged rollouts require no raw-log reads; an ordinary append reads only the new tail; forks, sub-agents, replacements, truncations, and failed safety checks fall back to the full correctness path. A bounded rolling audit occasionally re-reads one historical file. Very large first-time indexes checkpoint before the Mac app timeout and resume on the next sync instead of restarting
The Codex parser cache contains derived aggregates and replay metadata, not raw prompt or response text. It is independent of upload state and can be deleted safely (the next sync rebuilds it). reset intentionally keeps it so the required full re-upload does not also require a full disk rescan. Set VIBE_USAGE_CODEX_CACHE=0 to disable the optimization for diagnosis
SQLite-backed tools are read via Node’s built-in node:sqlite on Node ≥ 22.5 — no sqlite3 binary needed (works on Windows out of the box); on older Node the CLI falls back to the system sqlite3 executable
For continuous syncing, use npx @vibe-cafe/vibe-usage daemon or the Vibe Usage Mac app

Trust Model

vibe-usage parses local tool logs and local application state on a machine the user fully controls. The reported data is self-reported telemetry — local logs, parsers, and upload requests can all be modified by the user.

Good for visibility, not sufficient for settlement.

Suitable for:

personal analytics and efficiency review
team-internal AI coding adoption visibility
token usage trends across tools, models, and projects
rough cost estimation and anomaly detection

Not sufficient for:

financial settlement or team expense reimbursement
user rewards, credits, token, or airdrop allocation
agent contribution scoring or marketplace revenue sharing
proof-of-work / proof-of-usage or contractual billing

In short: this solves the visibility problem, not the verifiability problem. High-trust use cases need additional, independently verifiable metering layers.

AI Skill

Install vibe-usage as a skill for your AI coding assistant, so it knows how to sync usage data on your behalf:

npx @vibe-cafe/vibe-usage skill

This auto-detects installed AI tools (Claude Code, Cursor, Windsurf, Codex CLI) and writes a SKILL.md to each tool’s global skills directory. To remove:

npx @vibe-cafe/vibe-usage skill --remove

You can also install via the open skills ecosystem:

npx skills add vibe-cafe/vibe-usage

Development

Run the Node test suite locally with npm test. CI covers Node 20 and 22 on Ubuntu and macOS.

Test against a local vibe-cafe dev server without publishing:

VIBE_USAGE_DEV=1 VIBE_USAGE_API_URL=http://localhost:3000 npx @vibe-cafe/vibe-usage init
VIBE_USAGE_DEV=1 npx @vibe-cafe/vibe-usage sync

VIBE_USAGE_DEV=1 uses a separate config file (~/.vibe-usage/config.dev.json).

Config

Config stored at ~/.vibe-usage/config.json (dev: config.dev.json).

Key	Description
`apiKey`	Your API key (starts with `vbu_`)
`apiUrl`	Server URL (default: `https://vibecafe.ai`)
`hostname`	Stable device name for usage tracking (set at init, reused across syncs)
`codexExtraHome`	Optional additional Codex Home scanned together with `$CODEX_HOME` / `~/.codex`

The hostname is captured once during init and reused for all future syncs. This prevents macOS mDNS hostname changes (e.g., MacBook-Pro → MacBook-Pro-2) from creating duplicate device entries. To change it manually:

npx @vibe-cafe/vibe-usage config set hostname my-device-name

Daemon Mode

Background service (recommended)

Install as a system service for automatic background syncing:

npx @vibe-cafe/vibe-usage daemon install

This creates a user-level service (systemd on Linux, launchd on macOS) that syncs every 30 minutes and starts automatically on login. Manage with:

npx @vibe-cafe/vibe-usage daemon status
npx @vibe-cafe/vibe-usage daemon stop
npx @vibe-cafe/vibe-usage daemon restart
npx @vibe-cafe/vibe-usage daemon uninstall

For reliable operation, install globally first: npm install -g @vibe-cafe/vibe-usage

Foreground mode

Run continuous syncing in the foreground (every 30 minutes):

npx @vibe-cafe/vibe-usage daemon

Press Ctrl+C to stop.

License

MIT

View this README on GitHub

安装

npx skillfish add vibe-cafe/vibe-usage

vibe-cafe/vibe-usage

概览

README

vibe-usage

Quick Start

CI / Headless

Commands

Supported Tools

How It Works

Trust Model

AI Skill

Development

Config

Daemon Mode

Background service (recommended)

Foreground mode

License

推荐工具

安装