prtokens

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.

Quickstart

1. Authenticate the GitHub CLI once: gh auth login
2. 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.

What it posts

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):

🪙 This PR cost ~$4.12 in tokens

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

Commands

| 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. |

Requirements

• 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

Automatic runs (optional pre-push hook)

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 on PATH for hooks, or the absolute path baked in by prtokens 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.

Privacy

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.

Exit behavior

| 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 |

Pricing

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.