apple-notes — manage Apple Notes locally via AppleScript

Drives the user's real Apple Notes through Notes.app on macOS. Apple never shipped a cloud API for Notes, so there is nothing to OAuth into and no token to inject — this skill runs on the user's own Mac and talks to Notes.app with AppleScript (osascript). It works wherever an agent runs on macOS: the AceDataCloud desktop app (which executes local tools / local MCP on the user's Mac), Claude Code on macOS, or a CodingBridge node on the user's Mac.

surfaces: [mac] in the frontmatter marks this skill as macOS-desktop only — it cannot run on the web / iOS / Android / Windows surfaces (there is no local Notes.app there). The skill/connector directory UI reads this to badge the card ("macOS desktop") and steer users to install it from the macOS desktop app. Absent surfaces, a skill is assumed available everywhere.

The skill ships scripts/notes.py — self-contained, Python standard library only (it shells out to osascript; no pip install, no brew). Dynamic values are passed as environment variables, never interpolated into the AppleScript source, so note content can't break the script or inject commands.

Requirements

macOS with the Notes app. python3 (system Python is fine).
Automation permission. The first call triggers a macOS prompt: "Terminal wants to control Notes." Approve it, or enable it under System Settings › Privacy & Security › Automation › (your terminal / agent) › Notes. On an authorization error the CLI tells the user exactly this — do not loop-retry.
Referencing Notes launches the app in the background (no window is forced open).

NOTES="${SKILL_DIR:-.}/scripts/notes.py"   # run from this skill's directory
python3 "$NOTES" folders                    # smoke-test the connection

Commands

Command	Read/Write	Purpose
`folders`	read	List folders with note counts
`list [--folder F] [--limit N]`	read	List notes (newest first): id, title, folder, dates
`search QUERY [--folder F] [--limit N]`	read	Case-insensitive substring match on title + body
`view NOTE_ID [--format json\|text\|html]`	read	Show one note (metadata + body)
`export NOTE_ID [--format md\|html\|text] [-o FILE]`	read	Export one note to Markdown/HTML/text
`create --title T [--body B \| --body-file F] [--folder F]`	write	Create a note
`append NOTE_ID [--body B \| --body-file F]`	write	Append text to an existing note
`move NOTE_ID --folder F`	write	Move a note to another folder
`new-folder NAME`	write	Create a folder
`delete NOTE_ID`	write	Move a note to Recently Deleted (recoverable)

Most commands print JSON (and errors are always JSON: {"error": ...}). The exceptions print raw note content to stdout: view --format text|html and export without -o. NOTE_ID is the opaque x-coredata://… id returned by list / search — always fetch a fresh id first; do not guess one.

Read examples

python3 "$NOTES" folders
python3 "$NOTES" list --limit 20
python3 "$NOTES" list --folder "Work" --limit 50
python3 "$NOTES" search "invoice" --limit 20
python3 "$NOTES" view "x-coredata://…/p42"
python3 "$NOTES" export "x-coredata://…/p42" --format md -o note.md

Writes are GATED (dry-run unless trailing `--confirm`)

create, append, move, new-folder, and delete change the user's real notes. Without a trailing --confirm they dry-run and print what they would do. --confirm is honored only as the very last argument. Always show the dry-run, get an explicit "yes", then re-run with --confirm appended.

# Create — dry-run, then confirm
python3 "$NOTES" create --title "Groceries" --body "milk\neggs"                # preview
python3 "$NOTES" create --title "Groceries" --body "milk\neggs" --confirm      # writes

# Create in a folder, body from a file
python3 "$NOTES" create --title "Spec" --body-file draft.md --folder "Work" --confirm

# Append to an existing note
python3 "$NOTES" append "x-coredata://…/p42" --body "one more line" --confirm

# Move / organize
python3 "$NOTES" new-folder "Archive" --confirm
python3 "$NOTES" move "x-coredata://…/p42" --folder "Archive" --confirm

# Delete → goes to Recently Deleted (recoverable ~30 days)
python3 "$NOTES" delete "x-coredata://…/p42" --confirm

Content is treated as plain text (each line becomes a paragraph; the --title is the note's first line, which Notes shows as the title). HTML in the input is escaped, so it can't inject markup. Use \n for line breaks in --body, or pass a file with --body-file.

Gotchas

This is the user's real Notes account. Confirm before any write.
list scans the whole library — for large accounts it can take a few seconds. Narrow with --folder, and cap with --limit (default 50). search filters inside Notes and is faster.
Attachments / images: notes containing images or attachments can be read and exported as text, but append may not preserve embedded attachments — avoid editing attachment notes here; open them in Notes instead.
Export → Markdown converts common Notes formatting (headings, bold/italic, lists, links, line breaks). Rich objects (tables, drawings, scanned docs) degrade to plain text.
move stays within one account (e.g. iCloud). Cross-account moves fail.
Never assume a NOTE_ID — ids are store-specific; always get them from list / search first.
On a persistent authorization error, the Automation permission is missing — tell the user to grant it (see Requirements) and stop; do not retry in a loop.

apple-notes