---

Live session — WORKING state, all panels updating in real time

Claude Insights is a lightweight web dashboard that connects to Claude Code via hooks. It shows live status, token usage, session context, reasoning blocks, and uncommitted git changes — across all your projects simultaneously. Everything runs locally. No data leaves your machine.

---

Installation

Homebrew (macOS)

brew tap infowhere-ai/claude-insights
brew install claude-insights

pipx (macOS / Linux)

pipx install claude-insights

After installing, see Quick Start below to activate the hooks.

---

Quick Start

1. Activate hooks — sets up the hook script at ~/.claude/hooks/monitor-hook.sh and registers it for 5 Claude Code events in ~/.claude/settings.json:

   claude-insights install
   

   Existing hooks are never removed or modified.

2. Restart Claude Code — required for the hooks to take effect in open sessions.

3. Start the dashboard:

   claude-insights start
   

   Opens at http://localhost:4000

---

How It Works

Claude Code fires hooks at key moments — before and after each tool call, on notifications, on stop. Each hook writes a small JSON file to .claude/status.json inside the current project. Claude Insights watches those files and streams updates to the browser via Server-Sent Events.

Claude Code  →  hook fires  →  .claude/status.json  →  Claude Insights (SSE)  →  browser

---

Features

Area	What you see
Live status	Current state: working, waiting, compacting, idle — with the exact tool name
Reasoning	Claude's internal thinking live as it arrives; full history browsable
Session context	Context window breakdown: fixed rules, conversation, tool results — with token costs
Token usage	Input, output, cache reads — per session and 5-hour renewal window
Commands	Every tool call with path, duration, and success/failure
To commit	Uncommitted git changes; click any file for a side-by-side diff viewer
Multi-project	Monitors all projects under a root folder — auto-discovered
Session history	Browse past sessions; replay events and reasoning blocks

---

Requirements

• Python 3.10+
• Claude Code CLI 1.0+ (claude) in PATH
• macOS or Linux
• Git

Claude Code version: claude-insights requires Claude Code 1.0 or later (hooks support). The PreCompact hook (compacting state indicator) requires 1.5+ and is optional — the dashboard works without it. Update with npm install -g @anthropic-ai/claude-code@latest.

---

Configuration

Variable	Default	Description
PORT	4000 (CLI) / 19001 (run.sh, docker)	HTTP port for the dashboard
HOST	127.0.0.1	Bind address
PROJECTS_ROOT	required for pip/pipx/binary installs; auto-detected only from a source checkout	Root folder containing your project directories
POLL_INTERVAL	0.5	State-file polling interval (seconds)
DISCOVERY_INTERVAL	60.0	Project discovery interval (seconds)
JSONL_ACTIVE_SECONDS	30.0	Activity window for session JSONL files
CLAUDE_HOME	~/.claude	Claude Code directory
CLAUDE_PROJECTS_DIR	~/.claude/projects	Where session JSONL files live
CLAUDE_INSIGHTS_DB	~/.claude/claude-insights.db	SQLite database path
CORS_ORIGIN_REGEX	localhost/127.0.0.1	Allowed CORS origins regex

See .env.example for the full list.

PORT=8080 PROJECTS_ROOT=~/code claude-insights start

Any directory under PROJECTS_ROOT that contains a .claude/ folder is monitored automatically.

---

Uninstall

claude-insights uninstall

Removes the hook script and deregisters hooks from ~/.claude/settings.json. Your other Claude Code hooks and settings are preserved.

---

Development

For running from source:

git clone https://github.com/infowhere-ai/claude-insights.git
cd claude-insights
./install.sh        # sets up hooks
./run.sh start      # starts the server (source install — default port: 19001)

Stack: Python 3.10+ · FastAPI · SSE · Vanilla JS (no build step)

Contributions are welcome — see CONTRIBUTING.md. This project follows the Contributor Covenant Code of Conduct.

---

License

MIT — © 2026 Leandro Siciliano