systant/CLAUDE.md

CLAUDE.md

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

Common Commands

Development

# 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

# 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