---
name: apple-productivity
description: Access macOS Apple productivity apps (Calendar, Contacts, Mail, Messages, Reminders) to read events, contacts, messages, and tasks. Use this when user needs to check calendar, look up contacts, read messages/emails, or query reminders.
allowed-tools:
  - Bash
  - Read
  - Write
  - AskUserQuestion
---

# Apple Productivity Apps Skill

You have access to macOS native productivity apps through helper scripts installed in ~/bin/.

## Available Helper Scripts

### Calendar

**`calendar-list`** - List all available calendars
```bash
calendar-list
calendar-list -j  # JSON output
```

**`calendar-events`** - Query events
```bash
calendar-events                           # Today's events (default)
calendar-events -d 2025-11-15             # Specific date
calendar-events -w                        # This week
calendar-events -r 2025-11-15 2025-11-20  # Date range
calendar-events -c "Work"                 # Filter by calendar
calendar-events -j                        # JSON output
```

**`calendar-add`** - Add new event (REQUIRES USER CONFIRMATION)
```bash
calendar-add -t "Meeting" -s 2025-11-15T14:00:00 -e 2025-11-15T15:00:00
calendar-add -t "Lunch" -s 2025-11-15T12:00:00 -e 2025-11-15T13:00:00 -l "Cafe" -c "Personal"
```

**Important**: ISO-8601 format required: `YYYY-MM-DDTHH:MM:SS` (24-hour time)

### Contacts

**`contacts-search`** - Search contacts
```bash
contacts-search "Marie"          # Search by name
contacts-search -v "Brandon"     # Verbose (all details)
contacts-search -a               # List all contacts
contacts-search -l 5 "Smith"     # Limit to 5 results
contacts-search -j               # JSON output
```

Searches: First name, last name, email, phone, company (case-insensitive)

### Mail

**`mail-unread`** - Get unread mail (REQUIRES Mail.app RUNNING)
```bash
mail-unread              # Last 24 hours (default)
mail-unread 6            # Last 6 hours
mail-unread -d 3         # Last 3 days
mail-unread -l 5         # Limit to 5 messages
mail-unread -j           # JSON output
```

**Exit code 1** = Mail.app not running (tell user to open Mail.app)

### Messages

**`imessage-recent`** - Get recent iMessages (SQLite direct access)
```bash
imessage-recent              # Last 24 hours (default)
imessage-recent 6            # Last 6 hours
imessage-recent -d 3         # Last 3 days
imessage-recent -l 10        # Limit to 10 messages
imessage-recent -p "lunch"   # Filter by keyword
imessage-recent -n           # Check for notation patterns
imessage-recent -j           # JSON output
```

**Note**: Works even when Messages.app is NOT running (direct SQLite access)

**Notation patterns checked** (`-n` flag):
- `(ghsj→cc:`, `(ghsj:`, `(cc→ghsj:`, `(cc-suggest:`, `(cc-warn:`
- `>>move:`, `>>archive`, `>>defer:`
- `[MUST]`, `[SHOULD]`

**`imessage-search`** - Advanced iMessage search with full message history (SQLite + attributedBody decoding)
```bash
imessage-search --felicitations                 # Find birthday/holiday/congrats messages
imessage-search --pattern "lunch"               # Search for custom keyword
imessage-search --keywords "meeting,call"       # Multiple keywords (comma-separated)
imessage-search --felicitations -l 10           # Limit to 10 contacts
imessage-search --pattern "resume" --csv        # CSV output
imessage-search --felicitations -o ~/Desktop/contacts.csv  # Save to file
```

**Key Features**:
- Searches **complete message history** (not just recent messages)
- Decodes modern iMessage `attributedBody` BLOB format (binary plist)
- Groups results by contact with message counts and dates
- Auto-installs dependencies on first run (creates venv with biplist)
- Supports JSON, CSV, and human-readable output formats

**Use Cases**:
- Find contacts you've sent felicitation messages to (birthdays, holidays, congratulations)
- Search historical messages for specific keywords or topics
- Build contact lists for holiday greetings
- Analyze message patterns over time

**Note**: First run takes ~10s to setup virtual environment and install dependencies. Subsequent runs are fast.

### Reminders

**`reminders-list`** - Query reminders
```bash
reminders-list                        # Incomplete reminders (default)
reminders-list -a                     # All reminders
reminders-list -c                     # Only completed
reminders-list -d                     # Due today
reminders-list -o                     # Overdue
reminders-list -l "Work"              # Filter by list name
reminders-list -l "Work" -d           # Work reminders due today
reminders-list --limit 20             # Limit results
reminders-list -j                     # JSON output
```

**Warning**: Large queries can timeout (10s limit). Use `-l` to filter by specific list if needed.

## Common Patterns

### Morning Context Check

```bash
# Today's schedule
calendar-events --today

# Pending tasks
reminders-list -o  # Overdue
reminders-list -d  # Due today

# Unread communications
mail-unread
imessage-recent -n  # Check for notation patterns
```

### Contact Lookup

```bash
# Quick lookup
contacts-search "Marie"

# Full details
contacts-search -v "Brandon"

# Find someone by company
contacts-search "Best Buy"
```

### Message Search

```bash
# Recent messages about specific topic
imessage-recent -p "resume"

# Check for user directives
imessage-recent -n

# Historical search across all messages
imessage-search --pattern "resume"

# Find contacts for holiday greetings
imessage-search --felicitations --csv -o ~/Desktop/thanksgiving-contacts.csv
```

## Security & Privacy

### READ-ONLY (Safe - No Confirmation Needed)

- ✅ Viewing calendar events
- ✅ Looking up contacts
- ✅ Checking unread mail counts/subjects
- ✅ Reading recent iMessages (`imessage-recent`)
- ✅ Searching historical iMessages (`imessage-search`)
- ✅ Querying reminder status

### WRITE OPERATIONS (ALWAYS Ask User First)

- ❌ Creating/modifying calendar events (`calendar-add`)
- ❌ Creating/modifying contacts
- ❌ Sending emails
- ❌ Sending iMessages
- ❌ Creating/modifying reminders

**Rule**: ALWAYS use `AskUserQuestion` tool before ANY write operation.

## Error Handling

### Mail Not Running

```bash
$ mail-unread
Error: Mail.app not running
Please open Mail.app before running this command
# Exit code: 1
```

**Response**: Tell user to open Mail.app, then retry.

### Calendar Timeout

```bash
$ calendar-events -r 2020-01-01 2025-12-31
Error: Query timed out after 10s
Try a smaller date range or check if Calendar.app is responsive
# Exit code: 3
```

**Response**: Use smaller date range (days/weeks, not years).

### No Results

All scripts handle "no results" gracefully:
```bash
$ calendar-events
No events found for 2025-11-15
```

## Examples

### User: "What's on my calendar today?"

```bash
calendar-events --today
```

Parse output and summarize for user.

### User: "What's Brandon's phone number?"

```bash
contacts-search "Brandon"
```

Extract phone number from output.

### User: "Any unread emails from Marie?"

First check if Mail.app is running:
```bash
mail-unread -l 20
```

Then filter output for "Marie" in sender field.

### User: "Show my overdue reminders"

```bash
reminders-list -o
```

Present list to user with due dates.

### User: "When is Eileen's birthday?"

```bash
contacts-search -v "Eileen"
```

Look for "Birthday:" in verbose output.

### User: "Create a calendar event for lunch tomorrow at noon"

1. Calculate tomorrow's date
2. Format as ISO-8601: `2025-11-16T12:00:00`
3. **ASK USER FOR CONFIRMATION** using `AskUserQuestion`
4. If confirmed:
```bash
calendar-add -t "Lunch" -s 2025-11-16T12:00:00 -e 2025-11-16T13:00:00
```

## Limitations

- **Mail**: Requires Mail.app to be running
- **Calendar**: Large date ranges (years) may timeout - use smaller ranges
- **Reminders**: Large lists may timeout - filter by specific list
- **Messages**:
  - `imessage-recent`: Only searches messages with plain text field (~70 messages) - fast but limited
  - `imessage-search`: Searches complete history by decoding attributedBody BLOBs - comprehensive but slower
  - Sending messages requires user interaction (read-only access)
- **Contacts**: ~700 contacts can be slow to enumerate - use specific searches

## Tips

1. **Always check exit codes** - Non-zero = error
2. **Use JSON output** (`-j`) for complex parsing
3. **Limit results** when possible to avoid timeouts
4. **Filter early** - Use script options rather than parsing large outputs
5. **Batch operations** - Run multiple independent queries in parallel with multiple Bash tool calls

## Related Skills

- `apple-health-fitness` - Health and Fitness data
- `apple-shortcuts` - Run macOS Shortcuts

---

**Remember**: This skill gives you READ access to personal productivity data. ALWAYS ask before WRITING any data.