# Apple Notes

> Read Apple Notes via AppleScript. Use when asked to check, search, or read notes. READ ONLY — no creating or modifying notes.

- **Type:** Skill
- **Install:** `agentstack add skill-eins78-agent-skills-apple-notes`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [eins78](https://agentstack.voostack.com/s/eins78)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [eins78](https://github.com/eins78)
- **Source:** https://github.com/eins78/agent-skills/tree/main/skills/apple-notes

## Install

```sh
agentstack add skill-eins78-agent-skills-apple-notes
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Apple Notes (Read Only)

Read notes via Notes.app AppleScript. **No creating, updating, or deleting notes.**

## Prerequisites

- Notes.app running and synced
- Automation permissions granted (System Settings → Privacy & Security → Automation → Terminal/Claude Code → Notes)
- If first access attempt times out, ask user to check for macOS permission dialog

## Reliability: always wrap osascript with timeout + retry

Notes.app's AppleScript bridge hangs intermittently. AppleScript-internal `with timeout of N seconds` does NOT kill a wedged osascript process — wrap with shell-level `timeout` and retry.

```bash
notes_query() {
  local script="$1" attempt
  for attempt in 1 2 3; do
    result=$(timeout 15 osascript -e "$script" 2>&1) && { echo "$result"; return 0; }
    sleep 2
  done
  echo "ERROR: Notes query failed after 3 attempts" >&2
  return 1
}
```

Reasonable defaults: **15s timeout, 3 retries, 2s sleep**. Bump to 30s for full-text search across many notes. If all retries fail, report and move on.

## Scripts

### List folders

```bash
${CLAUDE_SKILL_DIR}/scripts/list-folders.sh              # All folders across all accounts
${CLAUDE_SKILL_DIR}/scripts/list-folders.sh iCloud       # Only iCloud folders
```

### List notes in a folder

```bash
${CLAUDE_SKILL_DIR}/scripts/list-notes.sh                        # iCloud/Notes (default)
${CLAUDE_SKILL_DIR}/scripts/list-notes.sh "Shopping"             # iCloud/Shopping
${CLAUDE_SKILL_DIR}/scripts/list-notes.sh "Notes" "Gmail"        # Gmail/Notes
```

Output: `note name | modification date` (one per line)

### Read a note

```bash
${CLAUDE_SKILL_DIR}/scripts/read-note.sh "Shopping List"             # Search all accounts
${CLAUDE_SKILL_DIR}/scripts/read-note.sh "Meeting Notes" "iCloud"    # Specific account
```

Returns metadata header + HTML body.

### Search notes by name

```bash
${CLAUDE_SKILL_DIR}/scripts/search-notes.sh "recipe"                 # Search all accounts
${CLAUDE_SKILL_DIR}/scripts/search-notes.sh "recipe" "iCloud"        # Specific account
```

Output: `note name | account/folder | modification date` (one per line)

## Direct Commands

For quick one-off access without scripts:

```bash
# List all iCloud folders
osascript -e 'tell application "Notes" to get name of every folder of account "iCloud"'

# List all note names in a folder
osascript -e 'tell application "Notes" to get name of every note in folder "Notes" of account "iCloud"'

# Read a note body (returns HTML)
osascript -e 'tell application "Notes" to get body of note "Note Name"'

# Count all notes
osascript -e 'tell application "Notes" to count every note'
```

## Notes

- Note bodies are returned as **HTML** — use for display or pipe through a converter for plain text
- Note names are **case-sensitive** in AppleScript queries
- Searching large numbers of notes can be slow — scope to a specific account when possible
- The `whose name contains` filter is case-insensitive
- Notes.app must be running — scripts will launch it if needed, but sync may take a moment

## Source & license

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

- **Author:** [eins78](https://github.com/eins78)
- **Source:** [eins78/agent-skills](https://github.com/eins78/agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-eins78-agent-skills-apple-notes
- Seller: https://agentstack.voostack.com/s/eins78
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.