apple-notes
/apple-notes
Read, search, write Apple Notes on macOS and extract their images. Enforces an inbox/ready/done/docs layout per project. Use when the user references Apple Notes, "check my notes", "pull bug reports from Notes", or extract screenshots.
- Author
- silvio-l ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/_helper.py
What it does and when to use it
Read, search, write Apple Notes on macOS and extract their images. Enforces an inbox/ready/done/docs layout per project. Use when the user references Apple Notes, "check my notes", "pull bug reports from Notes", or extract screenshots.
Triggers from the description
Original author description
Read, search, write Apple Notes on macOS and extract their images. Enforces an inbox/ready/done/docs layout per project. Use when the user references Apple Notes, "check my notes", "pull bug reports from Notes", or extract screenshots.
How it works
- Project layout (enforced by init, scanned by all reads)
- What each folder means → which one to read
- Quick start
- Subcommands
- Token-efficiency rules
- Workflows
- Setup
- macOS permissions
- Long titles & truncation
- Limitations
SKILL.md preview
---
name: apple-notes
description: Read, search, write Apple Notes on macOS and extract their images. Enforces an inbox/ready/done/docs layout per project. Use when the user references Apple Notes, "check my notes", "pull bug reports from Notes", or extract screenshots.
---
# Apple Notes
One dispatcher: `scripts/apple-notes <subcommand>`. AppleScript under the hood. Output is plain text by default, `--json` available where useful.
## Project layout (enforced by `init`, scanned by all reads)
```
Firma/ ← company folder (configurable; default "Firma" in iCloud)
ProjektA/ ← one subfolder per app/repo
inbox/ ← new, untriaged
ready/ ← triaged, ready for work
done/ ← merged / shipped
docs/ ← templates, briefing, specs — NOT issues
Projekt-B/
inbox/ ready/ done/ docs/
```
**Title-prefix convention** (the only requirement, surfaced by `triage`):
`BUG:` `FEAT:` `IDEA:` `FB:` (user feedback) `TECH:` (tech debt / refactor).
**Body**: free-form text. Non-technical partners write plain prose using the BUG / FEAT / IDEA / FB templates seeded under `docs/`. Only the TECH template (the maintainer's own notes) carries a compact `·`-separated metadata first line — agents and `triage` do not require it for any other prefix.
## What each folder means → which one to read
Pick the folder by **intent**. Crucial: a bare `notes <project>` lists *every* status, and `search` spans *every* project + status — so neither answers "what's new". Both will surface long-done and ready items as if they were fresh. This is the #1 mistake: do not answer an "incoming" question from `search` or an unscoped `notes`.
| Folder | Meaning | Read it when the user asks… |
|--------|---------|------------------------------|
| `inbox` | New, untriaged — the **only** "new" surface | "newest bugs", "what's new", "what did my partner report", "any new feedback", "triage the inbox" → `notes <project> --status inbox` (or `triage <project>`) |
| `ready` | Triaged, accepted, waiting for work | "what's ready", "next task", "the backlog" → `notes <project> --status ready` |
| `done` | Merged / shipped — history only | "what shipped", "already fixed", "what's done" → `notes <project> --status done` |
| `docs` | Templates, briefing, specs — **never issues** | only when explicitly asked for a template/spec; never list these as bugs/issues |
**Default rule:** any request about *incoming / new / latest / unhandled / untriaged* items ⇒ scope to **`--status inbox`**. Only widen to `ready`/`done`, or fall back to `search`, when the user *explicitly* asks for those statuses or for an across-everything lookup. When unsure which folder the user means, ask — don't silently pull from all of them.
## Quick start
```bash
S=/path/to/apple-notes/scripts/apple-notes
"$S" init ProjektA # creates inbox/ready/done/docs + seeds templates+cheatsheet
"$S" resolve # auto-map current repo to project (cached)
"$S" notes "$($S resolve)" # list, grouped by status
"$S" triage ProjektA # inbox health check (prefix + metadata)
"$S" get ProjektA "BUG: Login flaky" # plain-text body
"$S" images ProjektA "BUG: Login flaky" # extract base64 images → JSON paths
```
## Subcommands
| | |
|---|---|
| `init <project>` | Creates the four status folders and seeds `docs/` with five issue templates (`VORLAGE BUG/FEAT/IDEA/FB/TECH`) + an `Anleitung`-cheatsheet for non-technical collaborators. Idempotent; existing notes are never overwritten. `--no-docs` skips the templates. `init --explain` prints the convention. |
| `projects [--json]` | Lists app subfolders of the company folder with note counts. |
| `resolve [REPO]` | Maps a repo name (default: current git toplevel) to a project. Cached at `~/.config/claude/apple-notes/mapping.json`. |
| `notes <project> [--status S] [--limit N] [--preview N] [--json]` | Lists notes; default groups by status. |
| `get <project> <title> [--format text\|html\|raw]` | Reads a note; auto-locates across all status folders. `<title>` may be the exact name, a truncated/ellipsis title as listed, a prefix, or a raw note `id`. Default `text` strips base64 → `[image:N]`. |
| `images <project> <title> [--out DIR]` | Extracts inline base64 images to `~/.cache/claude/apple-notes/images/<slug>/` (dirs `0700`, files `0600`) and prints JSON `[{path,bytes,mime}]`. `--out` overrides the directory. |
| `search <query> [--project NAME] [--json]` | Full-text across all projects + statuses. |
| `create <project> <title> [--status S] [--body-file F]` | Body on stdin or `--body-file`. Default status: `inbox`. |
| `update <project> <title>` / `append <project> <title>` | Replace / append. Auto-locates the note; status stays. |
| `delete <project> <title> --force` | Moves to "Recently Deleted" (recoverable for 30 days). |
| `move <project> <title> <new-status>` | Status transition: `apple-notes move ProjektA "BUG: …" ready`. |
| `triage <project> [--json]` | Inbox health: per-note score (✓ / ⚠) based on whether the title carries one of the configured prefixes (`BUG:` / `FEAT:` / `IDEA:` / `FB:` / `TECH:`). Body content is no longer scored. |
| `config show \| set <k> <v> \| set-mapping <repo> <project>` | Read/write config + manual repo→project overrides. |
## Token-efficiency rules
1. Default `get` format is `text` — base64 images are placeholders, not the LLM payload.
2. `notes` lists `title + date + 80-char preview`, grouped by status.
3. For screenshots: `images <project> <title>` → temp paths → `Read` each path (multimodal). Never paste raw base64.
4. `search` returns the most recent match first; use `--project NAME` to scope.
## Workflows
**Verify every write.** `move`, `create`, `update`, and `init` print `OK` or `ERR:…`. After any write, check that line — on `ERR:` surface it and do **not** report success. For `move`, confirm by re-listing: `apple-notes notes <project> --status <new-status>` must now include the note. Never claim a note was moved/created/updated without seeing it land.
**Pull issues from a partner-maintained inbox**
1. `apple-notes triage <project>` — see which inbox notes are well-formed.
2. `apple-notes notes <project> --status inbox` — full list.
3. `apple-notes get <project> <title>` for content; `apple-notes images …` for screenshots.
4. Present your assessment and propose `apple-notes move <project> <title> ready` (acknowledge, will fix) or `delete --force` (won't fix). Wait for explicit user confirmation before running `delete --force` — deletion is destructive and the agent must not decide it autonomously.
5. After implementation: `apple-notes move <project> <title> done`.
**Always close the loop on processed inbox notes (standing reminder rule)**
Whenever you have *acted on* one or more `inbox` notes in a turn — triaged them, diagnosed them, turned them into a plan/PRD, or fixed them — you MUST end that turn by **offering to move those specific notes to `ready`** (acknowledged / will-fix). List the affected note titles and ask explicitly, e.g. "Soll ich diese N Notizen nach `ready` verschieben?".
- This is a standing reminder that fires on **every** such turn, not a one-off.
- **Never move them autonomously.** Always wait for explicit confirmation — the user may have only partly processed a note, or may want to revisit it later.
- `ready` = "acknowledged, will fix". Reserve `done` for after the work ships, and `delete --force` (still confirmation-gated) for "won't fix".
- If the user declines or stays silent, leave the notes in `inbox` and simply re-offer the next time they are processed.
**Onboarding a new project**
1. Create the project subfolder manually in Apple Notes UI (e.g. `Projekt-B`).
2. `apple-notes init Projekt-B` — folders + templates land.
3. Share the `Anleitung: Bugs und Feedback einbringen` note (in `docs/`) with the human collaborator.
## Setup
First run creates `~/.config/claude/apple-notes/config.json` with defaults:
```json
{
"account": "iCloud",
"company_folder": "Firma",
"statuses": ["inbox", "ready", "done", "docs"],
"default_status": "inbox",
"default_image_dir": "~/.cache/claude/apple-notes/images"
}
```
Change with `apple-notes config set <key> <value>`. Pre-existing configs are gently migrated on every run.
Extracted images are private but are not cleaned up automatically. Remove them when no longer needed:
`rm -rf ~/.cache/claude/apple-notes/images`. Configs written by older versions may still point to `/tmp/apple-notes-images`;
change that with `apple-notes config set default_image_dir ~/.cache/claude/apple-notes/images`.
## macOS permissions
Claude Code's host terminal must have **Automation → Notes** enabled in `System Settings → Privacy & Security`. First invocation triggers the prompt; if denied earlier, toggle it back.
## Long titles & truncation
Apple Notes has no separate title field — a note's title **is** its first body line, truncated to ~64 chars + `…` once it gets long. So when a collaborator dumps the whole report into the first line (no line break), the listed title is a truncated ellipsis form while the full text lives in the body.
This is handled transparently: `get`/`update`/`append`/`move`/`delete` resolve a `<title>` that is exact, **truncated**, a prefix, ASCII-`...`, or a raw **note `id`**. For bulletproof addressing across several operations, take the `id` from `notes --json` / `search --json` and pass it as `<title>`. If two notes collide on a prefix, the command aborts as `ambiguous` and asks for the id.
To *prevent* the problem at the source, the seeded `Anleitung`/templates ask collaborators to keep the first line a short title and put detail in the lines below.
## Limitations
- **Inline base64 only**: only images that Apple Notes stored inline are extractable. Video, audio, PDFs, and richly-linked attachments are flagged in the note body (often as ``) but not retrievable via AppleScript.
- **Duplicate / prefix-colliding titles**: when a title query ties across notes, the command aborts as ambiguous — disambiguate with the note `id` (from `--json`) or rename in Apple Notes.
- **Status set is configurable** but enforced by `init` + `move`. Adding a new status: edit `config.json` `statuses` array and re-run `init`.
See [REFERENCE.md](REFERENCE.md) for AppleScript caveats, exit codes, and full subcommand contracts.
Files in this package (5)
- REFERENCE.md 10 KB
- SKILL.md 10 KB
- applescripts/create_note.applescript 1 KB
- scripts/_helper.py 7 KB
- scripts/apple-notes 38 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · silvio-l/skills | 100 | MIT |
| sweetrb/apple-notes-mcp | 100 | MIT |
| sweetrb/apple-notes-mcp | 100 | MIT |
| AceDataCloud/Skills | 100 | Apache-2.0 |
| cowork-os/cowork-os | 100 | MIT |
| microclaw/microclaw | 100 | MIT |
| foxrun-ai/foxrun | 100 | MIT |
| grtninja/skill-arbiter | 90 | MIT |
| craftos-dev/craftbot | 86 | MIT |
Database snapshot: 13.11.2026 · package version 6a852a4e4f5b (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100apple-notes-search
Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server. Use when the user wants to find, recall, or synthesize something from their notes, or surface non-obvious bridges/related notes. macOS, on-device. - 100apple-notes-search
Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server. Use when the user wants to find, recall, or synthesize something from their notes, or surface non-obvious bridges/related notes. macOS, on-device. - 100apple-notes-search
Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server. Use when the user wants to find, recall, or synthesize something from their notes, or surface non-obvious bridges/related notes. macOS, on-device. - 100apple-notes-to-obsidian
Put the user's Apple Notes into an Obsidian vault as Markdown and keep them in sync, using the Exporter Mac app and its exporter command line. Use when asked to move, import, migrate or sync Apple Notes to Obsidian, open Apple Notes in Obsidian, or keep an Obsidian copy of Apple… - 90export-apple-notes
Export the user's Apple Notes to Markdown (or HTML) files on a Mac with the Exporter Mac app and its exporter command line. Use when asked to export Apple Notes, convert notes to markdown or .md files, get notes out of Apple Notes, or save notes as HTML. macOS only. - 100notes-management
Guide for effective use of che-apple-notes-mcp for macOS Apple Notes management. Use when user asks about Apple Notes, 備忘錄, note taking on Mac, creating/searching/organizing notes.