apple-notes

Files (2)

• SKILL.md
• notes.py · scripts/

SKILL.md (first lines)

# 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`](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).

```sh
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

```sh
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.

```sh
# 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.

From AceDataCloud/Skills, Apache-2.0.

More from AceDataCloud/Skills