Metadata-Version: 2.1
Name: terminal-messenger
Version: 0.1.0
Summary: Terminal iMessage client for macOS
Author: Cole Striler
Requires-Python: >=3.8
Description-Content-Type: text/markdown

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

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

For local development:

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

## Run

Open the interactive picker:

```bash
tmsg
```

Open a specific conversation directly:

```bash
tmsg frida
```

or:

```bash
tmsg --contact "+15555555555"
```

List recent conversations without opening a chat:

```bash
tmsg --list-chats
```

Override the default 100-message history window:

```bash
tmsg --history-limit 200
```

You can also run the module directly while developing:

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

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

