terminal-messenger 0.1.0

Terminal iMessage client for macOS

tmsg

tmsg is a local macOS terminal client for iMessage. The distributable package name is terminal-messenger, and the command people run is tmsg.

Current behavior

• Sends messages through Messages.app using AppleScript.
• Reads recent messages from the local Messages database.
• Shows up to 250 recent conversations in the picker and list view.
• Loads 100 recent messages by default when you open a chat.
• Resolves many phone numbers and emails to contact names from macOS Contacts.
• Supports arrow-key chat selection and live search in the picker.
• Shows * markers for chats with unread incoming messages.
• Styles your messages differently from incoming ones for easier scanning.

Install

For end users:

pipx install terminal-messenger

For local development:

cd /Users/colestriler/code/terminal-messenger
python3 -m pip install -e .

Run

Open the interactive picker:

tmsg

Open a specific conversation directly:

tmsg frida

or:

tmsg --contact "[phone]"

List recent conversations without opening a chat:

tmsg --list-chats

Override the default 100-message history window:

tmsg --history-limit 200

You can also run the module directly while developing:

python3 -m tmsg

Picker controls

When the chat picker is open:

• * marks chats with unread messages.
• Type to search/filter conversations live.
• Up / Down moves the selection.
• Enter opens the highlighted conversation.
• Backspace deletes search text.
• Esc or q cancels.
• The picker refreshes periodically while open so new unread chats can appear.

In-chat commands

• /help
• /history
• /list goes back to the conversation picker
• /quit

Permissions

tmsg depends on macOS privacy permissions.

• The first send should trigger an Automation prompt so your terminal or Python runtime can control Messages.
• Reading ~/Library/Messages/chat.db may require Full Disk Access for your terminal app and sometimes the python3 binary too.

If sending or reading fails, check:

• System Settings > Privacy & Security > Automation
• System Settings > Privacy & Security > Full Disk Access

Notes

• The Messages database schema is undocumented and may change across macOS versions.
• Contact-name resolution is best-effort and depends on local Contacts data.
• Some reactions, attachments, and rich-content previews are still rough around the edges.
• There may still be terminal UX quirks because the chat view currently uses a lightweight terminal loop rather than a full-screen TUI.

Verify locally

python3 -m unittest discover -s tests

Then:

1. Run tmsg.
2. Search or arrow to a conversation and press Enter.
3. Send a message and approve the Automation prompt if macOS asks.
4. Reply from another device and confirm the terminal prints the incoming message.