Work / Tokentrail
Tokentrail
Open-source TypeScript CLI
Open-source TypeScript CLI · local-first
Gallery
Claude Code writes a JSONL session log for every conversation under ~/.claude/projects/, but those logs sit there unread. Tokentrail walks the directory, attributes each session to a (repo, branch) pair, enriches with GitHub PR metadata when available, and rolls usage up into a daily per-feature ledger you can actually reason about — so "how much did this feature cost?" stops being a vibe.
It runs entirely on your machine. The default flow is a terminal report; the optional init command sets up a SwiftBar menu-bar widget showing today's running spend, a launchd daemon serving a local dashboard at 127.0.0.1:4920, and a Stop hook so new sessions ingest automatically. Notion sync is opt-in — point it at a database with a handful of named properties and Tokentrail pushes daily rollups with structured page bodies (sessions, PRs, commits).
Attribution is a priority chain: manual override → PR label → PR title → branch prefix (feat/, fix/, chore/, spike/, deps/) → mainline branch → branch slug. A .tokentrail.json config lets you extend mainline branches, branch patterns, project parent dirs, and override individual sessions without committing private feature names. Free and open source.
A CLI that traces token usage across branches, features, and pull requests — terminal report, menu-bar widget, and optional Notion sync.
What it does
~/.claude/projects/How attribution works
For each session, Tokentrail walks this priority chain and stops at the first match:
.tokentrail.jsonfeature/, fix/, chore/, spike/, deps/main, master, develop, staging, scoped per repoA debug command (tokentrail attribute --repo owner/repo --branch feature/x) shows how any given branch would bucket, so you can validate before running a session.
Setup
tokentrail init is one-shot on macOS: symlinks the SwiftBar plugin, writes a launchd plist so the dashboard auto-starts at login, installs Claude Code slash commands (/today, /rollup), and adds Tokentrail's Stop hook so new sessions ingest automatically. Re-runnable; --dry-run previews, --force replaces existing entries, and --skip-swiftbar / --skip-daemon / --skip-hook opt out of individual steps.
Local-first by default
Nothing leaves your machine unless you ask it to. Notion sync requires you to set NOTION_TOKEN + NOTION_DATABASE_ID; GitHub enrichment requires a GITHUB_TOKEN. Without those, every command runs against the local ledger.