165 lines
5.2 KiB
Markdown
165 lines
5.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
**Important:** When updating this file, always update `README.md` as well. The README is the main user-facing documentation for the project.
|
|
|
|
## Project Overview
|
|
|
|
Kao 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** (`kao.py`) — Unified entry point managing all processes
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # or .\venv\Scripts\activate on Windows
|
|
pip install -r requirements.txt
|
|
python kao.py
|
|
```
|
|
|
|
UI available at http://localhost:5100
|
|
|
|
## Configuration
|
|
|
|
Edit `config.json` to configure detectors:
|
|
|
|
```json
|
|
{
|
|
"aggregator_url": "http://localhost:5100",
|
|
"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) |
|
|
| Docker | `detectors/docker.py` | `CONTAINERS` (optional, monitors all if empty) |
|
|
|
|
All detectors support: `AGGREGATOR_URL`, `CHECK_INTERVAL`, `THRESHOLD_WARNING`, `THRESHOLD_CRITICAL`
|
|
|
|
## API Endpoints
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/event` | POST | Register event: `{"id": "name", "priority": 1-4, "message": "optional", "ttl": seconds}` |
|
|
| `/clear` | POST | Clear event: `{"id": "name"}` |
|
|
| `/notify` | POST | Simple notification: `{"message": "text", "duration": 5}` |
|
|
| `/sleep` | POST | Enter sleep mode |
|
|
| `/wake` | POST | Exit sleep mode |
|
|
| `/status` | GET | Current state JSON |
|
|
| `/events` | GET | List active events |
|
|
|
|
## Priority System
|
|
|
|
Lower number = higher priority. Events with a `ttl` auto-expire (heartbeat pattern).
|
|
|
|
| Priority | State | Emote | Color | Animation |
|
|
|----------|-------|-------|-------|-----------|
|
|
| 1 | Critical | `( x_x)` | Red | shaking |
|
|
| 2 | Warning | `( o_o)` | Yellow | breathing |
|
|
| 3 | Notify | `( 'o')` | Blue | popping |
|
|
| 4 | Optimal | varies | Green | varies |
|
|
|
|
## Personality System
|
|
|
|
The optimal state cycles through emotes with paired animations every 5 minutes:
|
|
|
|
| Emote | Animation | Vibe |
|
|
|-------|-----------|------|
|
|
| `( ^_^)` | breathing | calm |
|
|
| `( ˙▿˙)` | floating | content |
|
|
| `(◕‿◕)` | bouncing | cheerful |
|
|
| `( ・ω・)` | swaying | curious |
|
|
| `( ˘▽˘)` | breathing | cozy |
|
|
|
|
Additional states:
|
|
- **Idle expressions** (15% chance): `( -_^)`, `( ^_~)`, `( ᵕ.ᵕ)` with blink animation
|
|
- **Recovery celebration**: `\(^o^)/` with bounce for 5 seconds after issues resolve
|
|
- **Connection lost**: `( ?.?)` gray, searching animation
|
|
- **Sleep mode**: `( -_-)zzZ` dim, very slow breathing
|
|
|
|
## Home Assistant Integration
|
|
|
|
Add REST commands to `configuration.yaml`:
|
|
|
|
```yaml
|
|
rest_command:
|
|
kao_notify:
|
|
url: "http://kao-host:5100/notify"
|
|
method: POST
|
|
content_type: "application/json"
|
|
payload: '{"message": "{{ message }}", "duration": {{ duration | default(5) }}}'
|
|
|
|
kao_sleep:
|
|
url: "http://kao-host:5100/sleep"
|
|
method: POST
|
|
|
|
kao_wake:
|
|
url: "http://kao-host:5100/wake"
|
|
method: POST
|
|
```
|
|
|
|
Use in automations:
|
|
|
|
```yaml
|
|
# Doorbell notification
|
|
- service: rest_command.kao_notify
|
|
data:
|
|
message: "Someone at the door"
|
|
duration: 10
|
|
|
|
# Bedtime routine
|
|
- service: rest_command.kao_sleep
|
|
|
|
# Morning routine
|
|
- service: rest_command.kao_wake
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
├── kao.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
|
|
│ └── docker.py
|
|
├── requirements.txt
|
|
└── SPEC.md # Original project specification
|
|
```
|