--- 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.0.0 license: MIT author: Jeremy Longshore 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. ## Health Check Script ```bash #!/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) ```bash #!/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 ```typescript // 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 crashed | `killall bird` triggers automatic restart by launchd | | 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 | ## Resources - [macOS Unified Logging](https://developer.apple.com/documentation/os/logging) - [launchd.plist Reference](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html) - [Mac Automation Scripting Guide](https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/) ## 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`. --- Source attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/main/plugins/saas-packs/apple-notes-pack/skills/apple-notes-observability/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/main/plugins/saas-packs/apple-notes-pack/skills/apple-notes-observability/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Operations Roles: Backend Developer, DevOps / SRE, IT Operations Specialties: Backend Tools: Jq, Osascript Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 889c1a8540f498e3d7bb00050e4aba59091c16e73ac8e3ff2ba9adf3183eace4