https://github.com/realkenlee/vibecheck
vibecheck β know where your AI coding tokens go. Local-first analytics for Claude Code & Codex: spend, activities, budget burn-down. Nothing leaves your machine.
https://github.com/realkenlee/vibecheck
ai-coding analytics claude-code codex local-first token-usage
Last synced: 12 days ago
JSON representation
vibecheck β know where your AI coding tokens go. Local-first analytics for Claude Code & Codex: spend, activities, budget burn-down. Nothing leaves your machine.
- Host: GitHub
- URL: https://github.com/realkenlee/vibecheck
- Owner: realkenlee
- License: mit
- Created: 2026-06-11T02:31:34.000Z (14 days ago)
- Default Branch: main
- Last Pushed: 2026-06-12T06:01:45.000Z (13 days ago)
- Last Synced: 2026-06-12T06:22:20.726Z (13 days ago)
- Topics: ai-coding, analytics, claude-code, codex, local-first, token-usage
- Language: TypeScript
- Size: 150 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# π©Ί vibecheck
[](https://github.com/realkenlee/vibecheck/actions/workflows/ci.yml)
**Know where your AI coding tokens go.** Local-first analytics for Claude Code and Codex sessions β spend, activities, budget burn-down. Free forever for individuals.
```
npx vibe-check
```
```
π©Ί vibecheck Β· all time Β· all data stays local
$239 API-equivalent spend β 477.8M tokens β 45 sessions β 20h agent runtime (β$12/h) β $1,212 saved by caching
Budget (2026-06) $122 of $200 ββββββββββββββββ 61% day 10/30 Β· projected $367 β over pace
Where tokens go (by dominant activity per turn)
activity turns tokens cost share
βββββββββββ βββββ ββββββ βββββββ βββββ
executing 2262 229.2M $107 45%
editing 728 87.1M $44.82 19%
reasoning 784 77.6M $41.89 17%
exploring 716 67.1M $34.51 14%
By model By branch (Claude Code sessions)
model calls cost branch calls cost
βββββββββββββββββ βββββ ββββββ βββββββββββββββββ βββββ ββββββ
claude-sonnet-4-6 3937 $214 feat/q2-migration 1582 $85.76
gpt-5.3-codex 171 $3.34 main 1303 $54.14
When you vibe (events by hour, local time)
00 β ββββββββββββββ
ββββ
β 23
Doctor's notes
β Context tax: 6 sessions ran past 100 turns β late turns re-read ~109k cached
tokens apiece vs ~29k early, β $84 of pure re-reading. Context is rent,
not a purchase: /compact or restart between tasks.
β Re-read tax: 351 repeat file reads inside sessions (~1.5MB re-entering
context) β main.py alone was read 85Γ in one session.
Β· All 32 compactions were auto-forced at the context ceiling β each shed ~155k
tokens you'd been re-paying every turn.
Β· 44% of spend is command-running turns. Verbose build/test output is
token-hungry β pipe through tail/grep, silence noisy commands.
β Healthy cache: 99% of input was served from cache, saving $851 vs list price.
β Lean tool results: ~1.5KB per tool turn on average.
```
## The problem
Every developer now has an AI usage limit β and no instrument panel. Your agents already log everything (every token, tool call, and model) into local JSONL files nobody reads. vibecheck reads them and answers:
- **Am I going to blow my monthly limit?** β `--budget` burn-down with projection to month end
- **What activities eat my tokens?** β editing vs. executing vs. exploring vs. reasoning, per turn
- **What did that branch cost?** β spend by branch, project, model, agent, and day
- **What is caching saving me?** β vs. API list price (often 5Γ the headline spend)
One normalized report across Claude Code and Codex. More agents coming.
## Privacy
**Everything runs locally. Nothing leaves your machine.** No telemetry, no accounts, no uploads. It's a read-only parser over files you already have. Prompt and code content is never parsed β only token counts, models, tool names, and timestamps.
## Install
```bash
npx vibe-check # zero-install β if you run Claude Code, you already have Node
```
No Node? Locked-down laptop? Grab a **single-file executable** from
[Releases](../../releases) (macOS arm64/x64, Linux x64/arm64, Windows) β no runtime,
no dependencies, one artifact to checksum and allowlist.
### No install at all β as a Claude Code skill
You already have an agent that can read the logs. Install vibecheck as a [skill](skill/SKILL.md):
```bash
mkdir -p ~/.claude/skills/vibecheck && curl -fsSL https://raw.githubusercontent.com/realkenlee/vibecheck/main/skill/SKILL.md -o ~/.claude/skills/vibecheck/SKILL.md
```
Then ask Claude Code *"where do my AI tokens go?"* (or run `/vibecheck`). The skill encodes the
same parsing rules this CLI is tested against β message-id dedupe, cache-subset splits, list
prices β and instructs Claude to compute via a throwaway script, never by reading your logs
into context. Same privacy contract: everything stays local.
## Usage
```bash
npx vibe-check # full report, all time
npx vibe-check --days 30 # last 30 days
npx vibe-check --month 2026-05 # one calendar month (reconciliation)
npx vibe-check --project api # scope everything to one project (any substring)
npx vibe-check --branch q2-migration # β¦or to one git branch β what did it cost?
npx vibe-check --agent codex # one agent only: claude-code | codex
npx vibe-check months # month-over-month trend with Ξ%
npx vibe-check --budget 200 # monthly soft limit β burn-down + projection
npx vibe-check doctor # just the diagnosis β doctor's notes only
npx vibe-check doctor --fail-on-warn # exit 1 on any β note β CI hygiene gate
npx vibe-check sessions # most expensive sessions, span + turns
npx vibe-check sessions # drill in: gaps, compactions, activity split
npx vibe-check wrapped --out wrapped.svg # shareable card (aggregates only)
npx vibe-check wrapped --month 2026-06 --out june.svg # "AI Coding Wrapped Β· June 2026"
npx vibe-check web # static HTML dashboard β no server, opens in browser
npx vibe-check --json # machine-readable, pipe it anywhere
```
Set `VIBECHECK_BUDGET=200` to make the budget bar permanent.
`wrapped` renders a 1200Γ630 card built to be posted β aggregate numbers only, never project or branch names (sample below uses synthetic data):
Or as a library:
```ts
import { parseClaudeDir, totals, byActivity, budgetStatus } from 'vibe-check'
const { events } = parseClaudeDir(`${process.env.HOME}/.claude/projects`)
console.log(byActivity(events))
```
## For teams & enterprise
ICs get visibility for free. Engineering leaders get the questions ICs can't answer alone: *is our AI spend producing edits or spinning on retries? Which teams are over their soft limits? What did the migration actually cost?*
The bridge is `vibecheck export` β an **aggregates-only** JSON report each developer can inspect line-by-line before sharing:
```bash
vibecheck export --days 30 --out report.json # totals, activities, models, daily spend
vibecheck export --anonymous # β¦without your git name/email
vibecheck export --include-projects # opt-in: project + branch names
```
By default the export contains **no prompts, no code, no file paths, no session ids, no project or branch names** β read [`src/export.ts`](src/export.ts), it's one screen of code. The full schema is documented in [`docs/report-schema.md`](docs/report-schema.md) (additive-only within v1; a test keeps doc and code in sync). Doctor's notes travel as **stable ids + levels only** (never the rendered text); the id vocabulary is documented in [`docs/doctor-notes.md`](docs/doctor-notes.md).
**vibecheck for Teams** (hosted rollups, org-wide burn-down, activity benchmarks, gateway-level capture) is in design. Interested? β khflee@gmail.com
## Supported agents
| Agent | Data source | Status |
|---|---|---|
| Claude Code | `~/.claude/projects/**/*.jsonl` | β
|
| OpenAI Codex CLI | `~/.codex/sessions/**/*.jsonl` | β
|
| Gemini CLI | β | planned |
| Cursor | β | planned |
| opencode | β | planned |
## Accuracy notes
- Costs are **API list-price estimates** (per-MTok rates in [`src/pricing.ts`](src/pricing.ts)). Subscription users: read it as "value consumed," not "money billed."
- Claude Code streams duplicate assistant records β vibecheck dedupes by message id (naive parsers over-count by ~30%).
- Codex `cached_input_tokens` is a subset of `input_tokens` β vibecheck splits it out before pricing.
- Activity attribution is per-turn by dominant tool (precedence: editing > executing > delegating > exploring > planning). Read it as "cost of turns spent doing X."
- Unparseable lines are counted and surfaced β these JSONL schemas are undocumented and drift between agent versions. If you see the schema-drift warning, please [file a drift report](../../issues/new?template=schema-drift.yml) β it asks for counts and key names only, never your transcripts.
## Development
Parsers are the product, so everything is fixture-tested:
```bash
npm install
npm test # 112 tests over synthetic fixtures encoding every schema gotcha
npm run dev # build + run against your own sessions
```
## Roadmap
- [x] Activity attribution ("where tokens go")
- [x] Budget burn-down with month-end projection
- [x] Branch-level cost attribution
- [x] Aggregates-only team export
- [x] Session drill-down (`vibecheck sessions`, per-session detail via `sessions `)
- [x] Doctor's notes (actionable diagnosis: cache health, context tax, idle gaps, compaction receipts, re-read tax, failure tax, verbosity drift)
- [x] "AI Coding Wrapped" shareable card (`vibecheck wrapped`, SVG, aggregates only)
- [x] Local dashboard (`vibecheck web` β single static HTML file, no server, no JS)
- [ ] Gemini CLI, Cursor, opencode parsers
- [ ] vibecheck for Teams (hosted)
## License
MIT β free for everyone, forever. The CLI will never phone home.