messenger_tui/SETUP.md

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

• 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)

Setup

1. Install WeeChat

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

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

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

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

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

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:

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

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

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

# Clear saved credentials
/unset plugins.var.dev矩阵.server.kokoham.password
/matrix login your_username your_password

Performance Issues

Slow or laggy:

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

# 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
• WeeChat Matrix Plugin Docs
• mautrix-facebook
• Conduit Matrix Server
• Matrix.org