apple-notes

name	apple-notes
description	Manage Apple Notes via the `memo` CLI on macOS — create, view, search, edit, export.
version	1.2.3
requires_tools	["os.shell.run"]
dangerous	false
platforms	["darwin"]

apple-notes

Drive Apple Notes from the terminal via memo. Notes sync across Apple devices through iCloud.

Execution contract

This skill declares no bundled scripts. Never call skill.run_script for memo. Every memo ... command is an external CLI invocation and must use os.shell.run with cmd: "memo" and each command-line token in the separate args array.

Setup check (lazy — do NOT probe every turn)

Do not run a memo --version probe before each request. Just run the memo command the user asked for directly. Only when a command fails map the error to a Setup playbook branch:

• stderr mentions command not found / memo: command not found → Setup playbook → "memo is not installed".
• stderr mentions osascript / "Not authorized to send Apple events to Notes" → Setup playbook → "Automation permission denied".
• macOS not detected (e.g. uname returns Linux) → reply that this skill is macOS-only and stop. Do NOT try to install anything.

If unsure which branch applies, capture the actual stderr and ask the user before proceeding — never assume.

Setup playbook (when prerequisites are missing)

When a check fails, the agent's job is to OFFER concrete help and EXECUTE the fix itself — not to dump install instructions on the user. Use this dialogue shape:

1. State plainly what is missing (one short reply).
2. Offer the most direct remediation the agent can perform via tools.
3. Wait for the user's yes/no reply.
4. On yes, execute the fix (the runtime approval gate will surface the command for confirmation).
5. Retry the original request; only then proceed.

memo is not installed

Reply (solo reply step):

"The memo utility is not installed. I can install it myself via Homebrew (brew install antoniorodr/memo/memo); it needs your confirmation and takes ~30 seconds. Install it?"

If user agrees, execute as two consecutive solo steps:

[{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["tap", "antoniorodr/memo"] } }]

[{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["install", "antoniorodr/memo/memo"] } }]

After both succeed, retry the original command.

If brew itself is missing (exit != 0, command not found: brew), do NOT attempt to install Homebrew automatically — that requires sudo and a network curl-pipe-bash. Reply with: "You don't have Homebrew installed. I can't install it automatically — that requires sudo and an interactive install. Install it manually from https://brew.sh/, then I'll continue."

Automation permission denied

memo talks to Notes.app via AppleScript; macOS guards this behind Privacy & Security → Automation. The agent cannot toggle that switch programmatically. Help the user navigate there:

[{ "tool": "os.shell.run", "args": { "cmd": "open", "args": ["x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"] } }]

Then reply:

"I opened the right panel. Find your terminal program or atomic-agent there and enable the checkbox next to Notes. After that say "done" — I'll re-run the check."

When the user says done, retry a benign read (memo notes -s __probe__ to trigger the OS prompt if still pending), then proceed.

When to use

• The user asks to create, view, search, edit, move, or export Apple Notes.
• The user wants notes that sync to their iPhone / iPad / Mac via iCloud.

When NOT to use

• Markdown-native vault management — use the obsidian skill instead.
• Agent-internal scratch notes that don't need to leave the agent — use the memory.notes.store tool.
• Bear / other note apps — memo only talks to Apple Notes.

Common operations

All examples invoke os.shell.run with cmd: "memo" and the args array shown.

View

Goal	args
List all notes	["notes"]
Filter by folder	["notes", "-f", "Folder Name"]
Fuzzy search	["notes", "-s", "query"]

Create

Goal	args
Open interactive editor	["notes", "-a"]
Quick add with title	["notes", "-a", "Note Title"]

Edit / delete / move

Goal	args
Pick a note to edit (interactive)	["notes", "-e"]
Pick a note to delete (interactive)	["notes", "-d"]
Move a note to another folder (interactive)	["notes", "-m"]

Export

Goal	args
Export to HTML/Markdown	["notes", "-ex"]

Limitations

• Cannot edit notes that contain images or attachments (Apple's AppleScript surface limitation).
• Interactive subcommands (-a without title, -e, -d, -m, -ex) need a real TTY. They will hang or error from a non-interactive shell — prefer the explicit-title form (-a "Title") when scripting.
• macOS only. Do not attempt on other platforms.

Rules

1. Confirm content and target folder with the user before creating or modifying a note.
2. Prefer Apple Notes when the user wants cross-device iCloud sync; otherwise route to obsidian (vault) or memory.notes.store (agent memory).
3. Never paste user note bodies into traces or logs without checking — Notes can contain personal data.