diff --git a/README.md b/README.md index 460e0a7..e2f3d7e 100644 --- a/README.md +++ b/README.md @@ -1,130 +1,29 @@ # Messenger TUI -Terminal-based Matrix client for accessing Facebook Messenger via bridge. +Terminal-based Matrix client for accessing Facebook Messenger via self-hosted bridge on `matrix.kokoham.com`. -## Overview +## Quick Start -This project connects to a self-hosted Matrix homeserver with a mautrix-facebook bridge, providing a lightweight TUI for messaging on Messenger without the heavy desktop/mobile apps. +1. Install WeeChat: `brew install weechat` (macOS) +2. See [SETUP.md](./SETUP.md) for full configuration guide +3. Run `./scripts/quick_connect.sh` after configuring ## Architecture ``` -┌─────────────────────────────────────────────────────────────┐ -│ Your Server │ -│ ┌─────────────────┐ ┌─────────────────────────────┐ │ -│ │ Matrix Homeserver │ │ mautrix-facebook bridge │ │ -│ │ (Conduit) │◄──►│ │ │ -│ └─────────┬───────────┘ └──────────────┬────────────┘ │ -│ │ │ │ -│ │ Facebook/Meta │ │ -│ │ Messenger │ │ -│ │ ◄──── │ │ -│ │ │ │ -└─────────────┼───────────────────────────────┼────────────────┘ - │ │ - ▼ │ -┌─────────────────────────────────────────────────────────────┐ -│ Your Laptop │ -│ ┌─────────────────────────────────────────────────────┐ │ -│ │ WeeChat TUI │ │ -│ │ (This Client) │ │ -│ └─────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ +WeeChat TUI (laptop) → Matrix (matrix.kokoham.com) → mautrix-facebook → Messenger ``` -## Features +## Project Info -- [ ] Text messaging -- [ ] Group chats -- [ ] Image/media receive -- [ ] Image/media send -- [ ] Notifications -- [ ] Search +| Item | Value | +|------|-------| +| Homeserver | `https://matrix.kokoham.com` | +| Server Repo | `sleepyeldrazi/messenger_homeserver` | +| Bridge | mautrix-facebook | -## Prerequisites +## Quick Links -- WeeChat -- Matrix account on self-hosted server -- Server-side: Conduit + mautrix-facebook bridge - -## Setup - -### 1. Install WeeChat - -```bash -# macOS -brew install weechat - -# Linux (Debian/Ubuntu) -sudo apt install weechat - -# Linux (Arch) -sudo pacman -S weechat -``` - -### 2. Connect to Matrix homeserver - -```bash -/weechat plugin load matrix -/set matrix.server.your_server_name.homeserver https://your-server.com -/plugin reload matrix -``` - -### 3. Login - -```bash -/matrix certs /path/to/ca-certificate.pem # if self-signed -/matrix login your_username your_password -``` - -### 4. Bridge your Messenger account - -On the server, configure mautrix-facebook and link your Facebook account. - -## Usage - -### Basic WeeChat Commands - -| Command | Description | -|---------|-------------| -| `/buffer list` | List all joined rooms | -| `/join #room:server.com` | Join a room | -| `/query nick` | Open private chat | -| `Ctrl+P / Ctrl+N` | Switch buffers | -| `Ctrl+W then n` | Close buffer | -| `/set` | View/set options | -| `/help` | WeeChat help | - -## Configuration - -### WeeChat Matrix Settings - -```weechat -/set matrix.server.default.homeserver "https://your-matrix-server.com" -/set plugins.var.dev矩阵.notify.enabled on -/set plugins.var.dev矩阵.notify.message on -``` - -## Project Structure - -``` -messenger_tui/ -├── README.md # This file -├── .gitignore -├── config/ # WeeChat config snippets -│ └── weechat.conf -└── scripts/ # Helper scripts - └── setup_weechat.sh -``` - -## Known Limitations - -- Voice/video calls: Not supported via bridge -- Read receipts: Partial support -- Some rich media features may not work - -## See Also - -- [WeeChat Quick Start](https://weechat.org/doc/quickstart/) -- [mautrix-facebook](https://docs.mau.fi/bridges/python/facebook/index.html) -- [Conduit Matrix Server](https://conduit.rs/) +- [Full Setup Guide](./SETUP.md) +- [Server Project](../Messenger-Homeserver/) +- [Projects Index](../../../../entropy/Projects/) diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..1bea251 --- /dev/null +++ b/SETUP.md @@ -0,0 +1,300 @@ +# 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/) diff --git a/config/weechat.conf b/config/weechat.conf new file mode 100644 index 0000000..ffb6bb9 --- /dev/null +++ b/config/weechat.conf @@ -0,0 +1,73 @@ +# WeeChat Matrix Configuration Snippets +# Copy these settings to your WeeChat after connecting to matrix.kokoham.com + +# ============================================ +# NOTIFICATION SETTINGS +# ============================================ + +# Enable notifications for messages +/set plugins.var.dev矩阵.notify.enabled on + +# Show notification for every message +/set plugins.var.dev矩阵.notify.message on + +# Show notification for own messages +/set plugins.var.dev矩阵.notify.self on + +# ============================================ +# AUTO-JOIN SETTINGS +# ============================================ + +# Auto-join rooms on connect (optional) +/set plugins.var.dev矩阵.server.kokoham.autojoin true + +# Auto-create DM buffers +/set plugins.var.dev矩阵.server.kokoham.automaticrooms direct + +# ============================================ +# DISPLAY SETTINGS +# ============================================ + +# Show join/part messages +/set weechat.look.buffer_notify_default all + +# Nick color algorithm +/set weechat.color.nicklist_nick_alternate_ring on + +# ============================================ +# TYPOGRAPHY +# ============================================ + +# Timestamp format +/set weechat.look.buffer_time_format "%H:%M" + +/set weechat.look.nick_suffix "│" +/set weechat.look.nick_prefix "│" + +/set weechat.look.nick_color_first_chars "9kbzqtwxymc" + +# ============================================ +# ENCRYPTION (E2EE) +# ============================================ + +# Generate encryption keys (first time only) +/matrix keys device_id + +# Store keys in encrypted file +/set plugins.var.dev矩阵.e2ee.default_backend double_p_SOURCE + +# ============================================ +# PERFORMANCE +# ============================================ + +# Poll timeout (ms) +/set plugins.var.dev矩阵.server.kokoham.poll_timeout 1000 + +# Disable typing notifications for performance +/set plugins.var.dev矩阵.typing_timeout 0 + +# ============================================ +# SAVE +# ============================================ + +/save diff --git a/scripts/quick_connect.sh b/scripts/quick_connect.sh new file mode 100755 index 0000000..5f3a0a0 --- /dev/null +++ b/scripts/quick_connect.sh @@ -0,0 +1,40 @@ +#!/bin/bash +# Quick connect script for matrix.kokoham.com +# Run this inside WeeChat after loading the matrix plugin + +echo "Quick connect to matrix.kokoham.com" +echo "==================================" + +# Check if we're in WeeChat +if ! echo "$TERM" | grep -qE "^(xterm|screen|tmux)"; then + echo "Warning: This script is designed to run commands inside WeeChat" + echo "Start weechat first, then run: /exec -window ./scripts/quick_connect.sh" + echo "" + echo "Or paste these commands manually:" + echo "" +fi + +cat << 'EOF' +/plugin load matrix + +/server add kokoham https://matrix.kokoham.com:443 + +/set plugins.var.dev矩阵.server.kokoham.autoconnect on +/set plugins.var.dev矩阵.server.kokoham.ssl_verify on + +# Connect +/connect kokoham + +# After connecting, login with: +# /matrix login your_username your_password + +# Or register a new account: +# /msg #register:matrix.kokoham.com your_password + +/save +EOF + +echo "" +echo "After connecting, you'll need to:" +echo "1. Register or login with your Matrix credentials" +echo "2. Link your Facebook account via the bridge (see server docs)"