# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Sentry-Emote is a minimalist system status monitor designed for an old Pixel phone used as an ambient display. It uses ASCII "emotes" to represent system health instead of complex graphs.

## Architecture

**Publisher/Subscriber model:**

```
┌─────────────┐     POST /event      ┌─────────────┐     GET /status     ┌─────────────┐
│  Detectors  │ ──────────────────▶  │  Aggregator │ ◀────────────────── │   Emote-UI  │
│  (sensors)  │                      │   (broker)  │                     │  (display)  │
└─────────────┘                      └─────────────┘                     └─────────────┘
```

- **Aggregator** (`aggregator.py`) — Flask service managing the event queue and priority logic
- **Detectors** (`detectors/*.py`) — Independent scripts monitoring system metrics
- **Emote-UI** (`index.html`) — OLED-optimized web frontend
- **Sentry** (`sentry.py`) — Unified entry point managing all processes

## Quick Start

```bash
# Setup
python -m venv venv
source venv/bin/activate  # or .\venv\Scripts\activate on Windows
pip install -r requirements.txt

# Run everything
python sentry.py
```

UI available at http://localhost:5000

## Configuration

Edit `config.json` to configure the aggregator URL, enable/disable detectors, and set thresholds.

```json
{
  "aggregator_url": "http://localhost:5000",
  "aggregator": { "script": "aggregator.py" },
  "detectors": [
    {
      "name": "cpu",
      "enabled": true,
      "script": "detectors/cpu.py",
      "env": {
        "CHECK_INTERVAL": "30",
        "THRESHOLD_WARNING": "85",
        "THRESHOLD_CRITICAL": "95"
      }
    }
  ]
}
```

## Detectors

| Detector | Script | Required Env Vars |
|----------|--------|-------------------|
| Disk Space | `detectors/disk_space.py` | — |
| CPU | `detectors/cpu.py` | — |
| Memory | `detectors/memory.py` | — |
| Service | `detectors/service.py` | `SERVICES` (comma-separated process names) |
| Network | `detectors/network.py` | `HOSTS` (comma-separated hostnames/IPs) |

All detectors support: `AGGREGATOR_URL`, `CHECK_INTERVAL`, `THRESHOLD_WARNING`, `THRESHOLD_CRITICAL`

## API Endpoints

- `POST /event` — Register event: `{"id": "name", "priority": 1-4, "message": "optional", "ttl": optional_seconds}`
- `POST /clear` — Clear event: `{"id": "name"}`
- `GET /status` — Current state JSON
- `GET /events` — List active events

## Priority System

Lower number = higher priority. Events with a `ttl` auto-expire (heartbeat pattern).

| Priority | State    | Emote    | Color  | Behavior |
|----------|----------|----------|--------|----------|
| 1 | Critical | `( x_x)` | Red | Shaking animation |
| 2 | Warning | `( o_o)` | Yellow | Breathing animation |
| 3 | Notify | `( 'o')` | Blue | Popping animation, 10s default TTL |
| 4 | Optimal | `( ^_^)` | Green | Default when no events |

## Testing Events

```bash
# Warning with 30s TTL
curl -X POST -H "Content-Type: application/json" \
  -d '{"id":"test","priority":2,"message":"Test warning","ttl":30}' \
  http://localhost:5000/event

# Clear manually
curl -X POST -H "Content-Type: application/json" \
  -d '{"id":"test"}' \
  http://localhost:5000/clear
```

## File Structure

```
├── sentry.py           # Unified entry point
├── aggregator.py       # Event broker/API server
├── index.html          # OLED-optimized frontend
├── config.json         # Runtime configuration
├── detectors/
│   ├── disk_space.py
│   ├── cpu.py
│   ├── memory.py
│   ├── service.py
│   └── network.py
├── requirements.txt
└── SPEC.md             # Original project specification
```