Attribute coding-agent token usage to the GitHub pull request that shipped it.
prtokens
reads your local Claude Code, Codex, and OpenCode transcripts, attributes token usage to the commits on your PR branch, and posts a single estimated-cost comment. Only aggregate numbers leave your machine.
-
Authenticate the GitHub CLI once:
gh auth login -
From a repository, on a branch with an open PR, run:
npx prtokens
prtokens finds the open PR, reads your local transcripts, and posts or updates the comment. Run it again anytime to refresh.
A single comment showing total estimated cost, token and session counts, models used, agent costs, and a collapsible per-commit table. The same comment is updated in place on later runs; multiple contributors each get their own labeled section.
Sessions
counts top-level coding-agent sessions. For OpenCode, child/subagent sessions are grouped under their parent session.
Example (commit table collapsed by default):
980k in / 42k out · 7 sessions
Models: claude-sonnet-4-6
, gpt-5-codex
Agents: claude-code
~$3.40 · codex
~$0.72
Commit breakdown
| Commit | Message | In | Out | Cost | Sessions |
|---|---|---|---|---|---|
a1b2c3d |
|||||
| feat: add usage readers | 420k | 18k | ~$1.55 | 3 | |
e4f5a6b |
|||||
| test: cover attribution | 310k | 12k | ~$1.10 | 2 | |
c7d8e9f |
|||||
| fix: dedupe sessions | 250k | 12k | ~$1.47 | 2 |
Generated by prtokens
| Command | What it does |
|---|---|
prtokens |
|
| Resolve the current branch's open PR, read local usage, and post or update the comment. | |
prtokens --pr <n> |
|
Target PR number <n> instead of auto-detecting from the branch. |
|
prtokens --dry-run |
|
| Print the rendered comment to stdout; post nothing. | |
prtokens --json |
|
| Print a JSON payload (rendered markdown, attribution, pricing, per-agent totals, and per-source diagnostics); post nothing. | |
prtokens --verbose |
|
| Also print per-source reader diagnostics to stderr. | |
prtokens init |
|
| Install or update the optional global pre-push hook (see below). | |
prtokens init --dry-run |
|
| Preview the hook changes without writing files. | |
prtokens status |
|
| Show pending, blocked, failed, and recently completed automatic PR comment jobs. | |
prtokens pr create -- <gh args> |
|
Run gh pr create <gh args> and attempt to post the prtokens comment after successful PR creation. |
-
Node.js 22.13+
-
GitHub CLI authenticated with
gh auth login -
Transcripts from at least one supported agent:
-
Claude Code —
~/.claude/projects -
Codex —
~/.codex/sessions
or~/.codex/archived_sessions
-
OpenCode — SQLite databases under
~/.local/share/opencode -
Claude Code —
Install globally and run the setup command to post comments automatically on every git push
:
npm i -g prtokens
prtokens init
Preview changes first with prtokens init --dry-run
.
prtokens init
writes a managed block into your global pre-push
hook. If an absolute global core.hooksPath
is already set, prtokens writes the hook there; otherwise it creates ~/.config/git/hooks/pre-push
and sets core.hooksPath
globally. A relative core.hooksPath
is rejected.
Caveats:
prtokens
must be onPATH
for hooks, or the absolute path baked in byprtokens init
must stay valid.- A repository with a local
core.hooksPath
bypasses the global hook. gh pr create
on an already-pushed branch won't trigger the hook.
When a push has an open PR, the comment is posted immediately in the background. When pushed before the PR exists, prtokens records a pending job and retries within ~30 minutes.
For the most reliable workflow, create PRs through:
prtokens pr create -- --title "My PR" --body "Description"
Everything after --
is passed to gh pr create
. If PR creation succeeds, prtokens posts the comment before exiting.
For manual setup, run prtokens init --dry-run
to see the exact managed block and its target path, then place it yourself.
Transcripts never leave your machine. The PR comment contains only aggregate numbers — token counts, dollar estimates, session counts, model names, and commit metadata already visible in the PR. The automatic queue stores only repository path, remote/branch names, head SHA, timestamps, and job status — never transcripts, prompts, or rendered comment text.
| Situation | Outcome |
|---|---|
| No open PR | Prints a hint; exits 0 |
| No transcripts | Prints a hint; exits 0 |
Missing or unauthenticated gh |
|
| Prints setup instructions; exits 1 | |
| Comment post failure | Prints rendered markdown for manual paste; exits 0 |
| Push with no PR yet (hook) | Records pending job; exits 0 |
prtokens pr create — gh fails |
|
Returns gh exit code; does not post |
|
prtokens pr create — comment fails |
|
| Prints error; exits 0 |
Costs use agent-reported values when available. Otherwise, prtokens estimates at API rates using a bundled LiteLLM pricing snapshot covering Claude models (first-party, Bedrock, and Vertex) and OpenAI GPT-5 coding-agent aliases. Subscription users may have zero marginal cost — treat the number as a cost-awareness estimate. Refresh the snapshot with npm run update-pricing
.