Metadata-Version: 2.1
Name: terminal-messenger
Version: 0.1.4
Summary: Terminal iMessage client for macOS
Author: Cole Striler
Project-URL: Homepage, https://github.com/colestriler/terminal-messenger
Project-URL: Repository, https://github.com/colestriler/terminal-messenger
Project-URL: Issues, https://github.com/colestriler/terminal-messenger/issues
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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:

```bash
pipx install terminal-messenger
```

If you do not use `pipx`:

```bash
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

```bash
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:

```bash
tmsg
```

Go back to the chat list from inside a conversation:

```bash
/list
```

## Other commands

Show more history when opening a chat:

```bash
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

```bash
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:

```bash
python3 -m tmsg
```

