# Pulse for Claude Code

> A local, zero-dependency dashboard for Claude Code that shows live token usage, session recovery, full-text search, and lets you approve tool calls from your phone.

Pulse for Claude Code is an open-source, MIT-licensed local dashboard built by Nikita Doudikov that runs entirely on your machine. It reads Claude Code's session files from `~/.claude` in read-only mode and surfaces live token spend, context fill, session history, and tool-call approvals — all without any network calls, accounts, or telemetry.

## What It Is

Pulse is a monitoring and control layer for Claude Code, Anthropic's agentic coding tool. Claude Code already writes every session to disk as JSONL files; Pulse reads those files and turns them into a live web dashboard served at `127.0.0.1:4317`. The project is written in JavaScript, requires Node 18+, and has zero npm dependencies — no supply chain risk. It can be run instantly via `npx pulse-for-claude-code` or cloned and run directly.

## Core Capabilities

- **Live token dashboard** — token spend by hour, day, and week, broken down by model and project, with configurable budget alerts
- **Context fill meter** — shows how full the active session's context window is in real time
- **Ambient office view** — a full-screen mascot view showing whether Claude is working, resting, or waiting, with a rough ETA
- **Full-text search** — scans every session on disk for a word or phrase and links directly to the transcript
- **Session recovery** — `claude-pulse recover` reconstructs a lost session from disk, compresses a 15 MB log to ~180 KB markdown, and saves it under `~/.claude-pulse/exports/`
- **Auto-snapshots** — while Pulse runs, it continuously snapshots active sessions so a crash never loses context

## Phone Approval Workflow

The standout feature is approving Claude's tool calls from a phone without any Wi-Fi setup or open ports. When Claude wants to run a tool that needs permission, the `PreToolUse` hook fires, Pulse sends a push notification via the free [ntfy](https://ntfy.sh) service, and the notification carries working **Allow / Allow all / Deny** buttons. Tapping one sends the answer back through ntfy to a private reply topic that Pulse listens on. The flow works over cellular from anywhere. Pulse only acts on a reply while it is genuinely waiting for that exact request, so a stale notification cannot approve anything retroactively. If Pulse is not running or the approval timeout (60 seconds by default) expires, it falls back to the normal terminal prompt — Claude is never hung.

## Architecture and Privacy Model

Pulse is local-first by design. Out of the box it binds only to `127.0.0.1`, makes no outbound calls, and reads `~/.claude` read-only. Two optional features extend the perimeter: enabling `ntfyTopic` routes approval prompts through the public ntfy.sh relay (or a self-hosted instance), and enabling `bindLan` exposes the dashboard on the local network so a phone on the same Wi-Fi can open the live `/phone` page. Both are opt-in and off by default. Runtime state, the device token, and configuration live in `~/.claude-pulse/` and are never committed or sent anywhere.

The server uses Server-Sent Events (SSE) to push live updates to the browser. Three small hooks — `Notification`, `Stop`, and `PreToolUse` — are wired into `~/.claude/settings.json` via `claude-pulse install-hooks`, a single idempotent command that backs up existing settings and merges without duplicates.

## Deployment and Lifecycle Management

Pulse can run in the foreground or as a detached background process (`claude-pulse start/stop/status/restart`). On macOS, `claude-pulse install-service` registers it as a login item via launchd so it starts at login and auto-restarts if it crashes. The `export-all` command writes every session into a single gzipped markdown file for backup.

## Current Status

The repository was created in June 2026 and last pushed on June 23, 2026, indicating very recent and active development. The project had accumulated 82 stars and 3 forks within days of creation. It is licensed under MIT and published to npm as `pulse-for-claude-code`.

## Features
- Live token usage dashboard by hour, day, and week
- Context fill meter for active sessions
- Approve Claude tool calls from phone via push notification
- Allow / Allow all / Deny buttons in push notifications
- Full-text search across all sessions on disk
- Session recovery from disk after crash or freeze
- Auto-snapshots of active sessions
- Ambient office mascot view with ETA
- Budget alerts via phone push when thresholds crossed
- Background daemon mode with start/stop/status/restart
- macOS login service via launchd
- Zero npm dependencies
- Local-only by default (127.0.0.1)
- Optional LAN access for phone dashboard view
- Export all sessions to gzipped markdown
- install-hooks command for one-step Claude Code integration

## Integrations
Claude Code, ntfy (push notifications), ntfy.sh relay, macOS launchd

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/nikitadoudikov/claude-pulse
- Documentation: https://github.com/nikitadoudikov/claude-pulse#readme
- Repository: https://github.com/nikitadoudikov/claude-pulse
- EveryDev.ai: https://www.everydev.ai/tools/pulse-for-claude-code