# Osascript Apps

> osascript-apps

- Skill: `damionrashford/osascript-apps` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add damionrashford/osascript-apps`
- Raw SKILL.md: https://api.skillmd.com/api/skills/damionrashford/osascript-apps/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: damionrashford (https://skillmd.com/u/damionrashford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/damionrashford/osascript-apps

---


# osascript-apps

App scripting with confirmed-working patterns for Mail, Calendar, Finder, Notes, Reminders, and Spotlight.
All scripts are Python with AppleScript/JXA embedded as strings.

## App Capabilities

| App | API | What's accessible |
|-----|-----|-------------------|
| Mail | AppleScript dictionary | Inbox, search, attachments, accounts, all message properties |
| Calendar | AppleScript (surface) | Title, dates, location, status |
| Calendar | EventKit ObjC (full depth) | + Attendees, organizer, recurrence, alarms |
| Finder | AppleScript dictionary | Disk volumes, file metadata, desktop contents |
| Spotlight | `mdfind` via shell | Full-text search, metadata queries across indexed files |
| Notes | AppleScript dictionary | Note titles, body, creation/modification dates |
| Reminders | AppleScript dictionary | Title, completed state, due date, list |
| Shortcuts | AppleScript (minimal) | Name, ID, action count only — content is opaque |

## Key Limitations

- **Shortcuts two-way return**: `run shortcut` returns `missing value` unless shortcut has `accepts input: true` AND ends with "Stop and Output" action.
- **EventKit vs AppleScript**: Use EventKit ObjC for attendees, recurrence, alarms — AppleScript doesn't expose these.
- **mdfind empty results**: Returns empty for directories with `unknown indexing state`. Check with `mdutil -s /path`.
- **Mail TCC**: Mail has its own TCC category — not `kTCCServiceAddressBook`. First use may prompt.

## Scripts

Read recent Mail inbox messages with full properties:
```bash
uv run scripts/mail-read.py
uv run scripts/mail-read.py 20
```

Search Mail inbox by subject or sender keyword:
```bash
uv run scripts/mail-search.py "invoice"
uv run scripts/mail-search.py "from:boss@example.com"
```

Today's (or next N days') calendar events via EventKit ObjC — includes attendees:
```bash
uv run scripts/calendar-today.py
uv run scripts/calendar-today.py 7
```

Search files by name, content, kind, or date via `mdfind`:
```bash
uv run scripts/spotlight-search.py "budget 2024"
uv run scripts/spotlight-search.py "kind:pdf date:today"
```

Disk volumes with capacity/free space, or metadata for a specific path:
```bash
uv run scripts/finder-info.py
uv run scripts/finder-info.py ~/Documents/report.pdf
```

Read recent Apple Notes titles and dates — `--filter` by title keyword:
```bash
uv run scripts/notes-read.py
uv run scripts/notes-read.py 20 "meeting"
```

Read incomplete (or all) reminders from default list or a named list:
```bash
uv run scripts/reminders-read.py
uv run scripts/reminders-read.py --all
uv run scripts/reminders-read.py --list "Groceries"
```

## Reference

- [reference/16-mail-scripting.md](reference/16-mail-scripting.md) — Mail inbox, search, attachments, accounts, full message properties
- [reference/17-calendar-eventkit.md](reference/17-calendar-eventkit.md) — AppleScript vs EventKit comparison, attendees, recurring rules
- [reference/10-spotlight.md](reference/10-spotlight.md) — mdfind CLI, MDQuery ObjC, all metadata attributes
- [reference/12-app-dictionaries.md](reference/12-app-dictionaries.md) — Runtime introspection via `get properties`, Finder, Shortcuts limits
- [reference/13-error-handling.md](reference/13-error-handling.md) — safeExecute wrapper, common error codes (-1719, -1728, -1708)
- [reference/14-sandboxing.md](reference/14-sandboxing.md) — Allowed apps, blocked verbs, dry-run pattern, audit logging