# Messenger TUI

Terminal-based Matrix client for accessing Facebook Messenger via self-hosted bridge.

## Overview

This project connects to a self-hosted Matrix homeserver (`matrix.kokoham.com`) with a mautrix-facebook bridge, providing a lightweight TUI for messaging on Messenger without the heavy desktop/mobile apps.

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                           sleepy-mini                                │
│                                                                     │
│   ┌─────────────────┐    ┌─────────────────────────────┐            │
│   │  Matrix Homeserver   │    │   mautrix-facebook bridge  │            │
│   │     (Conduit)       │◄──►│                             │            │
│   │   matrix.kokoham.com │    └──────────────┬────────────┘            │
│   └─────────┬───────────┘                   │                         │
│             │                               │                         │
│             │           Facebook/Meta       │                         │
│             │             Messenger         │                         │
│             │               ◄────           │                         │
│             │                               │                         │
└─────────────┼───────────────────────────────┼─────────────────────────┘
              │                               │
              ▼                               ▼
┌────────────────────────────────┐  ┌──────────────────────────────┐
│      WeeChat TUI (Laptop)       │  │      YouTube (Phone)         │
│                                  │  └──────────────────────────────┘
└────────────────────────────────┘
```

## Server Info

- **Homeserver**: `https://matrix.kokoham.com`
- **Server Location**: `sleepy-mini:~/Documents/personal/projects/messenger_homeserver`

## Features

- [x] Text messaging
- [ ] Group chats
- [ ] Image/media receive
- [ ] Image/media send
- [ ] Notifications
- [ ] Search

## Prerequisites

- WeeChat with Matrix plugin
- Matrix account on `matrix.kokoham.com`
- Server-side: Conduit + mautrix-facebook bridge (see [Messenger-Homeserver](../Messenger-Homeserver/))

## Setup

### 1. Install WeeChat

```bash
# macOS
brew install weechat

# Linux (Debian/Ubuntu)
sudo apt install weechat

# Linux (Arch)
sudo pacman -S weechat
```

### 2. First-Time WeeChat Setup

Run WeeChat for the first time:
```bash
weechat
```

Set your username:
```
/set weechat look.nick "your_nick"
```

### 3. Load Matrix Plugin

WeeChat 4.0+ has built-in Matrix support. Load it:
```
/plugin load matrix
```

### 4. Configure Server Connection

```bash
# Add the server
/server add kokoham https://matrix.kokoham.com:443

# Enable TLS
/set plugins.var.dev矩阵.server.kokoham.ssl_verify on

# Disable certificate verification for self-signed (if needed)
# /set plugins.var.dev矩阵.server.kokoham.ssl_verify off

# Auto-connect on startup
/set plugins.var.dev矩阵.server.kokoham.autoconnect on
```

### 5. Register/Login

**If this is a new account:**
```
/connect kokoham
/msg #register:matrix.kokoham.com your_password
```

**If you already have an account:**
```
/connect kokoham
/matrix login your_username your_password
```

### 6. Save Configuration

```
/save
```

## Usage

### Essential WeeChat Commands

| Command | Description |
|---------|-------------|
| `/buffer list` | List all joined rooms/chats |
| `/join #room:matrix.kokoham.com` | Join a room |
| `/query username` | Open private chat |
| `/window swap` | Swap windows |
| `Alt+Left/Right` or `Ctrl+P/Ctrl+N` | Switch buffers |
| `Ctrl+W then n` | Close current buffer |
| `/close` | Close current chat |
| `/set` | View/set options |
| `/help matrix` | Matrix-specific help |
| `/help` | General WeeChat help |
| `/quit` | Exit WeeChat |

### Matrix-Specific Commands

| Command | Description |
|---------|-------------|
| `/matrix info` | Show room/user info |
| `/matrix devices` | Manage encryption devices |
| `/matrix keys` | Manage encryption keys |
| `/matrix room invite @user:domain` | Invite user to room |

### Typing and Sending

- Just type and press Enter to send
- `Ctrl+Q` to quote special characters
- `Ctrl+U` to clear line

### Navigation

- `Ctrl+X` to switch between rooms with same name
- `/bar scroll` to scroll buffers

## Configuration

### Recommended Settings

Copy `config/weechat.conf` snippets to your WeeChat:

```weechat
# Autojoin channels/rooms on connect
/set plugins.var.dev矩阵.server.kokoham.autojoin_commands "/join *"

/set plugins.var.dev矩阵.notify.enabled on
/set plugins.var.dev矩阵.notify.message on
/set plugins.var.dev矩阵.notify.self on

# Show join/part messages (optional)
/set weechat.look.buffer_notify_default all

# Auto-open DMs when received
/set plugins.var.dev矩阵.server.kokoham.automaticrooms room

# Notification commands (requires relay or external script)
# /set plugins.var.dev矩阵.notify.command "/exec -nocommand echo 'New message from $1'"
```

### Color Scheme (Optional)

```weechat
/color reset
/set weechat.color.chat_time_delimiters lightgreen
/set weechat.color.chat_highlight lightmagenta
```

## Scripts & Tools

### Quick Connect Script

Run after WeeChat is installed:
```bash
cd ~/Documents/personal/projects/messenger_tui
./scripts/quick_connect.sh
```

### Notification Relay (Optional)

For desktop notifications, use `weechat-matrix-notify-relay` or configure a notification command:

```bash
# macOS notification example
/set plugins.var.dev矩阵.notify.command "/exec -nocommand osascript -e 'display notification \"${message}\" with title \"WeeChat: ${nick}\"'"
```

## Project Structure

```
messenger_tui/
├── README.md              # This file
├── .gitignore
├── SETUP.md               # Detailed setup guide (this file)
├── config/
│   └── weechat.conf       # Config snippets to copy
└── scripts/
    ├── setup_weechat.sh  # Initial setup script
    └── quick_connect.sh   # Connect to kokoham server
```

## Troubleshooting

### Connection Issues

**"Unable to connect" error:**
```bash
# Check if server is reachable
curl https://matrix.kokoham.com/_matrix/client/versions

# Try without SSL verification (for self-signed certs)
/set plugins.var.dev矩阵.server.kokoham.ssl_verify off
/disconnect kokoham
/connect kokoham
```

**TLS certificate errors:**
```bash
# On macOS, install certs if needed
/usr/local/bin/cert-sync /etc/ssl/cert.pem  # with certsync
# or
brew install ca-certificates
```

### Login Issues

**Invalid username/password:**
- Make sure you've registered or that the admin has created your account
- Check password doesn't contain special characters (escape them)

**"Authentication failed":**
```bash
# Clear saved credentials
/unset plugins.var.dev矩阵.server.kokoham.password
/matrix login your_username your_password
```

### Performance Issues

**Slow or laggy:**
```bash
# Reduce sync interval
/set plugins.var.dev矩阵.server.kokoham.poll_timeout 5000

# Disable typing notifications
/set plugins.var.dev矩阵.typing_timeout 0
```

### Encryption (E2EE)

WeeChat Matrix supports end-to-end encryption:

```bash
# First time setup
/matrix keys device_id
# This generates your encryption keys

# Verify a device
/matrix devices verify DEVICE_ID
```

## Known Limitations

- Voice/video calls: Not supported via bridge
- Read receipts: Partial support
- Some rich media features may not work
- Encryption setup requires manual key management

## See Also

- [WeeChat Quick Start](https://weechat.org/doc/quickstart/)
- [WeeChat Matrix Plugin Docs](https://weechat.org/plugins/source/devel-matrix/)
- [mautrix-facebook](https://docs.mau.fi/bridges/python/facebook/index.html)
- [Conduit Matrix Server](https://conduit.rs/)
- [Matrix.org](https://matrix.org/)