florian/heartbeat-check
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
1 commit 1 branch 0 tags 33 KiB
  • Shell 100%
Find a file
Exact
Florian Beisel c2c966d8a7 Add heartbeat check script and docs
2026-03-07 16:50:44 +01:00
heartbeat-check.sh Add heartbeat check script and docs 2026-03-07 16:50:44 +01:00
README.md Add heartbeat check script and docs 2026-03-07 16:50:44 +01:00

README.md

heartbeat-check

Einführung

heartbeat-check ist ein leichter Bash-Orchestrator, der nacheinander die fünf wichtigsten Überwachungen abarbeitet: E‑Mail, Kalender, Tasks, Git und System. Das Skript wählt bei jedem Aufruf den gerade am meisten überfälligen Check innerhalb seines Zeitfensters aus, führt ihn aus und aktualisiert die Zeitstempel in memory/heartbeat-state.json. Eine zusätzliche Prioritätsschleife schaut immer zuerst nach /tmp/wilbur-wake.txt, damit Coding-Agenten ihre Fertigstellung sofort melden können.

Der Wilbur‑Heartbeat (siehe HEARTBEAT.md) ruft dieses Skript auf, Pulse reagiert auf die Ausgabe (HEARTBEAT_OK oder ein Warnhinweis). Alternativ kannst du ein Cron- oder systemd-Timer-Job aufsetzen, der heartbeat-check regelmäßig startet, damit sich die Checks auch dann drehen, wenn Pulse keine Signale liefert.

Installation

  1. Kopiere das Skript an einen Ort im PATH: 
    cp heartbeat-check.sh /home/florian/.local/bin/heartbeat-check
chmod +x /home/florian/.local/bin/heartbeat-check
  2. Stelle sicher, dass die Abhängigkeiten verfügbar sind: jq, himalaya, planka-cli, git, systemctl --user und (falls du Logging willst) Zugriff auf /tmp/openclaw-$(id -u)/openclaw-*.log.
  3. Optional kannst du /home/florian/.local/bin/heartbeat-check in ein Cron- oder Timer-Job einbinden (siehe Beispiele).

Konfiguration

CHECKS-Map

Die eingebauten Checks leben in der assoziativen CHECKS-Map im Skript. Jede Zeile hat das Format interval_seconds:start_hour:end_hour. Die Default-Werte lauten:

Check Intervall Zeitfenster Bedeutung
email 1 800 s 09:00 – 21:00 himalaya prüft ungelesene Mails im Posteingang
calendar 7 200 s 08:00 – 22:00 Placeholder für Kalender‑Events (TODO: gog/bigquery o.Ä.)
tasks 1 800 s Rund um die Uhr planka-cli + shared-knowledge/TASKS.md auf offene/blockierte Karten
git 86 400 s Rund um die Uhr Git‑Status des Workspaces auf ungesicherte Änderungen prüfen
system 86 400 s 03:00 – 04:00 Fehlgeschlagene systemctl --user Units + OpenClaw-Logfehler

Wenn du ein Intervall änderst, denk daran, dass das Skript nur innerhalb des angegebenen Fensters reagiert. Entferne die Zeile oder kommentiere sie aus, um einen Check zu deaktivieren. Weitere Anpassungen findest du unter shared-knowledge/tools/heartbeat-check/how-to-configure-checks.md.

State & Wake-Datei

State-File: /home/florian/.openclaw/workspace/memory/heartbeat-state.json – es enthält ein JSON-Objekt mit lastChecks.{email,calendar,tasks,git,system} (Epoch-Sekunden). Du kannst einzelne Timestamps mit jq zurücksetzen oder alle auf 0 setzen, wenn du einen Check sofort forcieren willst.

Wake-Datei: /tmp/wilbur-wake.txt dient dazu, dass Coding-Agenten dem Heartbeat sofort melden: Solange die Datei existiert, wird ihr Inhalt (z. B. Task #123 done) ausgegeben und der Rest der Rotation übersprungen. Die Datei wird danach gelöscht.

Neue Checks

Neue Funktionen fügst du nach der bestehenden Struktur hinzu: declare -A CHECKS, eine check_<name>()-Funktion und einen case-Zweig. Zur Anleitung: shared-knowledge/tools/heartbeat-check/how-to-add-custom-checks.md.

Usage

heartbeat-check

Das Skript gibt nur dann Text aus, wenn ein Check ein Problem gefunden hat, z. B. 📧 5 neue E-Mail(s) oder ⚠️ 2 failed systemd service(s). Ist alles sauber, kommt HEARTBEAT_OK. Setze das Skript in deinem HEARTBEAT-Prompt (siehe HEARTBEAT.md), damit Pulse nur bei echten Alerts eine Nachricht schickt.

Für Cron/systemd-Timer nimmst du z. B.:

*/15 * * * * /home/florian/.local/bin/heartbeat-check >/tmp/heartbeat-check.log 2>&1

Das Intervall sollte kleiner oder gleich der kleinsten interval_seconds sein, also alle 15 oder 30 Minuten. Der Timer kann zusätzlich eine Pulse‑Session auslösen (Signal HEARTBEAT_CHECK), wenn du die Ausgabe an eine Agent-Session weiterreichst.

Beispiele

  1. Cron-Beispiel: Job ausführen lassen, damit system nachts geprüft wird, auch wenn kein Heartbeat-Signal anliegt.
  2. Intervall ändern: CHECKS[email]="900:7:23" sorgt dafür, dass Mails alle 15 Minuten (7–23 Uhr) geprüft werden.
  3. State-Check: jq '.lastChecks.email' memory/heartbeat-state.json zeigt die letzte Laufzeit; date -d "@$(jq -r '.lastChecks.email' memory/heartbeat-state.json)'" macht sie lesbar.

Troubleshooting

  • jq oder planka-cli fehlen: Installiere die Pakete über deine Distribution oder über pip/npm. Das Skript gibt keine Fehlermeldung bei fehlenden Tools, du musst also manuell prüfen.
  • himalaya meldet keine Mail: Prüfe himalaya config und dass dein IMAP-Account erreichbar ist. Alternativ lasse das Mail-Check deaktiviert, indem du check_email leerst.
  • systemctl --user schlägt fehl: Stelle sicher, dass du in einer systemd-User-Sitzung bist (loginctl enable-linger ${USER}) oder nutze statt Cron einen systemd-Timer, damit systemctl --user funktioniert.
  • State-Datei beschädigt: Setze memory/heartbeat-state.json zurück (siehe oben).
  • Keine Heartbeat-Ausgabe: heartbeat-check läuft trotzdem, solange du HEARTBEAT.md oder Cron nur bei Alerts auf HEARTBEAT_OK prüfst.

Links

  • HEARTBEAT.md im Wilbur-Workspace (Puls-Signale & HEARTBEAT_CHECK-Flow)
  • shared-knowledge/topics/heartbeat-system.md (Technische Übersicht zu Checks & State)
  • shared-knowledge/tools/heartbeat-check/how-to-configure-checks.md
  • shared-knowledge/tools/heartbeat-check/how-to-add-custom-checks.md