marchat

A lightweight terminal chat with real-time messaging over WebSockets, optional E2E encryption, and a flexible plugin ecosystem. Built for developers who prefer the command line.

Latest Updates

v0.10.0-beta.1 (Current)

Message Management: Edit, delete, pin, search messages by ID
Reactions: React to messages with emoji aliases (:react 42 +1, heart, fire, party, etc.)
Direct Messages: Private DM conversations between users
Channels: Multiple chat rooms with join/leave and per-channel messaging
Typing Indicators: See when other users are typing
E2E File Transfers: End-to-end encryption extended to file sharing
UX Enhancements: Connection status indicator, @mention tab completion, unread count, multi-line input (Alt+Enter/Ctrl+J), chat history export
Security: Rate limiting, constant-time admin key comparison, plugin download timeouts, SHA-pinned CI actions
Refactoring: Client split into hotkeys/render/websocket/commands modules, config directory unified, orphaned code removed
Docker: Added docker-compose.yml for local development
Plugins: Full plugin system wiring (message forwarding, user list updates, command responses, init handshake, store UI, license enforcement)

Recent Releases

v0.9.0-beta.6: Rebuilt with Go 1.25.8 to address CVE-2026-25679, CVE-2026-27142, CVE-2026-27139
v0.9.0-beta.5: Automated release workflow, PBKDF2 keystore key derivation, JWT secret auto-generation, race condition fixes, Docker optimizations
v0.9.0-beta.4: Fixed admin metrics, restored plugin commands in encrypted sessions, dependency updates
v0.9.0-beta.3: Added :q quit command, improved theme handling, ESC behavior tweaks, and better database backups
v0.9.0-beta.2: Database performance improvements, documentation enhancements, dependency updates
v0.9.0-beta.1: Enhanced notifications, custom themes, plugin ecosystem, test coverage improvements
v0.8.0-beta.11: Encryption UI, hotkey alternatives, command encryption fix, username validation
v0.8.0-beta.10: Plugin persistence, state management, auto-discovery, deadlock fixes

Full changelog on GitHub releases.

Server Demo Client Demo

Features

Terminal UI - Beautiful TUI built with Bubble Tea
Real-time Chat - Fast WebSocket messaging with SQLite backend (PostgreSQL/MySQL planned)
Message Management - Edit, delete, pin, react to, and search messages
Direct Messages - Private DM conversations between users
Channels - Multiple chat rooms with join/leave and per-channel messaging
Typing Indicators - See when other users are typing
Read Receipts - Message read acknowledgement (broadcast-level)
Plugin System - Remote registry with text commands and Alt+key hotkeys
E2E Encryption - X25519/ChaCha20-Poly1305 with global encryption, including file transfers
File Sharing - Send files up to 1MB (configurable) with interactive picker and optional E2E encryption
Admin Controls - User management, bans, kick system with ban history gaps
Smart Notifications - Bell + desktop notifications with quiet hours and focus mode (guide)
Themes - Built-in themes + custom themes via JSON (guide)
Docker Support - Containerized deployment with docker-compose.yml for local dev
Health Monitoring - /health and /health/simple endpoints with system metrics
Structured Logging - JSON logs with component separation and user tracking
UX Enhancements - Connection status indicator, tab completion for @mentions, unread message count, multi-line input, chat export
Cross-Platform - Runs on Linux, macOS, Windows, and Android/Termux
Diagnostics - marchat-client -doctor and marchat-server -doctor (or -doctor-json) summarize environment, resolved paths, and configuration health

Overview

marchat started as a fun weekend project for father-son coding sessions and has evolved into a lightweight, self-hosted terminal chat application designed specifically for developers who love the command line. Currently runs with SQLite, with PostgreSQL and MySQL support planned for greater scalability.

Key Benefits:

Self-hosted: No external services required
Cross-platform: Linux, macOS, Windows, and Android/Termux
Secure: Optional E2E encryption with X25519/ChaCha20-Poly1305
Extensible: Plugin ecosystem for custom functionality
Lightweight: Minimal resource usage, perfect for servers

| Cross-Platform | Theme Switching | |---------------|----------------| | <img src="assets/mobile-file-transfer.jpg" width="300"/> | <img src="assets/theme-switching.jpg" width="300"/> |

Quick Start

1. Generate Admin Key

openssl rand -hex 32

2. Start Server

Option A: Environment Variables (Recommended)

export MARCHAT_ADMIN_KEY="your-generated-key"
export MARCHAT_USERS="admin1,admin2"
./marchat-server

# With admin panel
./marchat-server --admin-panel

# With web panel
./marchat-server --web-panel

Option B: Interactive Setup

./marchat-server --interactive

3. Connect Client

# Admin connection
./marchat-client --username admin1 --admin --admin-key your-key --server ws://localhost:8080/ws

# Regular user
./marchat-client --username user1 --server ws://localhost:8080/ws

# Or use interactive mode
./marchat-client

Database Schema

Key tables for message tracking and moderation:

messages: Core message storage with message_id
user_message_state: Per-user message history state
ban_history: Ban/unban event tracking for history gaps

Installation

Binary Installation:

# Linux (amd64)
wget https://github.com/Cod-e-Codes/marchat/releases/download/v0.10.0-beta.1/marchat-v0.10.0-beta.1-linux-amd64.zip
unzip marchat-v0.10.0-beta.1-linux-amd64.zip && chmod +x marchat-*

# macOS (amd64)
wget https://github.com/Cod-e-Codes/marchat/releases/download/v0.10.0-beta.1/marchat-v0.10.0-beta.1-darwin-amd64.zip
unzip marchat-v0.10.0-beta.1-darwin-amd64.zip && chmod +x marchat-*

# Windows - PowerShell
iwr -useb https://raw.githubusercontent.com/Cod-e-Codes/marchat/main/install.ps1 | iex

Docker:

docker pull codecodesxyz/marchat:v0.10.0-beta.1
docker run -d -p 8080:8080 \
  -e MARCHAT_ADMIN_KEY=$(openssl rand -hex 32) \
  -e MARCHAT_USERS=admin1,admin2 \
  codecodesxyz/marchat:v0.10.0-beta.1

Docker Compose (local development):

docker compose up -d

From Source:

git clone https://github.com/Cod-e-Codes/marchat.git && cd marchat
go mod tidy
go build -o marchat-server ./cmd/server
go build -o marchat-client ./client

Prerequisites for source build:

Go 1.25+ (download)
Linux clipboard support: sudo apt install xclip (Ubuntu/Debian) or sudo yum install xclip (RHEL/CentOS)

Configuration

Essential Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MARCHAT_ADMIN_KEY | Yes | - | Admin authentication key | | MARCHAT_USERS | Yes | - | Comma-separated admin usernames | | MARCHAT_PORT | No | 8080 | Server port | | MARCHAT_DB_PATH | No | ./config/marchat.db | Database file path | | MARCHAT_TLS_CERT_FILE | No | - | TLS certificate (enables wss://) | | MARCHAT_TLS_KEY_FILE | No | - | TLS private key | | MARCHAT_GLOBAL_E2E_KEY | No | - | Base64 32-byte global encryption key | | MARCHAT_MAX_FILE_BYTES | No | 1048576 | Max file size in bytes (1MB default) | | MARCHAT_MAX_FILE_MB | No | 1 | Max file size in MB (alternative to bytes) | | MARCHAT_ALLOWED_USERS | No | - | Username allowlist (comma-separated) |

Additional variables: MARCHAT_LOG_LEVEL, MARCHAT_CONFIG_DIR, MARCHAT_BAN_HISTORY_GAPS, MARCHAT_PLUGIN_REGISTRY_URL

Doctor / diagnostics: MARCHAT_DOCTOR_NO_NETWORK — set to 1 to skip the GitHub latest-release check in -doctor / -doctor-json.

File Size Configuration: Use either MARCHAT_MAX_FILE_BYTES (exact bytes) or MARCHAT_MAX_FILE_MB (megabytes). If both are set, MARCHAT_MAX_FILE_BYTES takes priority.

Interactive Setup: Use --interactive flag for guided server configuration when environment variables are missing.

Client vs server config locations

| Role | Default location | Override | |------|------------------|----------| | Server (.env, SQLite DB, debug log) | In development from a repo clone: ./config next to go.mod. Otherwise MARCHAT_CONFIG_DIR or the user config path (see ARCHITECTURE.md). | MARCHAT_CONFIG_DIR, --config-dir | | Client (config.json, profiles.json, keystore, themes.json) | Per-user app data (e.g. Windows %APPDATA%\marchat, Linux/macOS ~/.config/marchat). Same when developing from source. | MARCHAT_CONFIG_DIR |

Marchat

Install / Use

README