Ops Daemon

Runtime Context

Before diagnosing, load:

1. Plugin root: echo "${CLAUDE_PLUGIN_ROOT:-$(ls -d "$HOME/.claude/plugins/cache/ops-marketplace/ops"/*/ 2>/dev/null | sort -V | tail -1)}" — newest installed version
2. Daemon health: cat ${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/daemon-health.json — primary diagnostic input
3. Services config: cat ${CLAUDE_PLUGIN_DATA_DIR}/daemon-services.json — per-service command + cron definitions
4. OS: uname -s — daemon install is macOS-only (launchd). Linux/WSL/Windows fall back to manual invocation.

OPS ► DAEMON

Diagnostic + auto-fix surface for the background ops-daemon process. Acts like ops-doctor but scoped to the one subsystem users actually see break: the launchd daemon that keeps briefing-pre-warm, memory-extractor, message-listener, inbox-digest, and competitor-intel alive.

CLI/API Reference

bin/ops-daemon-manager.sh

| Command | Usage | Output | | --------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- | | ${CLAUDE_PLUGIN_ROOT}/scripts/ops-daemon-manager.sh status | Emit JSON snapshot | {os, installed, running, pid, plist_version_match, health_fresh, ...} | | ${CLAUDE_PLUGIN_ROOT}/scripts/ops-daemon-manager.sh install | First-time install (idempotent) | Writes plist, loads launchd | | ${CLAUDE_PLUGIN_ROOT}/scripts/ops-daemon-manager.sh upgrade | Re-point plist at current PLUGIN_ROOT + reload | Fixes stale version paths | | ${CLAUDE_PLUGIN_ROOT}/scripts/ops-daemon-manager.sh restart | Unload + reload without reconfiguring | Clears stuck state | | ${CLAUDE_PLUGIN_ROOT}/scripts/ops-daemon-manager.sh uninstall | Stop + remove plist | Returns system to pre-install state |

Accepts --plugin-root PATH to override auto-detection and --dry-run to preview without side effects.

Health file schema

${CLAUDE_PLUGIN_DATA_DIR}/daemon-health.json:

{
  "timestamp": "",
  "pid": ,
  "uptime_seconds": ,
  "services": {
    "": {
      "status": "running|polling|scheduled|dead|needs_reauth|max_restarts_exceeded",
      "pid": ,
      "last_health": "",
      "last_run": "",
      "next_run": "",
      "restarts": ,
      "latency_ms": ,
      "last_success": "",
      "error_count": ,
      "last_error": ""
    }
  },
  "action_needed": null | {"kind": "...", "service": "...", "message": "..."},
  "credential_warnings": ["", ...],
  "rate_limit_warnings": ["", ...]
}

A healthy daemon refreshes this file every 30s. An mtime older than 120s is a strong fail signal.

Per-service fields (Phase 16 additions):

• latency_ms — duration of the most recent run for warm/cron services, in milliseconds. 0 when no run has occurred yet.
• last_success — ISO-8601 UTC of the last clean run (no errors). Empty until the first success.
• error_count — cumulative error count since daemon start. Reset on daemon restart.
• last_error — truncated (≤300 chars) message from the most recent failure. null when there have been no failures.

Top-level fields (Phase 16 additions):

• credential_warnings — list of credentials that are expiring within 7 days or are keys older than 180 days. Populated from offline inspection of preferences.json (never a live API call).
• rate_limit_warnings — list of integrations currently at ≥80% of their quota window. Populated from rate-limits.json counters.

Persistent service failure: a service that hits max_restarts_exceeded status dispatches a one-shot HIGH severity push notification via ops-notify.sh to every configured sink (Telegram / Discord / ntfy / Pushover / macOS). The notification is re-armed the moment the service returns to running, so subsequent regressions still notify.

Smart Cache Invalidation (git hooks)

Cache timestamp files (.briefing_ts, .projects_ts, .marketing_ts, .prs_ts, .ci_ts) are deleted on local git commit and git merge so the next daemon warm cycle refreshes those specific caches without waiting for the normal throttle window.

Install:

bash ${CLAUDEPLUGINROOT}/scripts/ops-install-git-hooks.sh

Preview without writing:

bash ${CLAUDEPLUGINROOT}/scripts/ops-install-git-hooks.sh --dry-run

Remove:

bash ${CLAUDEPLUGINROOT}/scripts/ops-install-git-hooks.sh --uninstall

The installer is idempotent and only touches the block between # BEGIN ops-daemon-invalidate and # END ops-daemon-invalidate — existing husky / lefthook / pre-commit content in .git/hooks/post-commit or .git/hooks/post-merge is preserved.

Marketing Pre-Warm

The opt-in marketing-prewarm cron service pre-fetches cross-platform marketing data (Klaviyo, Meta Ads, GA4, GSC, Google Ads) every 15 minutes so /ops:marketing loads instantly from cache. Disabled by default; enable with /ops:setup marketing once marketing credentials are configured.

Rate Limit Tracking

Per-integration counters in ${CLAUDE_PLUGIN_DATA_DIR}/rate-limits.json — {quota, calls, window_start, warned_80pct} per integration. On each tracked API call the daemon advances the rolling window, increments the counter, and sends a single MEDIUM push notification when the ratio crosses 80%. Windows reset automatically on rollover, which re-arms the 80% warning.

Override the seeded defaults by setting rate_limit_quotas in ${CLAUDE_PLUGIN_DATA_DIR}/preferences.json:

{
  "rate_limit_quotas": {
    "meta_ads": { "quota": 200, "window_seconds": 3600 },
    "klaviyo": { "quota": 75, "window_seconds": 60 }
  }
}

Credential Rotation Alerts

The daemon checks ${CLAUDE_PLUGIN_DATA_DIR}/preferences.json once an hour for:

• _expires_at — ISO-8601 timestamp or the literal string "never". Warns when within 7 days of expiry.
• _created_at — ISO-8601 timestamp of when an API key was last created/rotated. Warns once the key is 180 days old.

The check is entirely offline — it never makes a network call. Warnings surface in daemon-health.json as credential_warnings and trigger a MEDIUM push notification once per (credential, day) tuple. /ops:fires lists them alongside Sentry / infra / CI issues.

---

Your task

Route on the first argument:

| Argument | Action | | ----------------- | ------------------------------------------------------------------------------------------- | | check (default) | Run all diagnostics, print a colored report, exit 0 if green / 1 otherwise | | fix | Run check, then per detected issue ask the user for confirmation and apply the fix | | restart | Call ops-daemon-manager.sh restart | | status | Print the JSON output of ops-daemon-manager.sh status verbatim — consumed by other skills | | uninstall | Ask [Uninstall] / [Cancel] via AskUserQuestion, then call the manager |

Diagnostic checklist

Run each check and track results as pass / fail / warn:

1. Plugin root resolved — CLAUDE_PLUGIN_ROOT env var set OR ~/.claude/plugins/cache/ops-marketplace/ops//scripts/ops-daemon.sh exists.
2. OS supported — uname -s is Darwin. On Linux/WSL print the manual invocation and exit 0 with a warn note. On native Windows print "not supported".
3. Plist installed — ~/Library/LaunchAgents/com.claude-ops.daemon.plist exists.
4. Plist points at current version — the second ` inside ProgramArguments equals ${PLUGIN_ROOT}/scripts/ops-daemon.sh`. Mismatch = stale after upgrade (the most common failure mode).
5. Plist is valid XML — plutil -lint passes.
6. Launchctl registered — launchctl list shows the label with a real PID (not -).
7. Process alive — kill -0 succeeds.
8. Bash binary exists — the first ` in ProgramArguments is executable and reports BASH_VERSINFO >= 4 (required for declare -A` in the daemon script).
9. Health file fresh — daemon-health.json exists, mtime within last 120 seconds.
10. Every service has a command — iterate daemon-services.json services; each enabled entry must have a non-empty command field. Missing command silently skips the service (historical bug).
11. Running services alive — for each service in the health file with status=running|polling, verify kill -0 succeeds.
12. Cron services have future next_run — scheduled services must have a next_run timestamp in the future.
13. whatsapp-bridge running — if enabled, lsof -i :8080 | grep LISTEN returns a result. (Optional — mark warn not fail if missing.)
14. No zombie children — no orphaned ops-message-listener.sh processes without a parent ops-daemon.sh.

Fix playbook

For each failed check, fix mode proposes a specific repair and asks the user with AskUserQuestion (max 4 options — always include [Skip]):

| Failure | Fix | Destructive? | | ---------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------- | | Plist stale version path | ops-daemon-manager.sh upgrade | Yes — unloads + reloads | | Plist missing | ops-daemon-manager.sh install | No | | Plist invalid XML | Regenerate via install (after backup) | Yes — overwrites | | Process dead but plist ok | ops-daemon-manager.sh restart | Yes — restarts | | Health file stale (>120s) | ops-daemon-manager.sh restart | Yes | | Service missing command | Merge from scripts/daemon-services.example.json into user's daemon-services.json after showing a diff | Yes — writes config | | Bash binary missing/ with per-process confirmation (Rule 5) | Yes | | Services config corrupt JSON | Restore from scripts/daemon-services.default.json` after confirmation + backup | Yes |

Never batch fixes. Per Rule 5, each destructive action needs its own AskUserQuestion with [Apply] / [Skip] options.

Output format for check

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPS ► DAEMON CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 OS:           macos
 Plugin root:  ${CLAUDE_PLUGIN_ROOT}
 Daemon PID:   57004
 Uptime:       1h 12m

 ✓ Plist installed
 ✓ Plist points at current version
 ✓ Plist is valid XML
 ✓ Launchctl registered, PID alive
 ✓ Bash binary found (5.3)
 ✓ Health file fresh (mtime 23s ago)
 ✓ All 5 enabled services have commands
 ✓ Running services alive
 ✓ Cron services have future next_run

 STATUS: GREEN — daemon healthy

On failure, replace ✓ with ✗ and append a one-line remediation hint. Exit 1 so /ops:ops-status can surface red.

Output format for status

Print the JSON from ops-daemon-manager.sh status verbatim. No wrapping. This is the machine-readable contract consumed by ops-status, ops-go, and other skills.

Output format for fix

Render the check report, then for each failing check enter a confirmation loop:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPS ► DAEMON FIX — 3 issues found
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 ✗ Plist points at old version 1.0.0
   → Proposed: ops-daemon-manager.sh upgrade

Then AskUserQuestion with [Apply fix] / [Skip this issue] / [Cancel all]. Repeat for each issue. After all actions, re-run check and print a before/after diff.

Cross-OS notes

• macOS: full support via launchd. All subcommands available.
• Linux / WSL: ops-daemon-manager.sh install exits EX_UNAVAILABLE (69) and prints the manual nohup invocation. check still validates the daemon script and services config.
• Windows native: unsupported. Use WSL.

Do not hardcode launchctl in this SKILL — always route through the manager script so future systemd / Task Scheduler support is a one-line addition.

Examples

# Morning habit: confirm the daemon survived overnight
/ops:daemon check

# After a plugin upgrade (`/plugin upgrade claude-ops`):
/ops:daemon fix
# → detects stale plist, asks [Apply upgrade], reloads, verifies

# Embedded in another skill:
/ops:daemon status | jq -r '.health_fresh'

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lifecycle-Innovations-Limited
• Source: Lifecycle-Innovations-Limited/claude-ops
• License: MIT
• Homepage: https://github.com/Lifecycle-Innovations-Limited/claude-ops/wiki

Install and usage instructions live in the source repository linked above.