terminal-messenger 0.1.3

Terminal iMessage client for macOS

tmsg

tmsg is a terminal client for iMessage on macOS.

Package name: terminal-messenger
Command name: tmsg

Features

• Sends messages through Messages.app using AppleScript.
• Reads recent messages from the local Messages database.
• Lets you pick recent conversations from the terminal.
• Loads recent message history when you open a chat.
• Resolves many phone numbers and emails to contact names from macOS Contacts.
• Supports arrow-key navigation and live search.
• Shows unread chats in the picker.

Requirements

• macOS
• iMessage set up in Messages.app
• Python 3.8+

Install

Recommended:

pipx install terminal-messenger

If you do not use pipx:

python3 -m pip install terminal-messenger

First-time macOS permissions

tmsg needs macOS permissions to work:

• Automation so it can send through Messages.app
• Full Disk Access so it can read ~/Library/Messages/chat.db

The first send should trigger the Automation prompt automatically.

If reading or sending fails, check:

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

You may need to grant access to both your terminal app and the Python binary it uses.

Quick start

tmsg

That opens the home screen with your recent chats.

The main flow is:

1. Run tmsg
2. Pick a chat
3. Type messages
4. Use /list anytime to go back to the home screen

Main commands

Open tmsg and show your chats:

tmsg

Go back to the chat list from inside a conversation:

/list

Other commands

Open a specific conversation:

tmsg frida

Open a specific phone number or email:

tmsg --contact "[phone]"

Show more history when opening a chat:

tmsg --history-limit 200

While using it

In the picker:

• Type to search
• Up / Down to move
• Enter to open
• Esc or q to cancel

In a chat:

• /list
• /help
• /history
• /quit

Troubleshooting

• Operation not permitted usually means Full Disk Access is missing
• send failures usually mean Automation permission was denied
• if tmsg is not found after install, reopen your terminal or refresh your shell shims
• macOS Messages internals are undocumented, so some reactions and rich content may still be imperfect

Development

git clone <your-repo-url>
cd terminal-messenger
python3 -m pip install -e .
python3 -m unittest discover -s tests

You can also run it directly during development:

python3 -m tmsg