cc-track-agent

Monitor your Claude Code token usage from the terminal — grouped by project and model, filtered by time range. No Anthropic API calls. No server required for standalone mode.

Requirements

• Node.js 18 or later
• Claude Code installed and used at least once (so ~/.claude/projects/ exists)

Installation

npm install -g cc-track-agent

Standalone mode — terminal dashboard

No server, no configuration needed. Just run:

cc-track run --standalone
cc-track run --standalone --user [email protected]   # optional: set your identifier

The dashboard refreshes every 10 seconds and shows usage grouped by project and model:

──────────────────────────────────────────────────────────────────
 cc-track  ·  03 Jul 2026  ·  [email protected]  ·  range: today  ·  10:45:00
──────────────────────────────────────────────────────────────────

Project                       Model            Tokens       Cost  Sessions
──────────────────────────────────────────────────────────────────
myorg/frontend                sonnet-4.6       149.3k     $9.08         3
myorg/backend                 sonnet-4.6        85.3k     $5.65         2
myorg/infra                   haiku-4.5          5.8k     $0.16         1
──────────────────────────────────────────────────────────────────
TOTAL                                          240.4k    $14.89         6

──────────────────────────────────────────────────────────────────

Time range filter

By default only today's usage is shown. Use --range to change the window:

cc-track run --standalone                  # today (default)
cc-track run --standalone --range 7d       # last 7 days
cc-track run --standalone --range 30d      # last 30 days
cc-track run --standalone --range all      # all history

Server mode — ship to team dashboard

Point the agent at a running claude-monitor server:

cc-track init --user [email protected] --server https://your-server.com --key YOUR_API_KEY

init does three things:

1. Saves config to ~/.config/cc-track-agent/config.json
2. Installs a background service that starts automatically on login
3. Starts shipping token records to the server immediately

Once initialized, the agent runs silently in the background and ships every new usage record to the server within seconds.

One-line team installer

Distribute this to every developer on your team:

curl -fsSL https://your-server.com/install.sh | bash -s -- \
  --user [email protected] \
  --server https://your-server.com \
  --key YOUR_API_KEY

CLI reference

| Command | Description | |---|---| | cc-track init --user <email> --server <url> --key <key> | First-time setup: save config and install background service | | cc-track status | Show current configuration | | cc-track run --standalone [--user <id>] [--range <r>] | Terminal dashboard — no server needed | | cc-track run | Run in foreground using saved server config | | cc-track uninstall | Stop and remove the background service |

Background service (server mode)

After cc-track init, a platform-native service is installed:

| Platform | Mechanism | Config location | |---|---|---| | macOS | launchd LaunchAgent | ~/Library/LaunchAgents/com.cc-track-agent.plist | | Linux | systemd user unit | ~/.config/systemd/user/cc-track-agent.service | | Windows | Registry Run key | HKCU\Software\Microsoft\Windows\CurrentVersion\Run |

Logs are written to ~/.config/cc-track-agent/stdout.log and stderr.log.

cc-track uninstall   # stop and remove the service

What data is read

The agent reads JSONL files written by Claude Code:

~/.claude/projects/<project>/<session-id>.jsonl

Only assistant messages with token usage are processed. User messages, tool results, and metadata lines are ignored. Zero-token synthetic entries are skipped.

What gets sent to the server (server mode only)

{
  "user": "[email protected]",
  "records": [{
    "sessionId": "abc123",
    "model": "claude-sonnet-4-6",
    "inputTokens": 1200,
    "outputTokens": 340,
    "cacheRead": 800,
    "cacheCreation": 0,
    "timestamp": "2026-07-03T10:15:00.000Z",
    "project": "myorg/myrepo"
  }]
}

Sent to POST {serverUrl}/api/usage with an x-api-key header. Cursors are persisted in ~/.claude/.monitor-state.json so no record is shipped twice across restarts.

In standalone mode, nothing leaves your machine.

Pricing used for cost estimates

Calculated locally using public Anthropic pricing (per million tokens):

| Model | Input | Output | Cache read | Cache write | |---|---|---|---|---| | claude-opus-4-8 | $5 | $25 | $0.50 | $6.25 | | claude-sonnet-4-6 | $3 | $15 | $0.30 | $3.75 | | claude-haiku-4-5 | $1 | $5 | $0.10 | $1.25 |

These are estimates only. No Anthropic API call is made.

Development

npm install
npm test           # run tests once
npm run test:watch # watch mode

Tests cover pricing math, JSONL parsing, project extraction, record transformation, and service module exports. All tests run without network access or filesystem side effects.