gitokens

gitokens

Record AI token usage while you vibe-code, and stamp it onto your next commit.

Every commit answers the question global usage dashboards can't: what did this change cost? Zero dependencies, no accounts, no daemons — just local transcript logs, two git hooks, and standard git trailers.

Between two commits, gitokens aggregates Claude Code and Codex CLI token usage (per model, including cache reads/writes) from the local transcript logs, and a prepare-commit-msg git hook appends the result to your commit message as machine-readable git trailers:

Add user authentication

AI-Model: claude-fable-5, gpt-5.6-sol
AI-Tokens: in=1204, out=8455, cache-read=203941, cache-write=40673
AI-Cost-USD: 1.23

How it works

• Claude Code writes every session transcript to ~/.claude/projects/<project>/*.jsonl; each assistant message carries model and usage (input/output/cache tokens).
• Codex CLI writes rollout files to ~/.codex/sessions/YYYY/MM/DD/*.jsonl; gitokens diffs the cumulative token_count counters (immune to duplicate events) and attributes them to the model from the surrounding turn_context.
• gitokens filters those entries to this repository (cwd match) and to the window since the last commit (a checkpoint file in .git/, updated by a post-commit hook), deduplicates streamed chunks by message + request id, and sums tokens per model.
• Costs are computed from LiteLLM's public pricing table (the same source ccusage uses), cached for 7 days at ~/.cache/gitokens/ — committing never blocks on the network; without pricing data the AI-Cost-USD line is simply omitted.
• The prepare-commit-msg hook appends the trailers via git interpret-trailers, so the data is queryable with plain git:

git log --format='%h %(trailers:key=AI-Tokens,valueonly)'

Install

npm install -g gitokens

cd your-repository
gitokens install               # one-time per repository

Or from source: git clone https://github.com/LYJW131/gitokens.git && cd gitokens && npm link.

install sets up prepare-commit-msg and post-commit hooks (it refuses to overwrite hooks it doesn't manage) and initializes the checkpoint. From then on every ordinary git commit gets stamped automatically. Requires Node 18+.

Commands

command	what it does
install	install the git hooks in the current repository
status	show AI usage since the last commit
trailer	print trailers, or append them to a commit-msg file (hook mode)
config	show or change the three trailer-line switches
checkpoint	reset the usage window to now

Trailer configuration

All three trailer lines are enabled by default. They can be switched on or off independently for the current repository:

gitokens config model off
gitokens config tokens on
gitokens config cost off

Run gitokens config to see the current settings. The switches are stored in the repository's local Git config as gitokens.trailer.model, gitokens.trailer.tokens, and gitokens.trailer.cost.

Notes & limitations

• Attribution is by time window: everything used between two commits counts toward the next commit, even chatter unrelated to the change.
• Merge, squash and amend commits are skipped.
• The transcript formats are internal to Claude Code / Codex and may change between versions.
• Sessions in linked git worktrees (Claude/Codex worktrees, git worktree add) are attributed to the main repository. For Codex worktrees that were already deleted, attribution falls back to matching the session's recorded repository URL against this repo's remotes — repos without a remote lose that fallback.
• Codex does not report cache writes, so cache-write=0 for GPT models.
• Set GITOKENS_SINCE=<ISO date> to override the window start for ad-hoc queries, e.g. GITOKENS_SINCE=2026-07-01 gitokens status.
• Gemini CLI support is a planned addition.