🌐 Pulse: The Ultimate Companion Dashboard for Claude Code

Pulse is a local, zero-dependency monitoring hub designed specifically for Claude Code. It provides a visual layer over your terminal interactions, allowing you to track spending, monitor context, and ~~stress over lost sessions~~ recover data instantly. Most importantly, it enables you to approve tool calls directly from your smartphone.

🚀 Core Capabilities

Pulse transforms the raw data in your ~/.claude directory (read-only) into a dynamic, live interface.

📊 Analytics & Monitoring

Financial Tracking: Monitor token consumption and API-equivalent costs.
- Granularity: View data by hour, day, week, model, or specific project.
- Budgeting: Set custom limits and receive phone alerts when you exceed them.
Context Awareness: Real-time visualization of your active session's context fill.
Ambient Mode: A dedicated full-screen view featuring a small mascot that indicates if Claude is working, resting, or waiting for your input, complete with a rough ETA.

🔍 Search & Recovery

Global Search: Perform full-text searches across every session stored on your disk.
One-Click Access: Jump from a search result directly to the full transcript.

📱 Remote Control

Mobile Approvals: Receive notifications with Allow, Allow all, or Deny buttons.
Zero Config: No need for IP addresses, open ports, or Wi-Fi setup for basic notifications.

🛠️ Quick Start Guide

Prerequisites: Node 18+

Installation Checklist

Run without installing:
```
npx pulse-for-claude-code
```

Or, install via Git:

git clone https://github.com/nikitadoudikov/claude-pulse.git
cd claude-pulse
node bin/cli.js

Access the UI: Open http://127.0.0.1:4317 in your browser.

Enabling Remote Approvals

To activate phone/desktop notifications and tool call approvals, you must link the hooks:

claude-pulse install-hooks

Note: This modifies ~/.claude/settings.json. It is safe to run multiple times. Restart Claude Code after running.

⚙️ Command Reference

Command	Description
`claude-pulse --port [port]`	Specify a custom port (default: `4317`)
`claude-pulse --no-open`	Start the server without launching the browser
`claude-pulse start`	Run as a detached background process
`claude-pulse status`	Check if the dashboard is currently active
`claude-pulse stop`	Terminate the background process
`claude-pulse restart`	Perform a full stop and start cycle

[!TIP] macOS Users: You can integrate Pulse into the system to ensure it launches at login and auto-respawns upon failure: claude-pulse install-service (To remove: claude-pulse uninstall-service)

💾 Session Recovery & Backups

If your terminal crashes or your laptop freezes, your progress isn't gone. Claude Code logs everything to disk in .jsonl format. Pulse can rescue this data.

Recovering Data

Use the recover command to generate a readable Markdown transcript:

claude-pulse recover $\rightarrow$ Most recent session.
claude-pulse recover 2 $\rightarrow$ Second most recent.
claude-pulse recover [id] $\rightarrow$ A specific session ID.

Efficiency Gain: Pulse drastically compresses the logs for readability. For example: $\text{Log Size: } 15\text{ MB} \xrightarrow{\text{Pulse Recovery}} \text{Markdown Size: } \approx 180\text{ KB}$

Automatic Snapshots & Exports

Auto-Snapshots: Pulse continuously saves active sessions to ~/.claude-pulse/exports/snapshots/.
Disable Snapshots: Set snapshotMinutes: 0 in ~/.claude-pulse.json.
Bulk Export: Use claude-pulse export-all to create a single gzipped markdown file of your entire history.

📱 Mobile Integration

Pulse offers two levels of mobile interaction:

The Light Way (ntfy): Uses notifications with actionable buttons (Allow/Deny). Works over cellular data with no network configuration.
The Rich Way (LAN): If you are on the same Wi-Fi and have bindLan: true enabled, visit http://[your-machine-ip]:4317/phone.
- Features: Live activity feed and a Pause/Resume button to halt Claude's tool execution.

🏗️ How It Works

Pulse acts as a read-only observer of Claude's logs while providing a feedback loop via hooks.

Technical Specifications:

Storage: Reads from ~/.claude/projects/.
Privacy: Zero telemetry.
Network: Serves locally on 127.0.0.1.

Example of the Ambient Office view for monitoring Claude's state.