@_mergescout/token-tracker

CLI that tracks Claude Code token usage per developer and reports it to a Merge Scout org.

Installed as a Claude Code Stop hook — parses the session transcript when Claude Code exits and POSTs token counts (input, output, cache read, cache create) to Merge Scout. Also keeps a local JSONL log so summary works offline.

Previously published under the name llm-token-tracker. That name is now taken by an unrelated MCP-server package; this one moved to @_mergescout/token-tracker and the executable renamed to mergescout-token-tracker. If you had the old version installed, uninstall it first: npm uninstall -g llm-token-tracker.

Prerequisite — set your git identity globally

The CLI uses git config --global user.email to attribute each Claude Code session to a Merge Scout user. Set this before running setup or the hook silently drops every record. Use the email you sign into Merge Scout with.

git config --global user.email "[email protected]"
git config --global user.name  "Your Name"

setup hard-fails with clear instructions if this isn't set. setup --remote <KEY> and the standalone diagnose command verify that the email resolves to an actual Merge Scout user.

Install

# Using bun (recommended)
bun install -g @_mergescout/token-tracker

# Or using npm
npm install -g @_mergescout/token-tracker

Setup (one-time)

# Install the Claude Code hook (fails fast if git email isn't set globally)
mergescout-token-tracker setup

# Connect to Merge Scout (admin issues the key in Settings → Token Tracker)
# Also auto-runs an end-to-end check reporting auth, email attribution, and repo scope
mergescout-token-tracker setup --remote ms_abc123...

After that, every Claude Code session reports token usage automatically.

Scope: only sessions whose working directory is a clone of one of the org's selected GitHub repos are recorded in the Merge Scout dashboard. Sessions in other directories (side projects, personal repos, non-git dirs) are kept in the local log but dropped by the server. Adjust the selected set under Settings → GitHub Connection.

Commands

mergescout-token-tracker setup              Install the Claude Code Stop hook (requires global git email set)
mergescout-token-tracker setup --remote <KEY>   Connect to Merge Scout with an org API key + auto-diagnose
mergescout-token-tracker diagnose           Full end-to-end check (hook, auth, email, repo scope)
mergescout-token-tracker track              (internal — invoked by the hook)
mergescout-token-tracker summary            Show local usage summary (today)
mergescout-token-tracker summary --week     Last 7 days
mergescout-token-tracker summary --month    Last 30 days
mergescout-token-tracker summary --all      All time
mergescout-token-tracker summary --project <name>  Filter by project

Troubleshooting

If sessions aren't showing up in the Merge Scout dashboard, run mergescout-token-tracker diagnose from inside the repo where you work. It reports each link in the chain (hook installed, API key saved, git email set, email mapped to a Merge Scout user, repo in the selected-repos list) and prints a fix for any that fail.

Configuration

| File | Purpose | |------|---------| | ~/.claude/settings.json | Claude Code hook registration | | ~/.claude/token-tracker-config.json | Merge Scout API key | | ~/.claude/token-usage/usage.jsonl | Local usage log (offline backup) |

Environment variables

• LLM_TOKEN_TRACKER_URL — override the Merge Scout server URL (default: https://mergescout.com). Useful for local development.

Privacy

Only token counts and session metadata (model, turns, git email, project basename, git remote owner/repo) are sent to Merge Scout. No prompt or response content ever leaves the machine.

Publishing

Published automatically by the publish-cli.yml GitHub Actions workflow whenever packages/token-tracker/** changes on the production branch and the version in package.json differs from the latest version on npm.

To cut a release: bump version in package.json, commit, push to production. The workflow handles the rest.

Development

Runtime dependencies: none (pure Node 18+).

The CLI is CommonJS JavaScript. No build step — what you see is what ships.