imessage

iMessage Claude Assistant

A local-first macOS assistant that wires Apple iMessage into Claude Code through a local Model Context Protocol (MCP) channel plugin. Incoming messages surface inside a Claude Code session; outbound replies are drafted as three explicit options, reviewed by the operator, and only sent after approval. Approved replies are logged locally to train Claude on the operator's voice over time.

Everything — message reads, message sends, message history, and style learning — runs on the operator's own Mac. No hosted service, no cloud sync, no third-party relay.

---

Table of contents

1. Overview
2. Features
3. Project status
4. Attribution
5. Architecture
6. Repository structure
7. Requirements
8. Installation
9. Configuration
10. Running the assistant
11. Running as a background service
12. Access control and DM policy
13. Using the assistant from iPhone, iPad, and other devices
14. Security and privacy
15. Testing and verification
16. Troubleshooting
17. Development and maintenance notes
18. Links and references
19. License and disclaimer
20. Maintainer and contact

---

1. Overview

The assistant is structured as a Claude Code plugin that exposes an iMessage channel: a bidirectional conduit between Claude Code and the macOS Messages.app. The plugin reads Apple's local SQLite message store (~/Library/Messages/chat.db) for inbound traffic and drives Messages.app over AppleScript (osascript) for outbound traffic.

The core operator workflow is:

1. A conversation partner sends an iMessage.
2. The plugin detects the new row in chat.db and delivers it to the active Claude Code session.
3. Claude proposes three distinct reply options — safest, warmest, and most concise — per the rules in CLAUDE.md.
4. The operator explicitly approves, edits, or replaces a draft.
5. On approval, the plugin sends the message via Messages.app and appends the final text to a local, append-only style log.

The /imessage:review skill inverts that flow for catch-up scenarios: the operator asks Claude to review existing unanswered threads, and Claude walks them one at a time, always gating on explicit approval before sending.

---

2. Features

Messaging

• Inbound iMessage delivery into Claude Code sessions
• Outbound send via AppleScript (text + attachments)
• Full native message history via direct SQLite reads against chat.db
• Attachment pass-through: inbound images surface as local file paths
• Self-chat bypass for frictionless operator testing

Assistant workflow

• Three-option reply proposal flow (see CLAUDE.md)
• Explicit operator approval required for every outbound message
• On-demand thread review via the /imessage:review skill
• Approved-reply log and per-contact style notes for voice learning
• Permission relay: mirrors Claude Code permission prompts into a self-chat so the operator can approve from a phone

Access control

• Policy modes: allowlist (default), pairing, and disabled
• Per-handle allowlist and per-group enablement
• Runtime pairing flow with approval codes
• Hand-editable access.json plus a /imessage:access skill

Operations

• Local marketplace registration (no external install required)
• Single-file MCP server on Bun
• preflight.sh and doctor.sh operator diagnostics
• Structured JSON logging (optional)
• health_check MCP tool for live self-diagnostics
• Optional macOS LaunchAgent for login-persistent operation

---

3. Project status

Local personal fork. This repository is a local, customized implementation derived from the upstream Claude Code iMessage channel. It is tuned for daily operator use on a single Mac, and reflects opinionated choices around approval flow, style learning, and policy semantics that do not necessarily match the upstream.

Versioning follows the plugin's own version field in plugins/imessage/.claude-plugin/plugin.json; the current release is 0.2.0. See CHANGELOG.md.

---

4. Attribution

• Original source and design foundation: the official Claude Code iMessage channel plugin shipped by Anthropic, from which this project derives its chat.db reader, AppleScript sender, and MCP channel protocol scaffolding.
• Local adaptation, extension, and maintenance: Gabriel Chiappa.