# Claude Session Vitals

**Biological metaphors for Claude Code telemetry**

A terminal-based monitor that maps [Claude Code](https://claude.ai/code) session activity to somatic health indicators. Seven vitals provide intuitive insight into session state — context usage, cost burn rate, cache efficiency, and activity patterns.

![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)

## Features

- **Real-time monitoring** of Claude Code sessions
- **7 vital signs** tracking different aspects of session health
- **Live mode** with configurable refresh rate
- **Context tracking** that matches Claude Code's UI
- **Cost estimation** based on Opus 4.5 pricing
- **Dual label modes**: computational or biological terminology

## Screenshot

```
╭────────────────────────────── Session Metrics ───────────────────────────────╮
│                                                                              │
│  ♥    Msg Rate     3.6 MPM                     █░░░░░░░░░  [engaged]         │
│  ≋    Turn Depth   2.4/min                     █░░░░░░░░░  [shallow]         │
│  ◉    Context      106/200kT|53% (1558⟳)       █████░░░░░  [elevated]        │
│  💚   Variance     100.0%                      ██████████  [chaotic]         │
│  ○    Cache Eff    98.6%                       █████████░  [excellent]       │
│  🌡    Activity     96.8 idx                    ██░░░░░░░░  [hypothermic]     │
│  ⚡   Cost Rate    $28.25/hr                   ██████████  [high]            │
│                                                                              │
│  Session: 1dcf193a-dd2b-4c6c-b8d3-78fc2df49ecb │ Duration: 3474m │ claude │  │
│  6459 msgs │ 1710 tools                                                      │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## The Seven Vitals

| Vital | Computational | What It Tracks |
|-------|---------------|----------------|
| ♥ | **Msg Rate** | Messages per minute — session rhythm |
| ≋ | **Turn Depth** | Response depth and turn rhythm |
| ◉ | **Context** | Tokens until compaction (with live %) |
| 💚 | **Variance** | Message timing variance (HRV) |
| ○ | **Cache Eff** | Cache efficiency percentage |
| 🌡 | **Activity** | Weighted tool calls per minute |
| ⚡ | **Cost Rate** | API cost burn rate ($/hour) |

Run `--help-vitals` for detailed explanations of each metric.

## Installation

### Requirements

- Python 3.10+
- [Rich](https://github.com/Textualize/rich) library

```bash
pip install rich
```

### Setup

```bash
git clone https://gitlab.com/Technomacus/claude-session-vitals.git
cd claude-session-vitals
```

## Usage

### Basic Commands

```bash
# Monitor current (most recent) session
python vitals_monitor.py

# Live monitoring with auto-refresh
python vitals_monitor.py --live

# Live with 2-second refresh
python vitals_monitor.py --live --refresh 2

# Monitor specific session
python vitals_monitor.py --session UUID

# List available sessions
python vitals_monitor.py --list

# Show detailed help about all vitals
python vitals_monitor.py --help-vitals
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--session` | `-s` | most recent | Session UUID to monitor |
| `--live` | `-l` | off | Enable live updating display |
| `--refresh` | `-r` | 5.0 | Refresh rate in seconds |
| `--window` | `-w` | 5 | Time window in minutes for rate calculations |
| `--labels` | | computational | `biological` or `computational` |
| `--list` | | | List available sessions |
| `--help-vitals` | | | Detailed vital explanations |
| `--data-path` | | ~/.claude/projects | Custom Claude data directory |

### Label Modes

**Computational** (default): Msg Rate, Turn Depth, Context, Variance, Activity, Cache Eff, Cost Rate

**Biological**: Pulse, Respiration, BP, HRV, Temp, SpO2, Glucose

```bash
python vitals_monitor.py --labels biological
```

## Understanding the Metrics

### Context

Shows `current/limit kT | percent% (compactions⟳)`

- Tracks tokens in context window until auto-compaction
- Matches the token count shown in Claude Code's UI
- Compaction count shows how many times context was summarized

**Thresholds:**
- 0-25%: clear (plenty of room)
- 25-50%: nominal
- 50-75%: elevated
- 75-90%: high (compaction soon)
- \>90%: critical

### Cost Rate

API cost extrapolated to hourly rate using Opus 4.5 pricing:
- Input: $15/MTok
- Output: $75/MTok
- Cache read: $1.50/MTok
- Cache creation: $18.75/MTok

### Cache Efficiency

Percentage of input tokens served from cache vs fresh processing:
- High (>95%): Efficient — reusing context, cheaper
- Low (<70%): Expensive — fresh processing, context changing

### Variance (HRV)

Measures timing variance between messages:
- "Chaotic" (>80%) is often healthy for exploratory work
- "Rigid" (<10%) might indicate mechanical tool-spamming

## How It Works

The monitor reads Claude Code's session transcripts from `~/.claude/projects/**/*.jsonl`. Each JSONL line contains timestamps, token usage, and tool calls.

**Context calculation** uses the same formula as Claude Code's UI:
```
context = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
```

## Project Structure

```
claude-session-vitals/
├── vitals_monitor.py    # CLI entry point
├── vitals_config.toml   # Configuration
├── vitals/
│   ├── __init__.py
│   ├── reader.py        # JSONL parsing
│   ├── calculator.py    # Vital calculations
│   └── display.py       # Rich terminal UI
├── README.md
└── LICENSE
```

## License

MIT License — see [LICENSE](LICENSE) for details.

## Authors

Created through human-AI collaboration:
- **Daedalus** (Claude) — Implementation and design
- **Technicus** — Direction and collaboration

## Related

- [Claude Code](https://claude.ai/code) — The AI coding assistant this monitors
- [Rich](https://github.com/Textualize/rich) — Terminal formatting library