---

name: apple-notes-observability description: 'Monitor Apple Notes automation health and performance metrics.

Trigger: "apple notes monitoring".

' allowed-tools: Read, Write, Edit, Bash(osascript:*), Grep version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• macos
• apple-notes
• automation compatibility: Designed for Claude Code

---

Apple Notes Observability

Overview

Apple Notes has no built-in metrics API or health endpoint. Observability must be built from the outside: polling note counts and folder states via JXA, monitoring iCloud sync daemon health, tracking osascript response latency, and watching system logs for Notes-related errors. This guide sets up a lightweight monitoring stack using bash scripts, structured JSON logs, and macOS notifications for alerting. For persistent monitoring, deploy the health check as a launchd agent that runs on a schedule.

Prerequisites

• A job-owned, permission-restricted log directory with rotation and retention limits.
• A monitoring scope limited to the approved account/folder; counts are sensitive operational metadata and must not be sent to broad telemetry.
• A defined alert owner and a sustained-failure threshold so transient iCloud or TCC conditions do not trigger unsafe remediation.

Instructions

1. Collect only health status, bounded latency, and coarse scoped counts required for the alert decision.
2. Sanitize shell output before emitting JSON; do not interpolate account names, note titles, bodies, or raw errors into notifications.
3. Alert after the agreed consecutive failure threshold and link to the incident runbook.
4. Rotate logs and review access periodically; monitoring must never restart iCloud processes or modify Notes state.

Health Check Script

#!/bin/bash
# scripts/notes-health-check.sh — Deploy via launchd (every 5 minutes)
LOG_FILE="${NOTES_LOG_DIR:-/tmp}/notes-health.jsonl"

timestamp=$(date -Iseconds)
notes_running=$(pgrep -x Notes > /dev/null && echo "true" || echo "false")

# Measure JXA latency
start_ms=$(($(date +%s%N)/1000000))
note_count=$(osascript -l JavaScript -e 'Application("Notes").defaultAccount.notes.length' 2>/dev/null || echo "-1")
folder_count=$(osascript -l JavaScript -e 'Application("Notes").defaultAccount.folders.length' 2>/dev/null || echo "-1")
account_count=$(osascript -l JavaScript -e 'Application("Notes").accounts().length' 2>/dev/null || echo "-1")
end_ms=$(($(date +%s%N)/1000000))
latency_ms=$((end_ms - start_ms))

# iCloud sync daemon status
bird_running=$(pgrep -x bird > /dev/null && echo "true" || echo "false")
cloudd_running=$(pgrep -x cloudd > /dev/null && echo "true" || echo "false")

# Determine health
healthy="true"
[ "$notes_running" = "false" ] && healthy="false"
[ "$note_count" = "-1" ] && healthy="false"
[ "$latency_ms" -gt 10000 ] && healthy="false"

echo "{\"ts\":\"$timestamp\",\"running\":$notes_running,\"notes\":$note_count,\"folders\":$folder_count,\"accounts\":$account_count,\"latency_ms\":$latency_ms,\"bird\":$bird_running,\"cloudd\":$cloudd_running,\"healthy\":$healthy}" >> "$LOG_FILE"

# Alert on unhealthy state
if [ "$healthy" = "false" ]; then
  osascript -e "display notification \"Notes health check failed (notes=$note_count, latency=${latency_ms}ms)\" with title \"Notes Alert\""
fi

Metrics Dashboard (CLI)

#!/bin/bash
# scripts/notes-dashboard.sh — Quick view of recent health data
LOG_FILE="${NOTES_LOG_DIR:-/tmp}/notes-health.jsonl"

echo "=== Apple Notes Health Dashboard ==="
echo "Last 10 checks:"
tail -10 "$LOG_FILE" | jq -r '"\(.ts) | notes=\(.notes) | folders=\(.folders) | latency=\(.latency_ms)ms | healthy=\(.healthy)"'

echo ""
echo "=== Trend (note count, last 24h) ==="
# Show note count changes
awk -F'"notes":' '{split($2,a,","); print a[1]}' "$LOG_FILE" | tail -48 | sort -u

echo ""
echo "=== Alerts (unhealthy checks) ==="
grep '"healthy":false' "$LOG_FILE" | tail -5 | jq -r '"\(.ts): notes=\(.notes), latency=\(.latency_ms)ms"'

Structured Metrics Collection

// src/observability/metrics.ts
import { execSync } from "child_process";
import { appendFileSync } from "fs";

interface NotesMetrics {
  timestamp: string;
  noteCount: number;
  folderCount: number;
  accountCount: number;
  latencyMs: number;
  healthy: boolean;
  icloudSyncActive: boolean;
}

function collectMetrics(): NotesMetrics {
  const start = Date.now();
  try {
    const output = execSync(
      `osascript -l JavaScript -e 'JSON.stringify({n: Application("Notes").defaultAccount.notes.length, f: Application("Notes").defaultAccount.folders.length, a: Application("Notes").accounts().length})'`,
      { encoding: "utf8", timeout: 15000 }
    );
    const data = JSON.parse(output);
    const bird = execSync("pgrep -x bird > /dev/null && echo 1 || echo 0", { encoding: "utf8" }).trim();
    return {
      timestamp: new Date().toISOString(), noteCount: data.n, folderCount: data.f,
      accountCount: data.a, latencyMs: Date.now() - start, healthy: true,
      icloudSyncActive: bird === "1",
    };
  } catch {
    return {
      timestamp: new Date().toISOString(), noteCount: 0, folderCount: 0,
      accountCount: 0, latencyMs: Date.now() - start, healthy: false,
      icloudSyncActive: false,
    };
  }
}

Error Handling

Issue	Cause	Solution
Latency spikes >10s	Notes.app indexing or large iCloud sync	Transient; alert only if sustained over 3 consecutive checks
Note count drops to 0	iCloud account signed out or TCC revoked	Check defaults read MobileMeAccounts; re-authenticate
bird process not running	iCloud daemon unavailable	Alert the owner and follow supported macOS/iCloud recovery guidance
Health check script fails	osascript timeout	Add timeout 15 prefix to osascript calls
Log file grows unbounded	No rotation configured	Add logrotate config or truncate weekly via launchd

Output

The health check emits a redacted timestamped health result, latency bucket, and bounded status counters to the restricted log. The alert states only that the scoped health check failed and where the owner can inspect the protected evidence.

Examples

If three consecutive checks cannot perform the scoped read-only query, send one deduplicated alert, pause any dependent write queue, and open the incident runbook. Do not place the raw osascript error or a note count in a desktop notification.

Resources

• macOS Unified Logging
• launchd.plist Reference
• Mac Automation Scripting Guide

Next Steps

For alerting on incidents detected by monitoring, see apple-notes-incident-runbook. For performance optimization when metrics show slowdowns, see apple-notes-performance-tuning.