# Prtokens – See how much AI agent tokens cost a PR

> Source: <https://github.com/SamuelZ12/prtokens/>
> Published: 2026-06-15 19:24:15+00:00

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

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`

.