Claude Apple Bridges

Claude Apple Bridges

Swift CLI tools that give Claude Code native access to Apple apps — Reminders, Calendar, Contacts, Notes, Mail, and tmux. Includes a [Claude Code skill](#skills) (/apple-bridges) with complete command reference for all bridges.

Usage Examples with Claude Code

Once set up, you can ask Claude naturally in any Claude Code session. Here are real-world examples:

---

Task & Project Management

> "What's on my todo list for today?"

Claude checks your Reminders and summarizes open items with due dates and priorities.

> "I just finished the login bug fix — mark the GitHub issue and the reminder as done."

Claude closes the GitHub issue and calls reminders-bridge complete in one step.

> "Add a reminder to my 'Work' list to review the PR tomorrow morning."

Claude creates the reminder with a due date set to tomorrow at 9:00.

---

Calendar-Aware Scheduling

> "I want to work on the Android release tomorrow — find a free slot and set a reminder."

Claude checks calendar-bridge tomorrow, finds a free window, and sets the reminder due date accordingly — no double-booking.

> "What do I have going on this week? Block some time for code review."

Claude reads your calendar for each day, spots gaps, and adds events or reminders where they fit.

> "Schedule our next planning session for next Monday at 10am in my Work calendar."

Claude calls calendar-bridge add directly without you having to open Calendar.

---

Contacts Lookup

> "What's Rob's phone number?"

Claude searches your Contacts and returns the number directly — no need to open the Contacts app.

> "Add Alex to my contacts: +49 123 456789, alex@example.com"

Claude calls contacts-bridge add and confirms once saved.

> "Show me all details for my contact Thomas."

Claude returns name, phone, email, address and birthday in one view.

---

Development Workflow Integration

> "Start working on issue #42 — create a reminder to track it and add the 'in progress' label."

Claude adds a GitHub label, creates a Reminders entry with the issue number in the notes, and sets a due date.

> "We finished the feature — close the issue, complete the reminder, and write the release note."

Claude handles all three in one go.

> "What are my open todos related to this project?"

Claude reads your Reminders list and cross-references with open GitHub issues for a full picture.

---

End-of-Day / Planning

> "Summarize what we did today and create reminders for anything we didn't finish."

Claude reviews the session, identifies incomplete work, and adds follow-up reminders with appropriate due dates.

> "Set reminders for all open todos so they show up in my Calendar tomorrow after my meetings."

Claude reads tomorrow's calendar first to avoid conflicts, then sets due times in the free slots.

---

Bridges

reminders-bridge

Access and manage Apple Reminders from Claude Code.

reminders-bridge lists                                   List all reminder lists
reminders-bridge create-list                       Create a new list
reminders-bridge rename-list                   Rename an existing list
reminders-bridge delete-list                       Delete a list (and all its reminders)
reminders-bridge items                             Show all reminders in a list
reminders-bridge incomplete                        Show only incomplete reminders
reminders-bridge today                                   Show reminders due today (all lists)
reminders-bridge overdue                                 Show all overdue reminders (all lists)
reminders-bridge search                           Search by title/notes across all lists
reminders-bridge add   [notes]              Add a new reminder
reminders-bridge set-due          Set due date (YYYY-MM-DD HH:mm)
reminders-bridge set-notes           Set or update notes
reminders-bridge rename        Rename a reminder (title only, preserves notes/due)
reminders-bridge complete                   Mark a reminder as complete
reminders-bridge delete   [--force]         Delete a reminder (dry-run without --force)

calendar-bridge

Read and write Apple Calendar events from Claude Code.

calendar-bridge calendars                                     List all calendars
calendar-bridge today                                         Show today's events
calendar-bridge tomorrow                                      Show tomorrow's events
calendar-bridge week                                          Show this week's events
calendar-bridge events                            Show events for a date
calendar-bridge free-slots                        Show free time slots (08:00–20:00)
calendar-bridge search                                 Search events by title (next 365 days)
calendar-bridge add                   Add event (YYYY-MM-DD HH:mm)
calendar-bridge add-all-day           Add all-day event
calendar-bridge delete    [--force]   Delete event (dry-run without --force)

contacts-bridge

Search and manage Apple Contacts from Claude Code.

contacts-bridge search                                 Search by name, email or phone
contacts-bridge show                                    Show full details for a contact
contacts-bridge add   [phone] [email]    Add a new contact
contacts-bridge update  phone  [label]           Add a phone (append, keeps existing)
contacts-bridge update  email  [label]           Add an email (append, keeps existing)
contacts-bridge remove  phone|email              Remove a matching phone/email
contacts-bridge delete  [--force]                       Delete a contact (dry-run without --force)
contacts-bridge birthdays-today                               Contacts with birthday today
contacts-bridge birthdays-upcoming                      Upcoming birthdays in next N days

notes-bridge

Read and write Apple Notes from Claude Code.

notes-bridge accounts                                         List all accounts
notes-bridge folders [account]                                List folders (default: iCloud)
notes-bridge list [folder] [account]                          List notes with modification date
notes-bridge search                                    Search by title and content across all accounts
notes-bridge read  [account]                           Read note content as plain text
notes-bridge add    [account]            Create a new note
notes-bridge append   [account]                  Append text to an existing note
notes-bridge delete  [--force] [account]               Delete a note (dry-run without --force)

Formatting: The body and text parameters support HTML — Notes.app renders it natively.

# Plain text note
notes-bridge add "Ideas" "Shopping" "Milk, Bread, Eggs"

# Rich note with HTML formatting
notes-bridge add "Work" "Meeting Notes" "Attendees: Tobias, HeikoDiscussed Q1 roadmapNext steps: review PR"

# Append a formatted section
notes-bridge append "Meeting Notes" "Follow-up:Send report by Friday"

Supported HTML tags: `, , , , , , , –, , `

mail-bridge

Read and send Apple Mail messages from Claude Code.

mail-bridge accounts                                                           List all email accounts
mail-bridge mailboxes [account]                                                List mailboxes (default: first account)
mail-bridge list [mailbox|account] [account] [count]                           List recent messages (auto-detects account names)
mail-bridge unread [mailbox|account] [account] [--all] [--max N] [--since X]   List unread — fast (server-side filter); --all = every account
mail-bridge search  [max_results] [account] [--unread] [--since X]      Search subject/sender — output includes  for each hit
mail-bridge read  [mailbox] [account]                                   Read message (unread status preserved)
mail-bridge read  [mailbox] [account] --mark-read                       Read message and mark as read
mail-bridge read  [mailbox] [account] --raw                             Read raw RFC822 source (HTML + MIME attachments)
mail-bridge read --mid  [account] [--mark-read] [--raw]            Read by RFC822 message-id (no listing needed) — fetches full body
mail-bridge send    [/attachment] [--from ]          Opens compose window — user reviews and sends manually
mail-bridge send    [/attachment] [--from ] --force  Sends directly without UI
mail-bridge delete  [mailbox] [account] [--force]                       Move to Trash (dry-run without --force)

--since accepts Nd / Nw / Nm (days/weeks/months), a bare integer (days), or YYYY-MM-DD.

Unread / search performance: both commands push the filter into Mail.app via a whose clause, so Mail scans the mailbox internally instead of the bridge fetching every message's properties over IPC. On a 50k-message INBOX the old behaviour took minutes; the filtered variant returns in ~1s per account. Use --since 7d to narrow further on servers that index slowly.

# All unread across every account, last 7 days, cap at 20
mail-bridge unread --all --since 7d --max 20

# Only unread results when searching
mail-bridge search "invoice" --unread --since 30d

--mid example — fetch a specific message without knowing its INBOX index:

search now prints an ` token for every hit (RFC822 Message-ID). Pass it to read --mid to fetch the full message directly — no expensive list` walk required, and Mail.app downloads the body if it was only partially cached.

mail-bridge search "invoice" 50 work@company.com --since 90d
# Found 7 message(s) (last 90d):
#    Invoice #4711 — billing@vendor.com (3/15)
#   ...

mail-bridge read --mid "abc123@example.com" work@company.com --raw > /tmp/mail.eml

--raw example — extract PDF attachments from invoice emails:

# Dump the raw message source (RFC822, includes HTML body + MIME attachments)
mail-bridge read 42 INBOX work@company.com --raw > /tmp/mail.eml

# Then parse with Python to save any PDF attachment
python3  [lines]                 Read pane content (e.g. main:1.1, default: 1000 lines)
tmux-bridge write   [--no-enter]    Send keystrokes to a pane
tmux-bridge snapshot [session] [lines]            Capture all panes at once (default: 5000 lines)

Write examples:

# Send a command (text + Enter)
tmux-bridge write main:0.0 "ls -la"

# Send text without pressing Enter
tmux-bridge write main:0.0 "partial input" --no-enter

Typical workflow: run your work in named tmux sessions, then ask Claude at the end of the day: > "Read tmux-bridge snapshot and summarize what I worked on today."

---

Setup

1. Compile

# Install all bridges at once (recommended)
git clone https://github.com/more-io/claude-apple-bridges.git
cd claude-apple-bridges
make install

Optional: Persistent TCC permissions with a Developer certificate

By default, bridges are ad-hoc signed. macOS TCC may re-prompt for permissions in new terminal sessions (especially remote/SSH). If you have an Apple Developer certificate, pass CODESIGN_IDENTITY for persistent grants:

make install CODESIGN_IDENTITY="Apple Development: Your Name (TEAMID)"

Or install individually:

make install-reminders
make install-calendar
make install-contacts
make install-notes
make install-mail

Manual compile (without make)

# reminders-bridge
cat > /tmp/reminders-info.plist 

    NSRemindersFullAccessUsageDescription
    Claude Code needs access to Reminders to manage tasks.

EOF
swiftc reminders-bridge.swift -o ~/.claude/reminders-bridge \
  -framework EventKit \
  -Xlinker -sectcreate -Xlinker __TEXT -Xlinker __info_plist -Xlinker /tmp/reminders-info.plist
codesign --force --sign - --identifier com.claude.reminders-bridge ~/.claude/reminders-bridge

# contacts-bridge
cat > /tmp/contacts-info.plist 

    NSContactsUsageDescription
    Claude Code needs access to Contacts to look up and manage contacts.

EOF
swiftc contacts-bridge.swift -o ~/.claude/contacts-bridge \
  -framework Contacts \
  -Xlinker -sectcreate -Xlinker __TEXT -Xlinker __info_plist -Xlinker /tmp/contacts-info.plist
codesign --force --sign - --identifier com.claude.contacts-bridge ~/.claude/contacts-bridge

# calendar-bridge
cat > /tmp/calendar-info.plist 

    NSCalendarsFullAccessUsageDescription
    Claude Code needs access to Calendar to schedule and view events.

EOF
swiftc calendar-bridge.swift -o ~/.claude/calendar-bridge \
  -framework EventKit \
  -Xlinker -sectcreate -Xlinker __TEXT -Xlinker __info_plist -Xlinker /tmp/calendar-info.plist
codesign --force --sign - --identifier com.claude.calendar-bridge ~/.claude/calendar-bridge

# notes-bridge
swiftc notes-bridge.swift -o ~/.claude/notes-bridge
codesign --force --sign - --identifier com.claude.notes-bridge ~/.claude/notes-bridge

# mail-bridge
swiftc mail-bridge.swift -o ~/.claude/mail-bridge
codesign --force --sign - --identifier com.claude.mail-bridge ~/.claude/mail-bridge

2. Grant permissions

Run each binary once from Terminal to trigger the macOS permission dialog:

~/.claude/reminders-bridge lists
~/.claude/calendar-bridge today
~/.claude/contacts-bridge search "test"
~/.claude/notes-bridge accounts
~/.claude/mail-bridge accounts

Then approve in System Settings → Privacy & Security → Reminders / Calendars / Contacts / Automation. Notes and Mail access is granted automatically via AppleScript on first use.

3. Add to Claude Code allowed tools

Add the bridges to your global ~/.claude/settings.json so they work across all projects without confirmation prompts:

{
  "permissions": {
    "allow": [
      "Bash(~/.claude/reminders-bridge*)",
      "Bash(~/.claude/calendar-bridge*)",
      "Bash(~/.claude/contacts-bridge*)",
      "Bash(~/.claude/notes-bridge*)",
      "Bash(~/.claude/mail-bridge*)",
      "Bash(~/.claude/tmux-bridge*)"
    ]
  }
}

---

Requirements

• macOS 13+
• Swift (comes with Xcode or xcode-select --install)
• Claude Code

---

Testing

After installing, run the integration test suite to verify everything works:

make test

35 tests cover all commands across all three bridges — exit codes, output validation, and argument handling. No data is modified during tests.

---

Skills

Skills are structured prompt templates that Claude Code can load automatically when a bridge topic comes up. Instead of relying solely on CLAUDE.md for bridge documentation, the skill provides complete command syntax, parameters, and usage examples on demand.

What Skills Do

When you type /apple-bridges in Claude Code (or when Claude detects you're asking about Reminders, Calendar, Contacts, Notes, Mail, or tmux), the skill loads:

1. SKILL.md — Overview of all bridges with a quick reference table
2. Detail files — Full documentation per bridge, loaded only when needed

This keeps context usage minimal while giving Claude complete knowledge of every command.

Install Skills

Skills are included with make install:

make install          # Installs bridges AND skills
make install-skills   # Install skills only

This copies the skill files to ~/.claude/skills/apple-bridges/.

Manual Install

cp -r skills/apple-bridges ~/.claude/skills/

Verify

Start a new Claude Code session and type /apple-bridges — it should be available as a slash command.

---

Contributing

Pull requests are welcome! When adding a new bridge:

1. Create -bridge.swift in the repo root
2. Add compile instructions to README.md and CLAUDE.md
3. Add the permission grant step to README.md
4. Add usage examples to README.md

See CLAUDE.md for developer notes and the branching workflow.

---

License

MIT — see [LICENSE](LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: more-io
• Source: more-io/claude-apple-bridges
• License: MIT
• Homepage: https://github.com/more-io/claude-apple-bridges

Install and usage instructions live in the source repository linked above.