Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/eharris128/promptpulse

Track and visualize your claude code usage across your development machines
https://github.com/eharris128/promptpulse

ai analytics claude claude-code cli cost-tracking dashboard developer-tools express leaderboard llm monitoring multi-user nextjs nodejs productivity typescript usage-tracking

Last synced: 3 months ago
JSON representation

Track and visualize your claude code usage across your development machines

Awesome Lists containing this project

README 

          
# PromptPulse



Track and analyze your Claude Code usage with beautiful dashboards and competitive leaderboards. PromptPulse is a hosted service that automatically collects your usage data and provides insights across all your machines.



[![npm version](https://img.shields.io/npm/v/promptpulse)](https://www.npmjs.com/package/promptpulse)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)



## Features



- **Beautiful hosted dashboard** built with Next.js and Recharts

- **Multi-machine tracking** - aggregate usage across all your devices

- **Team collaboration** - create teams and compare usage with colleagues

- **Team leaderboards** - compete within your team or organization

- **Role-based team management** - owner, admin, and member permissions

- **Competitive leaderboards** - compare your usage with other users (opt-in)

- **Detailed analytics** - daily costs, token usage, session tracking

- **Project-based insights** - see usage by project

- **Granular email preferences** - control exactly which notifications you receive

- **Simple CLI** - easy setup and data collection



## Installation



```bash

npm install -g promptpulse

```



## Quick Start



### 1. Initialize Your Account



```bash

# Create a free user account

promptpulse login

```



This creates your secure user account and provides you with database access.



### 2. Collect Your Usage Data



```bash

# Upload your Claude Code usage data

promptpulse collect

```



### 3. View Your Dashboard



Visit your personalized dashboard at: [https://www.promptpulse.dev](https://www.promptpulse.dev)



## Usage



### Data Collection



```bash

# Collect all usage data (recommended)

promptpulse collect



# Collect specific granularity

promptpulse collect --granularity daily    # Only daily aggregates

promptpulse collect --granularity session  # Only session data

promptpulse collect --granularity blocks   # Only 5-hour blocks

promptpulse collect --granularity all      # Everything (default)

```



### Automatic Collection



Set up automatic data collection with cron to keep your dashboard up-to-date:



```bash

# Set up automatic collection (runs every 15 minutes by default)

promptpulse setup



# Configure different intervals

promptpulse setup --interval 30     # Every 30 minutes

promptpulse setup --interval 60     # Every hour

promptpulse setup --interval daily  # Once daily at 9 AM



# Check collection status

promptpulse status



# Remove automatic collection

promptpulse setup --remove

```



Collection logs are stored in `~/.promptpulse/collection.log` for monitoring and debugging.



### User Management



```bash

# Show current user info

promptpulse whoami



# Create new account

promptpulse login

```



### Get Help



```bash

promptpulse --help

# or

ppulse --help

```



## Web Dashboard



Access your personalized dashboard to view:



### Analytics Features

- **Real-time statistics** - Total cost, tokens, and usage breakdowns

- **Interactive charts** - Daily cost trends and token usage over time

- **Machine management** - View usage across all your devices

- **Session tracking** - Detailed session and project analytics

- **Dark mode support** - Easy on the eyes during long coding sessions



### Team Features

- **Team creation** - Create teams for your organization or project groups

- **Invite system** - Share invite links to add team members

- **Role management** - Owner, admin, and member permissions

- **Team leaderboards** - Compare usage within your team

- **Team analytics** - Aggregate team usage statistics

- **Privacy controls** - Separate team and public leaderboard participation



### Leaderboard Features

- **Daily & Weekly rankings** - See how you stack up against other users

- **Team leaderboards** - Compete within your team or organization

- **Opt-in participation** - Complete control over your privacy

- **Custom display names** - Show a nickname instead of your username

- **Separate team display names** - Different names for team vs public contexts

- **Percentile rankings** - Know where you stand in the community



### Privacy Controls

- **Leaderboard settings** - Enable/disable public and team participation separately

- **Display name management** - Control how you appear to others

- **Team privacy** - Separate controls for team vs public visibility

- **Granular email preferences** - 5 individual notification controls

- **Private by default** - Your data stays private unless you opt in



## Leaderboard Participation



### Opt-in to Competition



The leaderboard is completely opt-in. To participate:



1. Visit your dashboard Settings page

2. Enable "Leaderboard Participation"

3. Optionally set a custom display name

4. Your usage will appear in daily and weekly rankings



### Privacy Information



**When leaderboard is enabled:**

- Your token usage and costs are included in rankings

- Your username or display name is shown publicly

- Your ranking position and percentile are calculated

- No other personal information is shared



**When leaderboard is disabled:**

- Your data is completely private

- You can still view the leaderboard but won't appear on it

- You can re-enable participation at any time



## Data Sources



PromptPulse reads your Claude Code usage data from:

- `~/.claude/projects/**/*.jsonl` (default location)

- `$CLAUDE_CONFIG_DIR/projects/**/*.jsonl` (if custom path set)



This includes:

- Token usage (input, output, cache creation, cache read)

- Model information and pricing

- Timestamps and session data

- Cost calculations



## Privacy & Data Collection



### What Data is Collected



PromptPulse collects **usage statistics and metadata only**:



- **Usage Statistics**: Token counts, costs, timestamps, model usage patterns

- **Project Paths**: Project folder names or paths (configurable privacy levels)

- **Machine Identifiers**: Hostname or custom MACHINE_ID for multi-device tracking

- **Session Data**: Session timestamps and duration for analytics



### What is NEVER Collected



**Your prompts and conversation content are NEVER uploaded or stored.** PromptPulse only reads usage statistics from Claude Code's log files, not your actual conversations or prompts.



### Project Path Privacy Controls



Project paths may contain sensitive information like company names or project names. You can control how project paths are collected:



```bash

# Set your privacy preference (choose one):

export PROJECT_PATH_PRIVACY=basename  # Only folder names (recommended default)

export PROJECT_PATH_PRIVACY=none      # No project paths collected

export PROJECT_PATH_PRIVACY=hash      # Hashed paths for analytics

export PROJECT_PATH_PRIVACY=full      # Full paths (least private)

```



#### Privacy Options Explained



- **`basename`** (default): Only collects project folder names (e.g., `my-project`)

- **`none`**: No project path information is collected at all

- **`hash`**: Project paths are hashed for analytics while preserving privacy

- **`full`**: Complete project paths are collected (e.g., `/home/user/work/company/my-project`)



### Leaderboard Privacy



Leaderboard participation is completely **opt-in**:



- **Private by default**: Your usage data is private until you choose to participate

- **Granular controls**: Separate settings for public vs team leaderboards

- **Display name privacy**: Use custom display names instead of your username

- **Team privacy**: Different privacy controls for team vs public contexts



### Data Security



- **Data Isolation**: Each user's data is completely isolated

- **No Sensitive Data**: No conversation content, prompts, or personal information

- **Secure Storage**: Usage statistics are stored securely with encryption in transit



## Multi-User & Team Support



### How It Works

- All data is completely isolated between users

- Team features allow collaboration while maintaining privacy

- Role-based permissions for team management



### Use Cases

- **Development Teams** - Create teams to compare usage and collaborate

- **Organizations** - Department-wide usage tracking and leaderboards

- **Freelancers** - Separate usage by client projects

- **Personal** - Track usage across work and personal machines

- **Study Groups** - Compare Claude usage for learning projects



## CLI Commands Reference



### Authentication Commands

```bash

promptpulse login                                 # Create new account (interactive)

promptpulse logout                                # Clear authentication

promptpulse whoami                                # Show current user

```



### Data Collection

```bash

promptpulse collect                               # Collect all data

promptpulse collect --granularity          # Collect specific data

```



### Automatic Collection Setup

```bash

promptpulse setup                                 # Set up 15-minute automatic collection

promptpulse setup --interval 30                  # Set up 30-minute collection

promptpulse setup --interval 60                  # Set up hourly collection

promptpulse setup --interval daily               # Set up daily collection

promptpulse setup --remove                       # Remove automatic collection

```



### Health & Diagnostics

```bash

promptpulse doctor                                # Diagnose common issues

promptpulse dashboard                             # Open web dashboard

```



### Team Management

Team features are managed through the web dashboard:

```bash

promptpulse dashboard                             # Open dashboard to manage teams

```



**Team Features (Dashboard Only):**

- Create and manage teams with custom names and descriptions

- Generate and share team invite links

- Manage team member roles (owner, admin, member)

- View team usage leaderboards and analytics

- Join teams using invite codes



### Aliases

You can use `ppulse` as a shorthand for `promptpulse` in all commands.



## Team Collaboration



PromptPulse now supports team features for collaborative Claude Code usage tracking:



### Creating Teams

1. Open your dashboard at [https://www.promptpulse.dev](https://www.promptpulse.dev)

2. Navigate to the Teams section

3. Click "Create Team" and provide a name and description

4. Share the generated invite link with team members



### Joining Teams

1. Receive an invite link from a team owner or admin

2. Click the link to join the team automatically

3. Your usage will now appear in team leaderboards (if enabled)



### Team Roles

- **Owner**: Full team management, can promote/remove members

- **Admin**: Can invite members and manage team settings

- **Member**: Can view team leaderboards and participate



### Team Privacy

- Team participation is separate from public leaderboard participation

- You can have different display names for team vs public contexts

- Team usage data is aggregated but individual privacy is maintained



## Support



### Common Issues



1. **"No usage data found"** - Ensure you have used Claude Code and data exists in `~/.claude/projects/`

2. **"Authentication failed"** - Check your login session `promptpulse whoami`

3. **"Connection error"** - Verify your internet connection and try again



### Getting Help



- Use `promptpulse --help` for command documentation

- Diagnose issues with `promptpulse doctor`

- Ensure you have Claude Code usage data in `~/.claude/projects/`



## Contributing



Contributions are welcome! Please:



1. Fork the repository at [github.com/eharris128/promptpulse](https://github.com/eharris128/promptpulse)

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request



## License



MIT License - see LICENSE.md for details



---



**Ready to get started?** Run `promptpulse login` and start tracking your Claude Code usage today!