.png)
1 day ago
1
- Beta Release
- Features
- Quick Start
- Usage
- Project Structure
- Admin Mode
- Security
- Tech Stack
- Troubleshooting
- Contributing
- License
marchat is a minimalist terminal-based group chat app designed for real-time, distraction-free conversations. Whether you're pair programming, self-hosting a LAN party, or just chatting from two terminals, it's lightweight, hackable, and built for fun.
Built for father-son coding sessions, marchat is about sharing the joy of hacking, learning, and chatting in a terminal. It's a fun, retro-inspired project for anyone who loves the command line, real-time collaboration, or just wants a simple, self-hosted chat.
marchat is currently in a pre-release phase with version v0.1.0-beta.2. This is the second public beta release, featuring prebuilt binaries for Linux, Windows, and macOS (amd64 only). The release includes both marchat-server and marchat-client executables, allowing you to test the application without building from source. This release includes clipboard support and bug fixes from v0.1.0-beta.1.
Important
This is a beta release intended for early testing and feedback. While stable for general use, some features may change or be refined before the first stable release. Please report any issues or suggestions on the GitHub Issues page.
-
Download the binaries:
- Visit the v0.1.0-beta.2 release page.
- Download the appropriate archive for your platform (Linux, Windows, or macOS, amd64 only).
- Extract the archive to a directory of your choice.
-
Run the server:
- Optionally, start the server with admin privileges:
./marchat-server --admin YourName --admin-key your-admin-key
- Optionally, start the server with admin privileges:
-
Run the client:
# Linux/macOS ./marchat-client --username Cody --theme patriot --server ws://localhost:9090/ws # Windows marchat-client.exe --username Cody --theme patriot --server ws://localhost:9090/ws- Alternatively, use a config.json file (see Quick Start for details).
Note
For the beta release, we recommend using the prebuilt binaries (marchat-server and marchat-client) instead of building from source. The binaries are standalone and include all dependencies.
Tip
To provide feedback on the beta release, create an issue on the GitHub Issues page with details about your experience, including your platform and any bugs encountered. Check the Full Changelog for details on what’s included in this release.
- Terminal UI (TUI): Beautiful, scrollable chat using Bubble Tea
- Real-time WebSocket Chat: Fast, robust, and cross-platform server/client
- Themes: Choose from patriot, retro, or modern for a unique look
- Small File Sharing (<1MB): Instantly send and receive small files with :sendfile <path> and save them with :savefile <filename>
- Emoji Support: Auto-converts common ASCII emoji (e.g., :), :(, :D, <3, :P) to Unicode
- Live User List: See who’s online in a fixed-width, styled panel (up to 20 users shown)
- @Mention Highlighting: Messages with @username highlight for all users in the chat
- Clipboard Support: Copy (Ctrl+C), paste (Ctrl+V), cut (Ctrl+X), and select all (Ctrl+A) in the textarea
- Admin Mode: Privileged commands (like :cleardb) for authenticated admins only
- Message Cap:
- Only the last 100 messages are kept in memory for client performance
- The server database automatically caps messages at 1000; oldest messages are deleted to make room for new ones
- Configurable: Set username, server URL, and theme via config file or flags
- Graceful Shutdown: Clean exit and robust connection handling (ping/pong heartbeat)
- ASCII Art Banner: Server displays a beautiful banner with connection info on startup
- Install Go 1.24+ if you haven’t already (only needed if building from source)
- (Check with go version in your terminal)
- (Optional, for remote access) Download cloudflared (cloudflared.exe on Windows)
- (Optional, for clipboard support on Linux) Install xclip or xsel for github.com/atotto/clipboard functionality
Note
You can configure marchat via flags or a config.json. Flags override config file values. For the beta release, use the prebuilt binaries as described in Beta Release.
Using the prebuilt binary:
Or, if building from source:
Tip
Start the server with --admin to register an admin username, and use --admin-key to secure access:
Create config.json in the project root:
Note
If no config.json is found, the client uses default values. Specify a custom config path with --config.
Using the prebuilt binary:
Or, if building from source:
Or with a config file:
Important
Ensure the server URL uses ws:// for local development or wss:// for production (secure WebSocket).
If you want to make your marchat server accessible from outside your local network (e.g., to chat with friends remotely), use Cloudflare Tunnel.
Tip
Cloudflare provides a public https:// URL. Convert it to wss://.../ws for the client (e.g., https://bold-forest-cat.trycloudflare.com becomes wss://bold-forest-cat.trycloudflare.com/ws).
Note
Temporary tunnels don’t require a Cloudflare account. For persistent tunnels, see the Cloudflare Tunnel docs.
Interact with marchat using the following commands and features:
- Send messages: Type and press Enter.
- File sharing:
- Send files (<1MB): :sendfile <path>
- Save received files: :savefile <filename>
- Emoji support: Auto-converts ASCII emoticons to Unicode (:), :(, :D, <3, :P).
- Mentions: Use @username to highlight a user (full message highlighted).
- Clipboard operations:
- Copy text: Ctrl+C (copies textarea content to clipboard)
- Paste text: Ctrl+V (appends clipboard content to textarea)
- Cut text: Ctrl+X (copies textarea content to clipboard and clears textarea)
- Select all: Ctrl+A (copies all textarea content to clipboard)
- Scroll: Use Up/Down arrows or mouse to navigate chat history.
- Commands:
- :theme <name>: Switch theme (patriot, retro, modern; persists in config).
- :time: Toggle 12/24-hour timestamp format (persists in config).
- :clear: Clear local chat buffer (client-side only, does not affect others).
- :cleardb: Wipe entire server database (admin only).
- User list: Displays up to 20 online users, with a styled +N more indicator for additional users.
- ASCII art banner: Shows connection info on server startup (disable via config or flag).
- Quit: Press Esc to exit (Ctrl+C is used for copying when textarea is focused).
Caution
The :cleardb command permanently deletes all messages in the server database. Use with caution, as this action cannot be undone.
Note
File transfers are limited to 1MB to ensure performance. Larger files should be shared via other methods.
Modular architecture: client, server logic, and shared types are separated for clarity and maintainability.
Important
Admin commands like :cleardb require the --admin flag and a matching --admin-key. Only users listed as admins on the server can authenticate.
- Start server with admins:
./marchat-server --admin Cody --admin Crystal --admin-key your-admin-key
- Connect as admin:
./marchat-client --username Cody --admin --admin-key your-admin-key --server wss://localhost:9090/ws
Warning
Do not use the default admin key (changeme) in production. Change it immediately to prevent unauthorized access.
- Admin usernames are case-insensitive.
- The admin key is sent only during the WebSocket handshake.
- All admin actions use WebSocket (no HTTP endpoints).
Warning
For production deployments:
- Change the default admin key (changeme) to a secure value.
- Use wss:// for secure WebSocket connections.
- Ensure firewall rules allow your chosen port (default: 9090).
- Consider a reverse proxy (e.g., nginx) for added security.
- Go 1.24+
- Bubble Tea (TUI)
- Lipgloss (styling)
- modernc.org/sqlite (pure Go SQLite, no C compiler required)
- Gorilla WebSocket (real-time messaging)
- atotto/clipboard (clipboard operations for copy, paste, cut, and select all)
Platform Support: Runs on Linux, macOS, and Windows terminals supporting ANSI escape sequences. Clipboard functionality on Linux requires xclip or xsel.
- Panic: close of closed channel
- Fixed: The client now guards against double-close of internal channels.
- Client fails to connect with http:// URL
- Use a WebSocket URL: ws://localhost:9090/ws or wss://... for remote.
- Mentions not highlighted
- Use @username exactly (word boundary, not substring).
- User list not updating
- Ensure server and client are both up to date and using compatible protocols.
- Messages not showing or chat not updating
- Check your WebSocket connection and server logs for errors.
- Old messages missing from chat history
- The server database only keeps the most recent 1000 messages.
- Too many users in user list
- Only up to 20 users are shown, with a styled +N more indicator.
- Clipboard operations not working
- Ensure xclip or xsel is installed on Linux for github.com/atotto/clipboard.
- Verify the textarea is focused when using Ctrl+C, Ctrl+V, Ctrl+X, or Ctrl+A.
- Firewall/Port: Ensure port 9090 is open for remote connections.
- Admin commands
- Ensure --admin and --admin-key match server settings.
Tip
When reporting bugs, include your version or commit hash for faster resolution. For beta release issues, specify that you’re using v0.1.0-beta.2.
See CONTRIBUTING.md and CODE_OF_CONDUCT.md. For the beta release, we especially welcome feedback on usability, bugs, and feature requests via the GitHub Issues page.
- Dependency Updates: marchat uses Dependabot to automatically check for and propose updates to Go module dependencies.
- Continuous Integration: All pushes and pull requests are checked by GitHub Actions for build, test, and linting. Please ensure your PR passes CI before requesting review.
This project is licensed under the MIT License.
