Claude Pulse

Why Claude Pulse?

The Problem: You're using Claude Code for development, but you have zero visibility into your API usage. When will you hit rate limits? How much are you actually spending? You're flying blind.

The Solution: Claude Pulse automatically analyzes your Claude Code logs to give you real-time insights into your usage patterns. No manual logging, no missed calls, no guesswork.

✨ Key Benefits

• 🚀 Zero Friction: One command syncs all your Claude Code usage automatically
• 📊 100% Accurate: No manual entry means no human error
• 🔒 Privacy First: Everything stays on your machine
• 📈 Real Insights: Understand your usage patterns and predict rate limits
• 🌍 Community Driven: Optionally share anonymous data to help everyone

Quick Start

Step 1: Sync your Claude Code usage

claude-pulse sync

Step 2: View your analytics

claude-pulse stats

That's it. No accounts, no API keys, no setup. Just pure automation.

Installation

You'll need Node.js (v18+) because this is 2025 and anything older is basically archaeology.

npm install -g claude-pulse

If you get a permission error, either sudo it or fix your npm setup (see troubleshooting below).

Commands

claude-pulse sync ⭐ Primary Command

Automatically imports all your Claude Code usage data. This is the main feature.

# Basic sync
claude-pulse sync

# Force re-processing (useful if you want to re-import everything)
claude-pulse sync --force

# Detailed output (see exactly what's happening)
claude-pulse sync --verbose

# Full control
claude-pulse sync --force --verbose

How it works: Claude Pulse scans your ~/.claude/projects/ directory for log files, extracts token usage data from assistant messages, and imports it into your local analytics database. It's smart enough to only process new or changed files, so subsequent syncs are lightning fast.

claude-pulse stats

Beautiful terminal dashboard showing your usage analytics for the last 7 days.

claude-pulse stats

Shows you:

• Total prompts and tokens used
• Average tokens per prompt
• Most used model
• Weekly limit estimates with progress bars

claude-pulse log

Secondary command for manual entry or logging usage from sources other than the Claude Code CLI.

claude-pulse log --model claude-3.5-sonnet --tokens 2150 --source cursor

| Flag | Short | What it does | Required? | |------|-------|--------------|-----------| | --model | -m | Which Claude model (like claude-3-opus) | Yep | | --tokens | -t | How many tokens you burned | Yep | | --source | -s | Where you called it from (defaults to manual) | Nah |

claude-pulse upload

Anonymously contribute your data to help the community figure out Anthropic's rate limiting patterns. Totally optional, totally anonymous.

claude-pulse upload

How It Works

🔄 Automated Sync Process

1. Discovery: Scans ~/.claude/projects/ for .jsonl log files
2. Extraction: Parses Claude Code's JSON Lines format to extract token usage
3. Deduplication: Only processes new or changed files for efficiency
4. Import: Maps Claude Code data to claude-pulse format with enhanced metadata
5. Analytics: Makes your data available for the stats dashboard

📊 Data Sources

• Primary: Claude Code CLI logs (~/.claude/projects/)
• Secondary: Manual logging via claude-pulse log
• Future: Other Claude API clients (planned)

🔒 Privacy & Security

Everything stays local in ~/.claude-pulse/ on your machine. No cloud storage, no tracking.

The upload feature is designed to be as private as possible:

• Creates a random UUID that can't be traced back to you
• Only uploads timestamp, model, and token count
• No IP logging, no tracking, no BS

Troubleshooting

"EACCES: permission denied" error

Classic npm global install issue. Two ways to fix it:

Quick fix (just get it working):

sudo npm install -g claude-pulse

Proper fix (so this doesn't happen again):

# Make a directory for global packages
mkdir ~/.npm-global

# Tell npm to use it
npm config set prefix '~/.npm-global'

# Add it to your PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
# (or ~/.zshrc if you're using zsh)

# Reload your shell
source ~/.bashrc

"No .jsonl files found" error

Make sure you've used Claude Code at least once. The sync command looks for log files in ~/.claude/projects/.

"Claude Code logs directory not found" error

Ensure Claude Code is installed and you've run it at least once to generate log files.

Contributing

Found a bug? Want to add something cool? PRs are welcome.

For big changes, probably worth opening an issue first so we can chat about it. I'm pretty responsive.

Local development

git clone https://github.com/ayumu436/claude-pulse.git
cd claude-pulse
npm install
npm test

Standard GitHub flow - fork, branch, commit, PR.

License

MIT License. Do whatever you want with it, just don't blame me if it breaks something.