Why VibeStats?
Claude Code clears local session transcripts after 30 days by default (configurable via cleanupPeriodDays in ~/.claude/settings.json). Tools that read those JSONL files can only show what's still on disk — your stats silently shrink as old sessions age out.
VibeStats syncs aggregated daily stats — tokens, sessions, minutes, model breakdown, harness mix — to your private vibestats-data GitHub repo on every session, before that cleanup fires. The sync is non-destructive by design: once a day's stats are uploaded, they stay there indefinitely.
What that gets you:
- History past 30 days — months and years of usage stats, without changing Claude Code's defaults.
- Privacy by default — Claude Code's transcript cleanup keeps doing its thing; only small JSON aggregates ever leave your machine. No prompt or response content is stored or synced.
- Survives machine wipes and reinstalls — your archive lives in your private GitHub repo, not on your laptop.
- Per-machine breakdown — every machine writes its own slice; the aggregation step combines them into one heatmap.
What you get
A live heatmap on your GitHub profile (the embed above), and a full analytics dashboard at vibestats.dev/<your-username>:
Weekly model token usage shows the selected period's top six models individually and groups rank seven onward as Others. It defaults to the last 12 months, with calendar-year selection available; Weekly Token Consumption and Efficiency share the summary row equally.
Quickstart
macOS/Linux: curl installer (recommended)
curl -fsSL https://vibestats.dev/install.sh | bash
The installer handles everything in one step:
- Creates a private
vibestats-data repo in your GitHub account
- Installs the daily aggregation workflow
- Configures Claude Code and Codex hooks to sync after each session when those tools are installed
- Adds the heatmap to your profile
README.md
- Runs an initial backfill of existing session data
To sync manually without installing Claude Code or Codex hooks:
curl -fsSL https://vibestats.dev/install.sh | bash -s -- --skip-hook-configuration
vibestats sync
Run vibestats sync --backfill whenever you want to rescan all historical sessions.
Windows: PowerShell installer
On Windows, use PowerShell:
irm https://vibestats.dev/install.ps1 | iex
The Windows installer performs the same setup as the macOS/Linux installer: it installs the native Windows binary, configures Claude Code and Codex hooks when those tools are present, registers the machine, and runs an initial backfill.
VibeStats uses native Windows paths:
| Data | Windows path |
|---|
| Config, checkpoint, and log files | %LOCALAPPDATA%\vibestats |
| Binary | %LOCALAPPDATA%\Programs\vibestats |
To remove VibeStats later, run:
vibestats uninstall
Method 2: cargo install
If you already have a Rust toolchain set up and prefer crates.io:
# 1. Install the binary from crates.io
cargo install vibestats
# 2. Run the installer with --skip-binary to do the rest of the setup
# (creates the vibestats-data repo, wires hooks, registers this machine)
curl -fsSL https://vibestats.dev/install.sh | bash -s -- --skip-binary
cargo install only ships the binary — the per-account setup (private data repo, daily workflow, hook wiring, profile-README markers) still has to run. The --skip-binary flag tells the installer to use the vibestats already on your PATH instead of downloading a release tarball.
Adding a second machine
On any additional machine, re-run the same install command. The installer detects the existing vibestats-data repo and registers the new machine without overwriting anything.
How it works
VibeStats has three components that work together:
- CLI — installed locally, hooks into Claude Code and Codex to record session activity into a private
vibestats-data GitHub repo after each session.
- GitHub Action (
stephenleo/vibestats@v2) — runs daily in your vibestats-data repo, aggregates the recorded sessions, and pushes an SVG heatmap to your GitHub profile repo.
- Profile heatmap — the SVG is embedded in your profile
README.md between marker comments, updated automatically.
CLI reference
vibestats <COMMAND>
Commands:
auth Authenticate with GitHub
sync Sync all supported session data to vibestats-data
status Show current sync status and last sync time
machines Manage registered machines
uninstall Uninstall vibestats
GitHub Action inputs
| Input | Required | Description |
|---|
token | Yes | Token with Contents write access to profile-repo. The installer defaults this to your gh OAuth token; opt in during install to supply a narrower fine-grained PAT scoped to just profile-repo instead. |
profile-repo | Yes | Your GitHub profile repo in username/username format |
Contributing
See CONTRIBUTING.md for development setup, code conventions, and the release process (including how floating major tags work).
License
MIT
