zhongwei/gh-g-shudy-claude-plugins-plugins-macos-apple-apps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:27:54 +08:00
commit d89fa2b5a9
6 changed files with 872 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "macos-apple-apps",
"description": "Claude Code integration with macOS Apple productivity apps (Calendar, Contacts, Mail, Messages, Reminders, Health, Fitness, Shortcuts)",
"version": "0.1.0",
"author": {
"name": "g-shudy",
"url": "https://ghsj.me"
},
"skills": [
"./skills"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# macos-apple-apps
Claude Code integration with macOS Apple productivity apps (Calendar, Contacts, Mail, Messages, Reminders, Health, Fitness, Shortcuts)

53
plugin.lock.json Normal file
View File

@@ -0,0 +1,53 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:g-shudy/claude-plugins:plugins/macos-apple-apps",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "0360f2f74e1185d8dc3eb2f99f01686f34d265f0",
"treeHash": "b40669b2442007fc59d1cf865ca2a8fa1b0f497909a3e282e9f0a63f7af00035",
"generatedAt": "2025-11-28T10:16:57.366676Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "macos-apple-apps",
"description": "Claude Code integration with macOS Apple productivity apps (Calendar, Contacts, Mail, Messages, Reminders, Health, Fitness, Shortcuts)",
"version": "0.1.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "4bc118cda6a48d37670277c1a7b81c41b1479b3751eb857a47f4d0c393eb9722"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "c34d9c2cf5e37a36959e4551fc719da5fe72d97c3388ae24e1d7f075440a4b50"
},
{
"path": "skills/apple-health-fitness/SKILL.md",
"sha256": "585146bdb9db5edb7e9ae9816d5f15a67e3df740e5f97581fe7e2d26315b6fc7"
},
{
"path": "skills/apple-productivity/SKILL.md",
"sha256": "bc4476a779ae569b64a8014c3c04a9014a85b7a592eabaef45d9841f4f401a3b"
},
{
"path": "skills/apple-shortcuts/SKILL.md",
"sha256": "79475645d2cf0fe981172f544d2116cc0c63d7a7bec4bb84b04e4a2b79c03485"
}
],
"dirSha256": "b40669b2442007fc59d1cf865ca2a8fa1b0f497909a3e282e9f0a63f7af00035"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

232
skills/apple-health-fitness/SKILL.md Normal file
View File

@@ -0,0 +1,232 @@
---
name: apple-health-fitness
description: Query Health and Fitness data from Apple Health app including activity, workouts, heart rate, sleep, and health metrics. Use when user asks about health stats, fitness activity, workouts, sleep data, or health metrics.
allowed-tools:
- Bash
- Read
- Write
---
# Apple Health & Fitness Skill
Access Health and Fitness data from Apple Health app.
## Status
⚠️ **UNDER DEVELOPMENT**
The Apple Health app does not have a robust AppleScript dictionary. Health and Fitness data access requires:
1. **Export from Health app** - Manual or via `healthexport` CLI tool
2. **Parse XML/CSV** - Health data is exported as XML or CSV files
3. **Query exported data** - Use standard tools to analyze exports
## Planned Implementation
### Method 1: healthexport CLI Tool
[healthexport](https://github.com/mgile/healthexport) is a community tool for exporting Apple Health data:
```bash
# Install healthexport
pip3 install healthexport
# Export all health data
healthexport ~/health-export/
# Export specific data types
healthexport --data-type StepCount ~/health-export/
healthexport --data-type HeartRate ~/health-export/
```
**Output**: CSV files with timestamps and values
### Method 2: Health.app Export
Manual export via Health app:
1. Open Health app
2. Profile → Export All Health Data
3. Generates `export.xml` file
4. Parse XML with standard tools
### Method 3: HealthKit Framework (Advanced)
Use Swift CLI tool with HealthKit framework:
- Requires Xcode and Swift development
- More powerful but complex setup
- Can query live data without export
## Planned Helper Scripts
### health-export
Export health data for specific timeframe and metrics:
```bash
health-export --days 7 --type steps,heart-rate ~/health-export/
```
### health-query
Query exported health data:
```bash
health-query ~/health-export/ --metric steps --days 7 --summary
health-query ~/health-export/ --metric heart-rate --date 2025-11-15
```
### fitness-summary
Activity and workout summaries:
```bash
fitness-summary --week # This week's activity
fitness-summary --month # This month's summary
fitness-summary --workouts 5 # Last 5 workouts
```
## Data Types Available
### Activity
- Steps
- Flights climbed
- Distance walked/run
- Active energy burned
- Exercise minutes
### Workouts
- Workout type
- Duration
- Distance (for running/walking/cycling)
- Calories burned
- Heart rate during workout
### Heart Rate
- Resting heart rate
- Walking heart rate
- Heart rate variability
- Heart rate during exercise
### Sleep
- Sleep duration
- Time asleep vs. time in bed
- Sleep stages (if available)
### Body Measurements
- Weight
- Height
- Body mass index (BMI)
- Body fat percentage
### Vitals
- Blood pressure
- Blood glucose
- Blood oxygen
- Respiratory rate
## Privacy & Security
Health data is **HIGHLY SENSITIVE**. This skill will be:
- **READ-ONLY** - No writing to Health app
- **EXPLICIT CONSENT** - Always ask before accessing health data
- **AGGREGATED DATA ONLY** - Summaries and trends, not raw detailed records
- **NO SHARING** - Health data never sent to external services
## Roadmap
### Phase 1: Export & Basic Queries (In Progress)
- [ ] Install and test `healthexport` tool
- [ ] Create helper scripts for common queries
- [ ] Document export process
- [ ] Test with actual Health app data
### Phase 2: Common Use Cases
- [ ] Weekly activity summaries
- [ ] Workout tracking and analysis
- [ ] Sleep pattern analysis
- [ ] Heart rate trend monitoring
- [ ] Weight tracking
### Phase 3: Advanced Features
- [ ] Live data queries (HealthKit framework)
- [ ] Trend analysis and insights
- [ ] Goal tracking
- [ ] Health correlations
- [ ] Export automation
## Examples (Planned)
### User: "How many steps did I take this week?"
```bash
health-query ~/health-export/ --metric steps --days 7 --summary
```
Response: "You took 45,234 steps this week, averaging 6,462 steps per day."
### User: "Show my recent workouts"
```bash
fitness-summary --workouts 5
```
Response:
- Nov 11: Running, 3.2 miles, 32 minutes
- Nov 9: Cycling, 10 miles, 45 minutes
- Nov 8: Strength training, 40 minutes
- Nov 6: Running, 5K, 28 minutes
- Nov 5: Walking, 2 miles, 35 minutes
### User: "What was my average heart rate yesterday?"
```bash
health-query ~/health-export/ --metric heart-rate --date 2025-11-14 --average
```
Response: "Your average heart rate yesterday was 72 bpm (resting: 65, max: 145)."
## Development Notes
### Testing Requirements
- Real Health app data with multiple data types
- Multiple export formats (XML, CSV)
- Various date ranges and queries
- Privacy-preserving aggregation
### Dependencies
- Python 3.x (for healthexport)
- SQLite (for local data cache)
- jq (for JSON parsing)
### Alternative: Fitness.app
Fitness.app has better AppleScript support than Health.app for Activity Ring data:
```applescript
tell application "Fitness"
-- Query activity rings
-- (Limited to current day only)
end tell
```
May be useful for real-time "close your rings" type queries.
## Status Updates
**2025-11-12**: Initial skill created, implementation in progress.
**Next**: Install and test `healthexport`, create first helper scripts.
## Related Skills
- `apple-productivity` - Calendar, Contacts, Mail, Messages, Reminders
- `apple-shortcuts` - Run macOS Shortcuts (could trigger Health exports)
---
**Current Status**: This skill is a placeholder for future development. Health data access is complex due to privacy restrictions and lack of direct API access. Implementation will proceed carefully with security and privacy as top priorities.

309
skills/apple-productivity/SKILL.md Normal file
View File

@@ -0,0 +1,309 @@
---
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.

263
skills/apple-shortcuts/SKILL.md Normal file
View File

@@ -0,0 +1,263 @@
---
name: apple-shortcuts
description: Run user-defined macOS Shortcuts for custom automation workflows. Use when user wants to trigger a Shortcut by name or execute a custom automation.
allowed-tools:
- Bash
- AskUserQuestion
---
# Apple Shortcuts Skill
Run user-defined macOS Shortcuts through Claude Code.
## Overview
macOS includes the Shortcuts app for creating custom automation workflows. This skill allows Claude to trigger those Shortcuts via the `shortcuts` command-line tool.
## The `shortcuts` Command
macOS provides a built-in CLI tool for running Shortcuts:
```bash
# List all available shortcuts
shortcuts list
# Run a shortcut by name
shortcuts run "Shortcut Name"
# Run with input
shortcuts run "Shortcut Name" --input-path /path/to/file
# Get shortcut details
shortcuts view "Shortcut Name"
# Sign shortcuts for automation (one-time setup)
shortcuts sign --mode people-who-know-me "Shortcut Name"
```
## Usage Pattern
### 1. List Available Shortcuts
```bash
shortcuts list
```
This shows all Shortcuts the user has created. Present this list to the user if they ask "What shortcuts do I have?"
### 2. Run a Shortcut (REQUIRES USER CONFIRMATION)
**Always ask user before running a shortcut** using `AskUserQuestion` tool.
```bash
shortcuts run "Morning Routine"
```
### 3. View Shortcut Details
```bash
shortcuts view "Backup Photos"
```
Shows what the shortcut does (if the user wants to verify before running).
## Common Use Cases
### User: "What shortcuts do I have?"
```bash
shortcuts list
```
Present the list formatted nicely.
### User: "Run my morning routine shortcut"
1. **First**, list shortcuts to find exact name:
```bash
shortcuts list
```
2. **Then**, ask user for confirmation:
"I found the shortcut 'Morning Routine'. This shortcut will:
- [describe what it does if possible]
Should I run it?"
3. **If confirmed**, run it:
```bash
shortcuts run "Morning Routine"
```
### User: "Create a shortcut to..."
**Response**: "I can't create Shortcuts directly. You'll need to create it in the Shortcuts app, then I can run it for you. Would you like me to explain how to create it?"
## Security & Privacy
### ALWAYS REQUIRE CONFIRMATION
Shortcuts can do **anything** - file operations, network requests, app automation, etc.
**Rule**: NEVER run a shortcut without explicit user confirmation.
### What to Ask Before Running
1. "Which shortcut do you want to run?" (verify exact name)
2. Show what it does (if possible via `shortcuts view`)
3. "Should I run this now?"
### Signing Shortcuts
Some shortcuts may need to be signed for automation:
```bash
shortcuts sign --mode people-who-know-me "Shortcut Name"
```
If a shortcut fails with a signing error, tell the user:
"This shortcut needs to be signed for automation. Run this in Terminal:
`shortcuts sign --mode people-who-know-me \"Shortcut Name\"`"
## Examples
### Example 1: Morning Routine
User has a "Morning Routine" shortcut that:
- Sets Focus mode
- Adjusts display brightness
- Opens specific apps
- Reads calendar
```bash
shortcuts run "Morning Routine"
```
### Example 2: Export Photos
User has "Export Photos" shortcut that exports recent photos to a folder:
```bash
shortcuts run "Export Photos"
```
May require input path:
```bash
shortcuts run "Export Photos" --input-path ~/Desktop/
```
### Example 3: Backup Workflow
User has "Backup to NAS" shortcut:
```bash
shortcuts run "Backup to NAS"
```
## Integration with Other Skills
Shortcuts can complement other Apple app integrations:
### Calendar → Shortcuts
- User creates Calendar event via `apple-productivity` skill
- Then triggers "Sync Calendar" shortcut to sync with external service
### Health → Shortcuts
- Trigger "Export Health Data" shortcut
- Then query exported data with `apple-health-fitness` skill
### Contacts → Shortcuts
- Lookup contact with `apple-productivity` skill
- Trigger "Send Birthday Reminder" shortcut for that contact
## Limitations
### Cannot Create Shortcuts
Claude cannot create or modify Shortcuts - only run existing ones. Shortcuts must be created by the user in the Shortcuts app.
### No Direct Shortcut Editing
Cannot view internal structure of shortcuts (they're binary files). Can only run them.
### Shortcut Permissions
Shortcuts may require permissions (Automation, Files, etc.). User must grant these in System Settings.
### Input/Output
- Simple text input/output works well
- File input via `--input-path`
- Complex data structures may be tricky
## Shortcut Ideas for Users
Suggest these shortcuts users could create:
### Productivity
- Morning/Evening routines
- Focus mode triggers
- Calendar sync workflows
- Email templates
### File Management
- Backup workflows
- Photo organization
- Document conversion
- File compression/archiving
### Health & Fitness
- Export health data
- Log workouts
- Meal tracking
- Sleep analysis
### Communication
- Send templated messages
- Email batches
- Social media posts
- Contact management
### Development
- Git workflows
- Build/deploy automation
- Test runners
- Environment setup
## Troubleshooting
### "Shortcut not found"
```bash
shortcuts list
```
Get exact name (case-sensitive, spaces matter).
### "Signing error"
```bash
shortcuts sign --mode people-who-know-me "Shortcut Name"
```
Or tell user to open Shortcuts app → Settings → Advanced → Allow Running Scripts
### "Permission denied"
Shortcut needs permissions. User must grant in:
System Settings → Privacy & Security → Automation
## Resources
- **Shortcuts User Guide**: https://support.apple.com/guide/shortcuts-mac/
- **Command-line Tool**: Run `man shortcuts` for details
- **Gallery**: Open Shortcuts app → Gallery for inspiration
## Related Skills
- `apple-productivity` - Calendar, Contacts, Mail, Messages, Reminders
- `apple-health-fitness` - Health and Fitness data
---
**Remember**: Shortcuts are powerful and potentially destructive. ALWAYS confirm with user before running any shortcut.