npcboard

CLI tool to sync your Claude Code usage stats to NPC Board - leaderboards, streaks, and analytics for Claude Code users.

Quick Start

npx npcboard init
npx npcboard sync

That's it. init walks you through setup and optionally enables auto-sync.

What It Does

NPC Board tracks your Claude Code usage across sessions: tokens used, models, tools, session duration, response times, and more. This CLI reads your local session files (~/.claude/projects/), aggregates the numbers, and uploads them to your NPC Board profile.

Your data powers leaderboards, streak tracking, achievement badges, and cost estimates on npcboard.dev.

Commands

npx npcboard init          # Interactive setup (token + auto-sync)
npx npcboard sync          # Sync usage data with progress
npx npcboard sync --quiet  # Minimal output (for auto-sync hook)
npx npcboard status        # Show config, last sync, pending sessions
npx npcboard privacy       # See exactly what data we collect
npx npcboard uninstall     # Remove hook and config
npx npcboard --version     # Print version

Auto-Sync

During init, you can enable auto-sync. This adds a SessionEnd hook to Claude's ~/.claude/settings.json that runs npx npcboard sync --quiet after every session. No cron jobs, no daemons - it just runs when your session ends.

To add it later:

npx npcboard init
# Choose "Y" when asked about auto-sync

To remove it:

npx npcboard uninstall

Privacy

We never collect your prompts, responses, code, file contents, file names, paths, API keys, secrets, or repository information.

We only collect aggregate numbers:

{
  "date": "2026-03-03",
  "tokens_input": 52340,
  "tokens_output": 18200,
  "sessions_count": 3,
  "tools_used": { "Bash": 12, "Read": 8, "Edit": 5 },
  "models_used": { "claude-sonnet-4": 2, "claude-opus-4": 1 },
  "metadata": {
    "messages_user": 12, "messages_assistant": 14,
    "api_errors": 0, "rate_limits": 0,
    "context_compactions": 1, "fast_mode_messages": 3,
    "web_searches": 2, "pr_count": 1
  }
}

This tool is fully open source. Read every line: cli/sync.ts

Reliability

• Batched uploads - large syncs are chunked into batches of 50 sessions
• Retry with backoff - network failures retry 3 times (1s, 2s, 4s)
• Per-file tracking - each file's sync state is tracked individually, so a crash mid-sync doesn't lose progress
• Offline detection - checks connectivity before syncing, skips gracefully if offline

Requirements

• Node.js 18+
• A NPC Board account and sync token

License

MIT