{"id":49952783,"url":"https://github.com/benelser/imessage-tools","last_synced_at":"2026-05-17T20:16:59.063Z","repository":{"id":348332449,"uuid":"1197340463","full_name":"benelser/imessage-tools","owner":"benelser","description":"Claude Code plugin for reading, searching, and sending iMessages","archived":false,"fork":false,"pushed_at":"2026-03-31T19:22:40.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T19:38:56.428Z","etag":null,"topics":["applescript","bun","claude-code","claude-code-plugin","imessage","macos"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benelser.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T14:02:31.000Z","updated_at":"2026-03-31T19:22:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/benelser/imessage-tools","commit_stats":null,"previous_names":["benelser/imessage-tools"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/benelser/imessage-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benelser%2Fimessage-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benelser%2Fimessage-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benelser%2Fimessage-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benelser%2Fimessage-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benelser","download_url":"https://codeload.github.com/benelser/imessage-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benelser%2Fimessage-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33153669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T09:28:26.183Z","status":"ssl_error","status_checked_at":"2026-05-17T09:27:52.702Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["applescript","bun","claude-code","claude-code-plugin","imessage","macos"],"created_at":"2026-05-17T20:16:53.910Z","updated_at":"2026-05-17T20:16:59.057Z","avatar_url":"https://github.com/benelser.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# imessage-tools\n\nA cross-platform iMessage plugin for [Claude Code](https://code.claude.com/docs/en/plugins) and [OpenAI Codex CLI](https://developers.openai.com/codex/plugins). Read, search, and send iMessages directly from your AI coding agent.\n\n## Prerequisites\n\n- **macOS** — iMessage is a macOS-only feature\n- **[Bun](https://bun.sh)** — JavaScript runtime (`brew install oven-sh/bun/bun`)\n- **Full Disk Access** — your terminal needs Full Disk Access in System Settings \u003e Privacy \u0026 Security to read `~/Library/Messages/chat.db` and `~/Library/Application Support/AddressBook/` (for resolving phone numbers to contact names)\n\n## Install\n\nCurrent release: **v3.0.0**\n\n### Claude Code\n\n```\n/plugin marketplace add benelser/imessage-tools\n/plugin install imessage-tools@benelser-imessage-tools\n/reload-plugins\n```\n\nTo pin to a specific release:\n```\n/plugin marketplace add benelser/imessage-tools#v3.0.0\n```\n\n### OpenAI Codex CLI\n\n```bash\ngit clone https://github.com/benelser/imessage-tools.git\ncd imessage-tools\nbun install \u0026\u0026 bun link\nbun run scripts/deploy.ts codex\n```\n\nThen restart Codex — the plugin will be enabled automatically.\n\n**Codex sandbox note:** Read commands (inbox, read, search, catchup) work in any sandbox mode. Send commands require **Full access** sandbox because AppleScript needs to control Messages.app. Set this in Codex Settings \u003e Sandbox settings, or pass `--sandbox danger-full-access` for non-interactive `codex exec`.\n\n### Global CLI\n\nClaude Code automatically registers `imessage-tools` as a global command on first session start (via a SessionStart hook). No manual step needed.\n\nFor Codex, `bun link` is included in the install flow above.\n\n## Skills\n\nSkills are invoked with `/` in Claude Code and `$` in Codex:\n\n| Claude Code | Codex CLI | Description |\n|---|---|---|\n| `/imessage-inbox` | `$imessage-inbox` | Recent conversation threads |\n| `/imessage-read` | `$imessage-read` | Read messages by contact or group |\n| `/imessage-search` | `$imessage-search` | Search messages by keyword |\n| `/imessage-catchup` | `$imessage-catchup` | What did I miss? |\n| `/imessage-send` | `$imessage-send` | Send a message |\n| `/imessage-group-create` | `$imessage-group-create` | Create a group chat |\n\n### [`imessage-inbox`](skills/imessage-inbox/SKILL.md) — Conversation list\n\nView recent threads like the Messages sidebar. Shows contact names, timestamps, message previews, and who spoke last.\n\n```\nimessage-inbox        # last 15 threads\nimessage-inbox 5      # last 5 threads\n```\n\n```\n  CONTACT                           TIME\n  ──────────────────────────────────────────────\n  Jane Doe                          9:17 AM\n    \u003e You: Sounds good, see you there\n  ──────────────────────────────────────────────\n  Work Chat                         8:57 AM\n    \u003e Sarah: deployed the fix\n  ──────────────────────────────────────────────\n```\n\n### [`imessage-read`](skills/imessage-read/SKILL.md) — Conversation view\n\nRead messages in a chat-style layout with day separators, right-aligned sent messages, smart timestamps (only shown on 30min+ gaps), and inline reactions.\n\n```\nimessage-read                       # last 20 messages (all contacts)\nimessage-read 10                    # last 10 messages\nimessage-read 20 +1555…             # last 20 from a specific number\nimessage-read --group \"Work Chat\"   # read a group chat\n```\n\n```\n                     ── Today ──\n\nJane Doe  9:15 AM\n    Hey are you free for coffee?\n    I'm at the place on 5th\n\n                                     Sure, give me 10 min  9:17 AM\n                                          On my way now\n\nJane Doe  10:45 AM\n    That was fun! (♥️ You)\n\n                                               Definitely!  10:46 AM\n```\n\n### [`imessage-search`](skills/imessage-search/SKILL.md) — Search with context\n\nSearch message history by keyword. Results are grouped by conversation with surrounding messages for context. Matching messages are marked with `▶`.\n\n```\nimessage-search \"coffee\"        # last 25 matches\nimessage-search \"coffee\" 50     # last 50 matches\n```\n\n```\n  Found 2 messages matching \"coffee\" in 2 conversations\n\n  ── Jane Doe ──────────────────────────────────\n    Jane Doe  Mar 29, 9:13 AM\n      Hey are you free tomorrow?\n    Me  Mar 29, 9:14 AM\n  ▶   Want to grab coffee at the usual spot?\n    Jane Doe  Mar 29, 9:15 AM\n      Yes! 10am works\n```\n\n### [`imessage-catchup`](skills/imessage-catchup/SKILL.md) — What did I miss?\n\nShows messages received since your last sent message, grouped by conversation with counts. Perfect for checking in after being heads-down.\n\n```\nimessage-catchup      # since your last sent message\nimessage-catchup 2    # last 2 hours\n```\n\n```\n  You've been away since 2:30 PM (1h 47m)\n\n  ── Jane Doe (3 new) ────────────────────────\n    Hey are you around?                  2:45 PM\n    Just called, call me back            3:15 PM\n    Nvm figured it out                   3:52 PM\n\n  ── Work Chat (1 new) ───────────────────────\n    Sarah: deployed the fix              3:30 PM\n\n  4 new messages in 2 conversations\n```\n\n### [`imessage-send`](skills/imessage-send/SKILL.md) — Send a message\n\nSupports three modes: 1:1, 1:many (individual sends), and group chat. Resolves contact names with fuzzy matching and disambiguation.\n\n**1:1** — send to a single contact by name or number:\n```\nimessage-send \"Jane Doe\" \"Hey what's up?\"\nimessage-send +15551234567 \"Hello!\"\nimessage-send \"Jane\" \"Hello!\" --rcs\n```\n\n**1:many** — send the same message individually to multiple contacts:\n```\nimessage-send \"Jane, John, Bob\" \"Meeting at 3\"\n```\n```\n  Resolved \"Jane\" -\u003e Jane Doe (+15551234567)\n  Resolved \"John\" -\u003e John Smith (+15559876543)\n  Resolved \"Bob\" -\u003e Bob Jones (+15550001111)\n\n  [ok] Jane Doe: sent via iMessage\n  [ok] John Smith: sent via iMessage\n  [ok] Bob Jones: sent via SMS\n```\n\n**Group chat** — send to an existing named group:\n```\nimessage-send --group \"Work Chat\" \"Hello team!\"\n```\nThe group must have a display name set in Messages.app (tap group info to name it). Unnamed groups can't be targeted by name.\n\n### [`imessage-group-create`](skills/imessage-group-create/SKILL.md) — Create a group chat\n\nInteractive, human-in-the-loop group creation. The agent walks you through each step and never sends without your explicit confirmation.\n\n```\n\u003e imessage-group-create\n```\n\nThe agent will:\n\n1. **Ask** who should be in the group\n2. **Resolve** each name against your Contacts, flagging ambiguous or missing matches\n3. **Present** the roster and let you `+Name` / `-Name` to adjust\n4. **Confirm** before creating — only proceeds on your explicit \"yes\"\n5. **Ask** for the first message\n6. **Create** the group by sending to all members\n\nNote: group naming must be done in Messages.app after creation (AppleScript limitation).\n\n## Developer Tooling\n\n### Build\n\nGenerates platform-specific plugin artifacts from `skills-src/` (single source of truth):\n\n```bash\nbun run scripts/build.ts\n```\n\nOutputs `.claude-plugin/`, `.codex-plugin/`, `.agents/plugins/`, and universal `skills/`.\n\n### Deploy\n\nAutomates the full install/reinstall cycle:\n\n```bash\nbun run scripts/deploy.ts claude    # reinstall for Claude Code\nbun run scripts/deploy.ts codex     # install for Codex CLI\nbun run scripts/deploy.ts all       # both platforms + bun link\nbun run scripts/deploy.ts link      # just register global CLI\n```\n\n## How it works\n\n- **Reading messages** — Queries `~/Library/Messages/chat.db` (SQLite) directly. No AppleScript needed for reads.\n- **Contact resolution** — Cross-references phone numbers/emails against macOS AddressBook databases to display real contact names instead of raw identifiers.\n- **Reactions** — Tapback reactions are collapsed inline onto their parent messages instead of appearing as separate entries.\n- **Service detection** — Uses `account_id` from chat history (not the unreliable `service_name` field) to determine the correct transport (iMessage/RCS/SMS) before sending.\n- **Sending** — Uses AppleScript to drive Messages.app with auto-detection of iMessage/RCS/SMS. Phone numbers are normalized to E.164 format for reliable delivery.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenelser%2Fimessage-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenelser%2Fimessage-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenelser%2Fimessage-tools/lists"}