Eneru
AGENTS.md152 starsChanged 31 days agoMITView on GitHub
Intelligent UPS monitoring daemon for NUT (Network UPS Tools). Orchestrates graceful shutdown of VMs, containers, remote servers, and local systems during power events. These apply to every task in this repo, ahead of any section-specific guidance below. CRITICAL: NEVER run pip, pip3, python -m pip, python, pytest, or any other dev/Python tooling directly against the system Python. ALL Python work — install, uninstall, run, test, version-check — MUST happen inside a uv virtualenv. No exceptions. CRITICAL: Unless a human explicitly…
- Installs packages
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- dashboard-previewSkill
- release-reviewSkill
The file
We split this AGENTS.md into the rules it gives an agent
11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
if you're Claude Code, absolutely Be brief.
- Distinctive: line 11
if you're Codex, don't be as brief as your defaults forces you.
- Distinctive: line 83
Commit messages: conventional commits (feat:, fix:, docs:, refactor:, test:, chore:)
- Very specific: line 88
Always test with --dry-run before real shutdown logic changes
- Very specific: line 90
Adding or removing tests?: Update docs/testing.md (per-file breakdown, E2E test case table).
- Very specific: line 95
Adding a new file under
src/eneru/?: Add a matching contents: entry in nfpm.yaml. - Very specific: line 204
Run trail map first — a token-budgeted orientation (dir clusters, hubs, hotspots), no LLM, no key.
- Very specific: line 207
Run trail ask "<your question>" --source → ranked nodes with the relevant code spans inlined (each hit's ≤8-line crux by default.
- Very specific: line 219
Add --direction out for what it calls, or --depth N to walk transitively for the full blast radius.
- Distinctive: line 227
If a returned span is truncated ("+N more lines"), open the file at that exact range before finalizing.
- Very specific: line 232
After big code changes, refresh the graph with trail build (deterministic, no API key, $0).
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Eneru
Intelligent UPS monitoring daemon for NUT (Network UPS Tools). Orchestrates graceful shutdown of VMs, containers, remote servers, and local systems during power events.
Primary Directives
These apply to every task in this repo, ahead of any section-specific guidance below.
- Be brief.
- if you're Claude Code, absolutely Be brief.
- if you're Codex, don't be as brief as your defaults forces you; make sure code is commented, commit messages are clear, and enough context is included.
- Decide locally. Flag assumptions only when the choice is non-obvious or hard to reverse.
- No speculative complexity. Build for the problem in front of you, not the one you imagine next.
- Define success criteria. Loop until verified.
- Touch only what you must. Clean up only your own mess.
- Explain like I'm five (ELI5). When you justify a non-obvious fix, debug a tricky bug, or write an AGENTS.md / changelog / commit-body section, lead with a concrete metaphor or analogy (kitchen, plumbing, traffic, whatever fits) before the jargon. The audience for these notes is future-you at 3 a.m. during an incident — not a reviewer looking for sophistication. Jargon comes second, after the picture is in their head.
Development Setup
CRITICAL: NEVER run pip, pip3, python -m pip, python, pytest, or any other dev/Python tooling directly against the system Python. ALL Python work — install, uninstall, run, test, version-check — MUST happen inside a uv virtualenv. No exceptions.
CRITICAL: Unless a human explicitly authorizes it for the current task, NEVER run the Docker-backed E2E suite locally. This includes Docker/Compose setup, execution, and teardown under tests/e2e/. Use GitHub Actions for E2E execution. Local unit tests, static checks, shell syntax checks, and workflow parsing remain allowed. Authorization from an earlier task does not carry forward.
This rule applies to every operation, including uninstalls: a system-wide pip uninstall eneru rips out files claimed by both pip and the deb/rpm package (e.g. /usr/local/bin/eneru), breaking the package install. If a system has stale pip-installed Eneru packages, the only correct cleanup is to reinstall the deb/rpm to restore its files and leave the pip remnants alone, or hand-delete only the pip-owned site-packages directory. Never invoke pip against system Python.
To verify an installed deb/rpm package, invoke the package's own entry point (/usr/local/bin/eneru version, python3 /opt/ups-monitor/eneru.py version) — these read from /opt/ups-monitor/, no venv required.
# Create and activate virtualenv (disposable tmp folder)
uv venv /tmp/eneru-venv
source /tmp/eneru-venv/bin/activate
# Install package with all dev dependencies (same extras CI installs, plus docs)
uv pip install -e ".[dev,notifications,auth,mqtt,docs]"Commands
# Testing (always inside virtualenv)
pytest # Run all tests
pytest -m unit # Unit tests only (integration coverage is the E2E suite, tests/e2e/)
pytest --cov=src/eneru # With coverage
# Development
python -m eneru validate --config examples/config-reference.yaml
python -m eneru run --dry-run --config examples/config-reference.yaml
# Documentation
mkdocs serve # Local docs previewProject Structure
src/eneru/ # Main package — see src/eneru/AGENTS.md for the per-module
# map, mixin pattern, loopback ordering, stats schema, scheduler
shutdown/ # Per-phase shutdown mixins (vms, containers, filesystems, remote)
health/ # Health-monitoring mixins (voltage, battery)
web/ # Browser dashboard static assets (app.js, style.css, index.html)
tests/ # pytest unit/integration tests (test_*.py; shared fixtures in conftest.py)
tests/e2e/ # End-to-end suite: docker-compose env, NUT simulator, SSH targets
docs/ # MkDocs documentation (ReadTheDocs); changelog.md is the single changelog
examples/ # Example configs; config-reference.yaml covers every feature flag
deploy/kubernetes/ # Kubernetes manifests
packaging/ # Package entry-point wrapper, systemd unit, lifecycle scripts
tools/ # dashboard-preview.py — visual verification of web/ changes
# (see the dashboard-preview skill)
.claude/skills/ # Repo skills: dashboard-preview, release-review
.github/workflows/ # validate, integration, e2e, codeql, release, pypi
nfpm.yaml # .deb/.rpm package config (enumerates every module file)
pyproject.toml # PEP 517/518 packagingCode Style
- Python 3.9+ with type hints; PEP 8; docstrings for public functions/classes
- Tests in
tests/followingtest_*.py - Emojis in logs/notifications carry semantic meaning (⚡ power events, 🔋 battery, 🌐 remotes, 🛰️ loopback delegation, …). They're scanner hints during incident review, not decoration. The full legend lives in
CONTRIBUTING.md("Log message emoji conventions") — match existing usage when adding log lines.
Conventions
- Commit messages: conventional commits (feat:, fix:, docs:, refactor:, test:, chore:)
- Codex commits must include this trailer in the commit message body:
Co-authored-by: Codex <noreply@openai.com> - Claude commits must include this trailer in the commit message body:
Co-authored-by: Claude <noreply@anthropic.com>(model-agnostic — don't pin a specific version; new model releases shouldn't require a doc bump) - Notifications via Apprise (100+ services supported)
- Config validation before any changes to config handling
- Always test with
--dry-runbefore real shutdown logic changes - New config feature flags go in
examples/config-reference.yamlAND the relevant table indocs/configuration.md(key, default, one-line description). The two surfaces drift apart fast otherwise — both must agree. - Adding or removing tests? Update
docs/testing.md(per-file breakdown, E2E test case table). The pyramid summary intentionally says "thousands of tests" — no specific count to keep in sync. - New features require both synthetic AND end-to-end tests: unit/integration tests in
tests/covering the logic and a step in.github/workflows/e2e.ymlexercising the feature against the Docker Compose environment intests/e2e/. Synthetic tests catch logic bugs; E2E proves it works against real NUT/SSH/Docker. This applies to drain-path behavior changes too, not just features. PRs missing E2E coverage get sent back. - Coverage bar: ≥95% per file (line+branch) for every file under
src/eneru/— including defensive branches (error logging, swallowed exceptions, edge cases). Verify withpytest -m unit --cov=src/eneru --cov-report=term-missingbefore pushing; bring regressions back up in the same PR. - OCI image changes: update
Dockerfile,.dockerignore,docs/containers-kubernetes.md, the Kubernetes samples underdeploy/kubernetes/, and the OCI smoke checks inintegration.yml/release.yml. One Python 3.12 image, non-root by default, published to GHCR, must work under Docker and Podman. Remote-only configs run without root; local-host orchestration requires root or an enabled host-loopback delegate (is_host_loopback: true). - SELinux bind-mount rule, no exceptions in docs/examples/CI:
:Z/:zonly on eneru-owned sources (/srv/eneru/...); plain:roon shared host files (/etc/machine-id,/etc/localtime, anything other services read).:Zpersistently relabels the host file and can leave the host with a dead bus + no network after reboot. Full rationale:docs/containers-kubernetes.md("Podman and SELinux"). - Adding a new file under
src/eneru/? Add a matchingcontents:entry innfpm.yaml. The deb/rpm builds enumerate every module file explicitly — they do NOT glob; a missing entry passes pip CI silently and fails only at deb/rpm install time (ModuleNotFoundError). - Adding state to the SQLite stats DB? Bump
SCHEMA_VERSIONinsrc/eneru/stats.pyand add an idempotent, append-only migration — full pattern and when-to-add-a-column guidance insrc/eneru/AGENTS.md("Stats schema evolution"). New event types do NOT need a schema bump — only new columns or tables do.
Working efficiently
This repo deliberately keeps individual source files on the smaller side (the v5.1 mixin decomposition). To stay within the context window during longer sessions:
- Use Graft directly, or delegate its query to an Explore subagent, for "where is X" / "how does Y work" questions. Open only the exact source spans still needed. Direct
Readis right when you already know the file and need its current contents. - Read
src/eneru/AGENTS.mdfor the per-module map before reading implementations; the map is far cheaper than themonitor.pyit summarizes. - Don't add startup context-injecting hooks. They pre-load files into every session — exactly the wrong direction. On-demand tool configuration such as the Graft MCP is fine; keep local
.mcp.jsonfiles untracked. - On long multi-finding tasks, track every item with
/goals(or the task tools) and re-check the list before declaring done — "61 of 62 done" reads as done in a long session unless the tracker says otherwise.
Git Workflow
main is protected. All changes go through feature branches and pull requests.
Branch protection on main: required checks = validate (reduced PR matrix 3.9, 3.12, 3.15; all three required) + test-oci-image (aggregates parallel native AMD64 and ARM64 builds, config/native-dependency/metadata checks, and the Podman smoke) + 8 parallel E2E matrix jobs (E2E CLI, E2E UPS Single Core, E2E UPS Single Auth, E2E UPS Multi, E2E Redundancy Quorum, E2E Redundancy Regression, E2E Stats, E2E Loopback). Strict mode (branch up-to-date with main), enforce admins, no force pushes, 0 required reviewers (CI-gated), branches auto-delete after merge.
Workflow:
1. Pull latest main: git checkout main && git pull --ff-only origin main
(branching from stale main forces a rebase later)
2. Create feature branch from the up-to-date main
3. Develop, commit, push the first logical chunk
4. Open the PR as soon as you have something pushable — CI does NOT fire on
feature-branch pushes until a PR exists. Mark draft if WIP
5. Iterate in logical chunks (one push per slice) — NOT one commit per push
(CI flood, AI-reviewer quota burn) and NOT "20 commits → finally open PR"
6. All required checks green before merge
7. Merge via GitHub (branch auto-deletes)Commit boundaries: Think of each commit as one labelled box: it should contain one complete, coherent behavior and everything needed to prove and explain it. Keep an independent feature, fix, or workstream in its own commit, including its related tests, docs, config, and CI changes. Do not collect all production code in one commit and all tests or docs in later commits. For example, self-test behavior, weekly reports, and an APC compatibility fix are three separate commits even when they ship in the same release PR. Prepare these commits locally, then batch pushes when practical so this rule does not create a CI run for every commit.
Releasing a new version:
1. For X.Y.0 / X.0.0 ONLY — run the release-review skill first (see below)
2. Merge all feature work into main via PRs
3. Update docs/changelog.md and version.py on main
4. Tag the latest commit on main: git tag vX.Y.Z && git push origin vX.Y.Z
5. Create the GitHub Release from the tag (triggers release.yml + pypi.yml)
— point releases use --latest=false; see docs/maintenance.md
("Release mechanics") for the Latest-pinning and blockquote patternTags are the immutable release snapshots; no release branches. Point releases (X.Y.Z) are for bug fixes only — feature work waits for the next minor.
How a point release is advertised (do this every time, unasked). Think of the X.Y.0 release page as the shop window: it stays in the window, and each point release gets a sticky note on the glass, not a new window. Concretely:
- Never Latest.
gh release create vX.Y.Z --verify-tag --latest=false --title "vX.Y.Z" --notes-file <notes>. TheX.Y.0release stays GitHub's pinned Latest; apt/dnf, PyPI and the Dockerlatesttag still advance (they follow tags, not the GitHub flag). - Point-release notes (model: v6.2.1): one plain sentence on what it fixes;
### Fixed(and### Addedonly if the release really adds an opt-in key), each bullet user-facing;### Thankscrediting issue reporters by handle and issue link; then the closing blockquote> This point release is intentionally not marked GitHub "Latest". The vX.Y.0 feature release remains pinned there, while package repositories and container tags advance to X.Y.Z.andFull details: [changelog](https://eneru.readthedocs.io/latest/changelog/). - Swap the sticky note on
X.Y.0.gh release view vX.Y.0 --json body --jq .body > body.md, replace ONLY the top> **Update:** …blockquote (what X.Y.Z fixes in one or two sentences, "There are no new features and no breaking config changes." or the honest equivalent, "apt/dnf and the Dockerlatesttag upgrade automatically.", a link to the X.Y.Z notes, and "This page stays pinned as the latest stable."), keep the rest byte-for-byte, thengh release edit vX.Y.0 --notes-file body.md. Verify afterwards thatgh release liststill showsLatestonX.Y.0. - Issues the release addresses: comment with what shipped and ask the reporter to try it. Leave the issue open until the reporter confirms, unless the maintainer says otherwise.
Full mechanics: docs/maintenance.md ("Release mechanics").
Pre-release deep review (MANDATORY for minor/major releases). Before tagging any X.Y.0 or X.0.0, run the release-review skill (.claude/skills/release-review/SKILL.md) end-to-end: parallel multi-agent audit of the whole repository → stable-ID findings report → user triage → remediation PR → post-implementation verification round with fresh lenses. Patch releases are exempt — they inherit the minor's review. The v6.0.0/v6.1.6/v6.1.7 cycles each surfaced 60–100 real findings; the skill codifies that process so it survives context loss and model changes.
Code review workflow (manual AI invocation)
Three layers of AI review, all manually invoked (free-tier quotas: CodeRabbit one review/45 min, cubic.dev 40/month; per-commit auto-review burns quota on noisy intermediate diffs while the E2E suite already gates every push):
- Pre-push: spawn the
agent-skills:code-reviewerskill as a SUBAGENT via theAgenttool (fresh context = independent opinion — a same-session review defends its own choices; findings come back P0-P3, triage before pushing). Record the reviewer's exact model identifier and reasoning level in the review audit trail when the runtime exposes them; never guess missing metadata. - After CI is green (never before), post in PR comments:
@coderabbitai full reviewand@cubic-dev-ai review this pull request - Triage findings, push fixes (CI re-runs), re-trigger AI review only if substantive new code was added. Merge when both GitHub-side reviewers + branch protection are satisfied.
Skip all three for trivial PRs (docs-only, version bumps + changelog promotion, typo fixes, pure dependency upgrades) — the CI gates are sufficient; save the quota.
Configuration: CodeRabbit auto-review is off via .coderabbit.yaml; cubic.dev auto-review is off in its dashboard (per-repo setting). Accidentally triggered auto-reviews are harmless — close and re-trigger manually after CI is green.
Changelog
One changelog: docs/changelog.md (rendered on ReadTheDocs).
Verbose during dev, trim before release. The [Unreleased] section is a working surface — add per-rc breakouts, file references, and rationale freely; future sessions pick up context cheaper from one long file than from git log -p. The release-cut commit trims it to a published-quality entry matching prior releases (reference: v5.1.0 went from ~2950 accumulated words to ~1100 published): drop rcN — prefixes, collapse to bullet + sub-bullets, move design rationale to docs/<feature>.md, cut walkthroughs. Finally run the humanizer skill on the trimmed entry to remove AI-isms; don't mention that pass in the commit message.
Installation paths (for docs writing)
Two install methods with different invocation styles — package (deb/rpm → sudo python3 /opt/ups-monitor/eneru.py …) and pip (eneru … / python -m eneru …). Use the style matching the doc's audience; full layout and the context table are in docs/maintenance.md ("Installation paths").
Maintenance reference
GitHub Actions tag maintenance, the nFPM pin, the deliberate Docker-base-image freshness policy (ISS-045), and GitHub-release mechanics live in docs/maintenance.md. Read it before touching workflow refs or cutting a release.
Key Dependencies
- PyYAML: Configuration parsing
- Apprise (optional): Notifications
- pytest: Testing framework
<!-- trail:start -->Trail — repo context graph
This repo is indexed in .trail/cache/: small linked markdown nodes that explain each
system and carry exact file:line spans, kept in sync with the code through git.
For ANY task here — understanding how something works, finding where code lives,
or scoping a change — get context from the graph before grepping or opening
source files. Re-ask freely (it's cheap) and reuse literal identifiers you
already have (symbol, error string, file name) as the query. New to this repo?
Run trail map first — a token-budgeted orientation (dir clusters, hubs,
hotspots), no LLM, no key.
- Run
trail ask "<your question>" --source→ ranked nodes with the relevant code spans inlined (each hit's ≤8-line crux by default;--fullfor whole definitions when the crux isn't enough). Match the tool to the task shape: for understanding or editing, the top node IS the answer — cite itscovers:file:line spans and edit straight from--source. For exhaustive tasks ("every occurrence / every caller of this pattern"), ranked results are top-N, not complete — runtrail grep "<literal>"instead (exhaustive over indexed files, grouped by enclosing symbol), falling back to rawgrep -rnonly for unindexed files. trail skeleton <file>→ every definition's signature + span, ~10× cheaper than reading the file; use it to skim an API surface.trail callers <symbol>gives precomputed, exact edges — who calls this. Add--direction outfor what it calls, or--depth Nto walk transitively for the full blast radius. For structural questions, skip ranking and use this directly.- Or browse:
.trail/cache/INDEX.mdlists every node; follow the links. - Monorepos and folders of multiple repos rank fairly across sub-projects —
hits carry
[scope/]labels naming which one they're from. Narrow withtrail ask "<task>" --in <scope>/once you know where you're working.
If a returned span is truncated ("+N more lines"), open the file at that exact range before finalizing. Only open source files when a node genuinely lacks a needed detail, and then at the exact file:line the node points to — never re-read whole files.
After big code changes, refresh the graph with trail build (deterministic,
no API key, $0).
<!-- trail:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

