name: apple-notes-rate-limits description: 'Handle Apple Notes automation rate limits and iCloud sync throttling.

Trigger: "apple notes rate limit".

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

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

Apple Notes Rate Limits

Overview

Apple Notes has no formal API rate limits like cloud services do. However, there are practical throughput limits imposed by three systems: the Apple Events IPC bridge (osascript to Notes.app), the iCloud sync daemon (bird/cloudd) that must process each write, and the Notes.app SQLite database that handles concurrent access. Exceeding these practical limits causes timeouts (-1712), sync lag, or data loss when writes outpace iCloud's upload buffer. This guide documents safe operation rates and provides throttling patterns.

Practical Rate Limits

Throttled Operation Queue

// src/rate-limit/throttle.ts
import { execSync } from "child_process";

interface ThrottleConfig {
  minDelayMs: number;
  maxRetries: number;
  backoffMultiplier: number;
}

const THROTTLE_CONFIGS: Record<string, ThrottleConfig> = {
  read:   { minDelayMs: 100,  maxRetries: 3, backoffMultiplier: 2 },
  write:  { minDelayMs: 1000, maxRetries: 5, backoffMultiplier: 2 },
  delete: { minDelayMs: 1000, maxRetries: 3, backoffMultiplier: 3 },
  search: { minDelayMs: 500,  maxRetries: 2, backoffMultiplier: 2 },
};

async function throttledExec<T>(
  operation: () => T,
  type: keyof typeof THROTTLE_CONFIGS = "write"
): Promise<T> {
  const config = THROTTLE_CONFIGS[type];
  let delay = config.minDelayMs;

  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      const result = operation();
      await new Promise(r => setTimeout(r, config.minDelayMs));
      return result;
    } catch (e: any) {
      if (attempt === config.maxRetries) throw e;
      console.warn(`Retry ${attempt + 1}/${config.maxRetries} after ${delay}ms: ${e.message}`);
      await new Promise(r => setTimeout(r, delay));
      delay *= config.backoffMultiplier;
    }
  }
  throw new Error("Unreachable");
}

Batch Operations with Rate Limiting

#!/bin/bash
# Batch create notes with throttling
INPUT_FILE="$1"  # JSON array of {title, body} objects
DELAY=1  # seconds between creates

jq -c '.[]' "$INPUT_FILE" | while IFS= read -r note; do
  title=$(echo "$note" | jq -r '.title')
  body=$(echo "$note" | jq -r '.body')
  osascript -l JavaScript -e "
    const Notes = Application('Notes');
    const n = Notes.Note({name: '$title', body: '$body'});
    Notes.defaultAccount.folders[0].notes.push(n);
    n.name();
  " && echo "Created: $title" || echo "FAILED: $title"
  sleep "$DELAY"
done

iCloud Sync Monitoring During Bulk Operations

# Monitor iCloud sync backlog during batch operations
watch -n 5 'echo "=== Sync Status ===";
  brctl status com.apple.Notes 2>/dev/null || echo "brctl unavailable";
  echo ""; echo "=== Note Count ===";
  osascript -l JavaScript -e "Application(\"Notes\").defaultAccount.notes.length" 2>/dev/null'

Error Handling

Resources

• Mac Automation Scripting Guide
• Apple Events Programming Guide
• iCloud Sync Architecture

Next Steps

For performance optimization beyond throttling, see apple-notes-performance-tuning. For monitoring sync health during operations, see apple-notes-observability.