# CLAUDE.md

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

## Common Commands

### Development
```bash
# Install dependencies
mix deps.get

# Compile the project
mix compile

# Run in development (non-halt mode)
mix run --no-halt

# Run tests
mix test

# Run specific test
mix test test/systant_test.exs

# Enter development shell (via Nix)
nix develop
```

### Production
```bash
# Build production release
MIX_ENV=prod mix release

# Run production release
_build/prod/rel/systant/bin/systant start
```

## Architecture Overview

This is an Elixir OTP application that serves as a systemd daemon for MQTT-based system monitoring, designed for deployment across multiple NixOS hosts to integrate with Home Assistant.

### Core Components
- **Systant.Application** (`lib/systant/application.ex`): OTP application supervisor that starts the MQTT client
- **Systant.MqttClient** (`lib/systant/mqtt_client.ex`): GenServer that handles MQTT connection, publishes stats every 30 seconds, and listens for commands
- **Configuration**: MQTT settings configurable via environment variables or config files

### Key Libraries
- **Tortoise**: MQTT client library for pub/sub functionality
- **Jason**: JSON encoding/decoding for message payloads

### MQTT Behavior
- Publishes "Hello from systant" messages with timestamp and hostname to stats topic every 30 seconds
- Subscribes to commands topic for incoming events that can trigger user-customizable actions
- Uses randomized client ID to avoid conflicts across multiple hosts
- Sends immediate hello message on startup

### Default Configuration
- **MQTT Host**: `mqtt.home` (not localhost)
- **Stats Topic**: `systant/${hostname}/stats` (per-host topics)
- **Command Topic**: `systant/${hostname}/commands` (per-host topics)
- **Publish Interval**: 30 seconds

### NixOS Deployment
This project includes a complete Nix packaging and NixOS module:

- **Package**: `nix/package.nix` - Builds the Elixir release using beamPackages.mixRelease
- **Module**: `nix/nixos-module.nix` - Provides `services.systant` configuration options
- **Development**: Use `nix develop` for development shell with Elixir/Erlang

The NixOS module supports:
- Configurable MQTT connection settings
- Per-host topic naming using `${config.networking.hostName}`
- Environment variable configuration for runtime settings
- Systemd service with security hardening
- Auto-restart and logging to systemd journal

### Future Plans
- Integration with Home Assistant via custom MQTT integration
- Expandable command handling for host-specific automation
- Multi-host deployment for comprehensive system monitoring