Menu
Cross-platform messaging CLI for Beeper Desktop. Access iMessage, WhatsApp, Instagram, LinkedIn, Telegram, Signal, Discord, Slack, and more from the terminal. Use when the user asks about messages, wants to search conversations, check unread, or send messages.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Access macOS Messages and Contacts programmatically without Full Disk Access. Use when: (1) "Operation not permitted" error accessing ~/Library/Messages/chat.db or ~/Library/Application Support/AddressBook/, (2) Need to read iMessage history, contacts, or chat data from terminal/scripts, (3) Need to SAVE or update a contact (name, phone, email, Instagram/social handle, note), (4) CNContactStore/CNSaveRequest write fails with a CoreData 4097 XPC error, (5) Full Disk Access isn't granted or isn't desirable. Covers AppleScript automation permissions workaround, the read-vs-write permission split, and Beeper Desktop CLI as alternatives to direct database access.
Use compiled Swift binaries instead of AppleScript for macOS system integrations. Use when: (1) an AppleScript is slow (>2s) for Contacts, Calendar, Reminders, or other system data, (2) need to read/write macOS Contacts, Calendar, Reminders, Focus status, or Notifications programmatically, (3) osascript is timing out or iterating slowly, (4) building a new macOS system integration for an AI agent or CLI tool. Swift + native frameworks (CNContactStore, EventKit, UNUserNotificationCenter) are ~100x faster than AppleScript equivalents. Compile once with swiftc, call from Python/Node/Bash.
Use when asked to explain, describe, or write up a topic for a technically competent audience that lacks project-specific or insider context — onboarding a new teammate, an outside reviewer, external docs, or when the user says "explain to someone unfamiliar", "don't assume inside knowledge", or "assume no context".
Git commit best practices for Claude Code. Use when: (1) about to create a git commit, (2) user asks to commit changes, (3) bundling multiple changes together. Covers atomic commits, meaningful messages, what not to commit, and ensuring commit messages reflect all changes in the diff.
Stack Overflow terminal interface with Startpage, StackExchange API, Google, and DuckDuckGo backends. Use when: (1) need to look up a programming question on Stack Overflow, (2) searching StackExchange sites (unix, superuser, serverfault), (3) fetching SO answers programmatically from a script or agent context. Default engine: Startpage. Use --print for non-TTY/pipeable output.
X/Twitter CLI for reading timelines, searching tweets, checking engagement, streaming, and managing lists. Use when: (1) user asks about tweets, Twitter, or X, (2) checking mentions or engagement, (3) searching Twitter discussions, (4) streaming tweets by keyword, (5) looking up users or followers.
| name | beeper |
| description | Cross-platform messaging CLI for Beeper Desktop. Access iMessage, WhatsApp, Instagram, LinkedIn, Telegram, Signal, Discord, Slack, and more from the terminal. Use when the user asks about messages, wants to search conversations, check unread, or send messages. |
Always use beeper (the wrapper at scripts/beeper), never beeper-desktop-cli directly.
The wrapper enriches iMessage phone numbers with contact names, does smart chat search across all scopes, and auto-loads the access token. Implementation details: scripts/README-beeper.md.
Requires Beeper Desktop running locally with API enabled (Settings > Developers).
~/scripts/.env as BEEPER_ACCESS_TOKEN (loaded by ~/.zshrc)To validate a token: curl -X POST http://localhost:23373/oauth/introspect -d "token=<token>&token_type_hint=access_token"
# Find all chats with someone — works across ALL platforms including iMessage
beeper chats search --query "Lili"
# DMs only
beeper chats search --query "Lili" --type single
# Group chats only
beeper chats search --query "climbing" --type group
What to expect: Searching by name finds chats on every platform — Instagram, WhatsApp, AND iMessage. iMessage DMs show up with the contact's name (e.g. "Lili ❤️") even though Beeper stores them as phone numbers internally.
beeper chats search --query "climbing"
beeper chats search --query "dinner" --type group
# By inbox type
beeper chats search --inbox primary --limit 20
# Unread only
beeper chats search --unread-only true
# By time range
beeper chats search --last-activity-after "2026-02-01T00:00:00Z"
# By account (e.g. just WhatsApp)
beeper chats search --account-id <accountId>
beeper chats retrieve --chat-id <chatId>
beeper chats list
beeper chats list --max-items 20
# Search across all chats
beeper messages search --query "lunch"
# Search within a specific chat
beeper messages search --chat-id <chatId> --query "address"
# Messages from others only (find unanswered stuff)
beeper messages search --query "free" --sender others
# Your own messages (find promises you made)
beeper messages search --query "should" --sender me
# Filter by date range
beeper messages search --date-after "2026-02-15T00:00:00Z" --date-before "2026-03-01T00:00:00Z"
# DMs only (skip group noise)
beeper messages search --query "tea" --chat-type single
# Messages with media
beeper messages search --media-type image
beeper messages search --media-type video
beeper messages search --media-type any
# Exclude muted/low-priority
beeper messages search --query "plans" --include-muted false --exclude-low-priority true
# List messages in a chat (newest first)
beeper messages list --chat-id <chatId>
Quick search across chats, participants, and messages in one call:
beeper search --query "dinner"
Always confirm with Femi before sending.
# Send a text
beeper messages send --chat-id <chatId> --text "On my way!"
# Reply to a specific message
beeper messages send --chat-id <chatId> --text "Sounds good" --reply-to-message-id <msgId>
# Send with attachment
beeper messages send --chat-id <chatId> --text "Check this out" --attachment /path/to/file.png
# Edit a sent message
beeper messages update --chat-id <chatId> --message-id <msgId> --text "corrected text"
beeper chats:messages:reactions add --chat-id <chatId> --message-id <msgId> --reaction-key "👍"
beeper chats:messages:reactions delete --chat-id <chatId> --message-id <msgId> --reaction-key "👍"
beeper chats:reminders create --chat-id <chatId> --remind-at "2026-03-10T09:00:00Z"
beeper chats:reminders delete --chat-id <chatId>
beeper focus
beeper focus --chat-id <chatId>
beeper focus --chat-id <chatId> --draft-text "Hey, are you free this weekend?"
beeper accounts list
beeper accounts:contacts list --account-id <accountId>
beeper accounts:contacts search --account-id <accountId> --query "Sarah"
All formats: auto, explore, json, jsonl, pretty, raw, yaml. Default is pretty.
beeper chats list --format json # single JSON array
beeper chats list --format jsonl # one JSON object per line (best for scripting)
beeper messages search --query "dinner" --format yaml
What to expect: All formats get contact enrichment — iMessage phone numbers are replaced with contact names regardless of format.
# First page
beeper chats list --format json
# → response includes "cursor" field
# Next page (older results)
beeper chats list --cursor <cursor> --direction before
# Newer results
beeper chats list --cursor <cursor> --direction after
Chat IDs contain special shell characters.
! (Matrix rooms): Use $'...' syntax to prevent zsh history expansion:
CHAT_ID=$'!roomId:server.com'
beeper chats retrieve --chat-id "$CHAT_ID"
## (iMessage): Handled automatically by the wrapper. Just pass the raw chat ID.
--query is literal token matching, not semantic. Use single words ("dinner" not "dinner plans"). Multiple words = ALL must match.--scope to chats search unless you specifically want to restrict results. Without it, the wrapper searches titles + participants + reverse phone lookup automatically. The raw CLI's default scope is unreliable.beeper messages search searches message content. beeper chats search searches chat titles/participants.localhost:23373.--debug flag shows raw HTTP requests/responses for troubleshooting.