ClaudePulse

At a Glance

Every file read, edit, and test that Claude Code performs is automatically recorded and viewable in real time — either from the CLI or a web dashboard.

Claude Code CLI
  │
  ├── Hooks auto-record every tool use  →  ~/.claude-pulse/sessions/*.jsonl
  │
  ├── Query from CLI          "/claude-pulse:stats"
  │
  └── Visualize in dashboard  "/claude-pulse:dashboard"  →  http://localhost:52101
  │
  └── Start/stop dev server   "/claude-pulse:server <command>"  →  http://localhost:<port>

Installation

# 1. Register the marketplace (one-time)
claude plugin marketplace add ccivlcid/ClaudePulse

# 2. Install the plugin
claude plugin install claude-pulse@claude-pulse

# 3. Enable the plugin
claude plugin enable claude-pulse

Data collection begins immediately after installation. No additional configuration required.

Requirements

• Node.js >= 20
• Claude Code CLI

Plugin Management

# Uninstall
claude plugin uninstall claude-pulse

# Uninstall (preserve data — keeps ~/.claude-pulse/)
claude plugin uninstall claude-pulse --keep-data

# Update
claude plugin update claude-pulse

# Disable / re-enable
claude plugin disable claude-pulse
claude plugin enable claude-pulse

Use scopes to control where the plugin is active:

Usage

Slash Commands

1. Session Statistics

> /claude-pulse:stats

── Session Stats ──────────────────
Elapsed: 6m | Tools: 67 | Errors: 1

  Read: 32  Edit: 12  Bash: 8
  Grep: 8   Agent: 4  Write: 3
───────────────────────────────────

Natural language also works:

• "Show me the session stats"
• "How much have I used so far?"
• "Which files were modified the most?"

2. Web Dashboard

> /claude-pulse:dashboard

Opens http://localhost:52101 in your browser automatically.

Dashboard panels:

Click the ↗ button in any panel header to pop it out into a full-screen window.

The dashboard uses SSE (Server-Sent Events) for real-time updates. Claude Code activity is reflected instantly without refreshing.

3. Dev Server Monitoring

Start or stop a dev server using slash commands or natural language.

> /claude-pulse:server start npm run dev
→ "Dev server started (PID: 12345, localhost:3000)"

> /claude-pulse:server stop
→ "Dev server stopped"

Natural language works too:

> Start the dev server
Claude Code → pulse_start_server({ command: "npm run dev" })
→ "Next.js server started (localhost:3000)"

> Stop the dev server
Claude Code → pulse_stop_server()
→ "Server stopped"

While the server is running, logs are automatically captured and displayed in the Server Monitor panel in real time.

Checking errors:

> Any server errors?
→ "1 found — TypeError at src/api/auth.ts:42 (14:35:05)"
→ Claude Code automatically reads the file → suggests a fix

> /claude-pulse:errors
→ Summary of all errors in the session (tool failures + server errors)

Auto-detected error patterns:

• JavaScript exceptions: TypeError, ReferenceError, SyntaxError
• HTTP errors: 4xx/5xx responses
• Build errors: Failed to compile, Module not found
• Network errors: EADDRINUSE, ECONNREFUSED
• Stack traces

How It Works

Data Collection (Automatic)

Claude Pulse uses the built-in Hook system in Claude Code.

User: "Refactor the auth module"

  Claude Code calls the Read tool
  → PreToolUse Hook fires
  → collect-event.mjs runs
  → One line appended to ~/.claude-pulse/sessions/{sessionId}.jsonl

  Claude Code calls the Edit tool
  → Same process repeats

  Tool failure
  → PostToolUseFailure Hook fires
  → Error details recorded

Collected events:

Data Storage

All data is stored in local JSONL files. No external server or database required.

~/.claude-pulse/
├── sessions/
│   ├── {sessionId-1}.jsonl    # Per-session event logs
│   └── {sessionId-2}.jsonl
├── servers/
│   └── {sessionId}.jsonl      # Dev server logs
├── index.json                 # Session index (for fast lookups)
└── config.json                # Configuration

Example JSONL line:

{"id":"a1b2","ts":"2026-03-30T14:32:01Z","type":"tool-start","sessionId":"8ebad784-...","toolName":"Read","toolUseId":"toolu_01Gt...","filePath":"src/auth.ts","projectDir":"/home/user/my-app"}

Data Retention

• Event logs: 30-day retention (default)
• Server logs: 7-day retention
• Max storage: 500 MB (oldest sessions deleted when exceeded)
• Cleanup runs only at session end (zero overhead during work)

MCP Tools

These tools can be invoked via natural language inside Claude Code.

Configuration

Edit ~/.claude-pulse/config.json:

{
  "retention": {
    "eventsDays": 30,
    "serverLogsDays": 7,
    "maxTotalSizeMb": 500
  },
  "ports": {
    "dashboard": 52101
  }
}

You can also override the port via environment variable:

PULSE_DASHBOARD_PORT=52102

About Token Estimation

Token estimates are based on tool input text length (~4 chars/token) and per-tool average output token tables.

Since hooks cannot observe system prompts, conversation history, or reasoning tokens, only tool-related tokens can be estimated. The estimates are useful for relative comparisons across sessions and projects; absolute numbers are approximate.

Tech Stack

No native C++ module dependencies — works on Windows, macOS, and Linux.

Limitations

• Dev servers started directly from a terminal (outside Claude Code) cannot have their logs captured — use pulse_start_server instead
• Token estimates are tool-call-based approximations (system prompt and conversation history excluded)
• Hooks only report tool start/end — intermediate progress is not observable

License

MIT