/install-watchdog

name: install-watchdog
description: Installs egregore watchdog daemon via launchd or systemd for autonomous relaunching. Use when setting up egregore on a new machine. Do not use on CI/CD runners.
alwaysApply: false
category: setup
tools: []

Install Watchdog

Overview

Installs a persistent daemon that monitors the egregore process and relaunches it when needed. The daemon uses the OS-native scheduler (launchd on macOS, systemd on Linux) to run a watchdog script every 5 minutes.

The watchdog script checks:

• Whether an egregore session is already running.
• Whether the budget is in cooldown.
• Whether there are active work items in the manifest.

If all conditions are met, it launches a new egregore session.

When To Use

• After initializing an egregore project (`egregore init`)

when you want autonomous relaunching.

• When setting up egregore on a new machine.

When NOT To Use

• On CI/CD runners (use the orchestrator directly).
• When you want manual control over session launches.

Installation Steps

1. Detect the operating system

OS=$(uname -s)

2. Run the appropriate installer

**macOS (launchd):**

bash plugins/egregore/scripts/install_launchd.sh

This script creates a plist at `~/Library/LaunchAgents/com.egregore.watchdog.plist` that runs the watchdog script every 300 seconds (5 minutes).

**Linux (systemd):**

bash plugins/egregore/scripts/install_systemd.sh

This script creates a systemd timer and service unit at `~/.config/systemd/user/` that fires every 5 minutes.

3. Verify installation

**macOS:**

launchctl list | grep egregore

Expected output: a line containing `com.egregore.watchdog` with a PID or `-` status.

**Linux:**

systemctl --user status egregore-watchdog.timer

Expected output: `active (waiting)` status.

4. Confirm to the user

Report the installation result, the schedule interval, and the log file location:

• macOS: `~/.egregore/watchdog.log`
• Linux: `journalctl --user -u egregore-watchdog`

Uninstall Command

To remove the watchdog, run:

Skill(egregore:uninstall-watchdog)

Or invoke the uninstall skill directly via the command `/egregore:uninstall-watchdog`.

Troubleshooting

• **Permission denied on plist**: ensure the script runs

as the current user, not root.

• **systemd user session not available**: run

`loginctl enable-linger $USER` to enable user services without an active login session.

• **Watchdog not firing**: check the log output and verify

the scheduler is loaded (`launchctl list` or `systemctl --user list-timers`).

Exit Criteria

• [ ] On macOS: `~/Library/LaunchAgents/com.egregore.watchdog.plist`

exists after the install script completes

• [ ] On Linux: `~/.config/systemd/user/egregore-watchdog.timer`

exists after the install script completes

• [ ] Verification command confirms daemon is loaded: `launchctl list |

grep egregore` returns a line (macOS), or `systemctl --user status egregore-watchdog.timer` shows `active (waiting)` (Linux)

• [ ] Schedule interval (300 seconds / 5 minutes) and log file path

reported to the user after installation

• [ ] If `permission denied` occurs, the error is reported with the

remediation step (run as current user, not root)