Metadata-Version: 2.5
Name: claude-insights
Version: 1.0.0b3
Summary: Real-time dashboard for Claude Code sessions
Project-URL: Homepage, https://github.com/infowhere-ai/claude-insights
Project-URL: Repository, https://github.com/infowhere-ai/claude-insights
Project-URL: Documentation, https://github.com/infowhere-ai/claude-insights#readme
Project-URL: Changelog, https://github.com/infowhere-ai/claude-insights/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/infowhere-ai/claude-insights/issues
Author-email: Leandro Siciliano <infowhere@infowhere.be>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,claude-code,dashboard,developer-tools,monitor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: anyio>=4.0.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-playwright>=0.5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <img src="docs/logo.png" alt="Claude Insights" width="220"/>

  # Claude Insights

  **Real-time dashboard for Claude Code sessions**

  Monitor what Claude is doing across all your projects — live status, token usage,
  session context, reasoning history, and git changes.

  [![PyPI](https://img.shields.io/pypi/v/claude-insights?label=version)](https://pypi.org/project/claude-insights/)
  [![Python](https://img.shields.io/pypi/pyversions/claude-insights)](https://pypi.org/project/claude-insights/)
  [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  [![CI](https://github.com/infowhere-ai/claude-insights/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/infowhere-ai/claude-insights/actions/workflows/ci.yml)

  *by [Leandro Siciliano](https://github.com/ltsiciliano) · InfoWhere*
</div>

---

![Claude Insights dashboard — live session](docs/demo.gif)
*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)

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

**pipx** (macOS / Linux)

```bash
pipx install claude-insights
```

After installing, see [Quick Start](#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`:

   ```bash
   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**:

   ```bash
   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 |

<div align="center">
  <img src="docs/screenshots/02-reasoning-live.png" width="600" alt="Reasoning panel — live thinking stream"/>
  <p><em>Live reasoning stream — Claude's internal thinking as it arrives</em></p>
</div>

<div align="center">
  <img src="docs/screenshots/03-session-context.png" width="600" alt="Session context — token breakdown"/>
  <p><em>Context window breakdown by category with token costs</em></p>
</div>

<div align="center">
  <img src="docs/screenshots/07-git-panel.png" width="600" alt="Git panel — uncommitted files"/>
  <p><em>Uncommitted files — click any file to open the side-by-side diff viewer</em></p>
</div>

<div align="center">
  <img src="docs/screenshots/14-renewal-window.png" width="600" alt="5-hour token renewal window"/>
  <p><em>5-hour token renewal window tracker</em></p>
</div>

---

## Requirements

- Python 3.10+
- [Claude Code CLI](https://claude.ai/code) **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.

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

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

---

## Uninstall

```bash
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:

```bash
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](CONTRIBUTING.md). This project follows the
[Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).

---

## License

MIT — © 2026 Leandro Siciliano
