imsg — Messages.app from your terminal

#Try it

After granting Full Disk Access (covered in the Quickstart), every workflow is a one-liner.

# List the 10 most recent chats.
imsg chats --limit 10 --json | jq -s

# Read history from one chat, with attachment metadata.
imsg history --chat-id 42 --limit 20 --attachments --json

# Stream new messages live, including tapbacks.
imsg watch --chat-id 42 --reactions --json

# Send a message — auto-pick iMessage or SMS.
imsg send --to "+14155551212" --text "on my way"

# Send a file (image, audio, document).
imsg send --to "Jane Appleseed" --file ~/Desktop/voice.m4a

--json emits newline-delimited JSON on stdout; human progress and warnings always go to stderr so pipes stay parseable.

#What imsg does

Local-first reads. Chats, history, and attachments come straight from ~/Library/Messages/chat.db — no network round-trip, no daemon.
Live streams. imsg watch follows filesystem events on chat.db and falls back to a lightweight poll when macOS drops the event.
Send through Messages.app. Text, attachments, and standard tapbacks ride Messages' AppleScript automation surface — no private send APIs.
Group-aware. Direct chats, group threads, participants, GUIDs, and per-chat account routing hints all show up in JSON output.
Built for agents. Stable JSON-RPC over stdio, deterministic JSON schemas, and imsg completions llm for in-context CLI help.
Contacts integration. Resolves names from your Address Book when permission is granted, while keeping raw handles in the output.
Attachment-aware. Reports filenames, UTIs, byte counts, and resolved paths. Optional --convert-attachments exposes model-friendly CAF→M4A and GIF→PNG variants.

#Pick your path

Trying it. Install → Quickstart. Five minutes from brew install to a streaming watch.
Wiring up an agent. JSON output and JSON-RPC cover the stable contracts; completions shows how to feed the CLI reference into an LLM.
Sending messages. Send and React explain text/file/group sends and how the Tahoe ghost-row check works.
Diagnosing access. Permissions and Troubleshooting.
Advanced IMCore. Read receipts, typing, status, launch. SIP-disabled and increasingly limited on macOS 26.

#Project

Active development; the changelog tracks what shipped recently. Released under the MIT license. Not affiliated with Apple.