Files

Spencer Grimes 11896919e4 Initial commit: Sentry-Emote system monitor

- Aggregator: Flask-based event broker with priority queue
- Frontend: OLED-optimized UI with animations
- Detectors: disk, cpu, memory, service, network
- Unified entry point (sentry.py) with process management
- Heartbeat TTL system for auto-clearing stale events

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-02 21:04:02 -06:00

4.0 KiB

Raw Blame History

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

# 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.

{
  "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

# 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

4.0 KiB Raw Blame History