A lightweight, keyboard-driven terminal user interface for SimpleX Chat. Built in Rust with ratatui, designed for cyberdeck enthusiasts, privacy advocates, and anyone who prefers the terminal.
Version: 0.1.1-alpha (06. January 2026)
Status: Active Development
Tested on: Debian 12, Ubuntu 24.04, Raspberry Pi OS (64-bit)
Companion to: SimpleX Private Infrastructure Tutorial
Real-time messaging with colored avatars, message status indicators (✓/✓✓), and animated status bar
⚠️ ALPHA SOFTWAREThis project is in active development. Core features work, but expect rough edges. Not recommended for production use without thorough testing.
✅ What works: Real-time messaging, contact management, address creation/sharing, message status tracking, keyboard navigation, mouse support
🚧 In progress: File transfers, group chats, settings UI, Tor integration
📡 Planned: Optional radio transport layer for off-grid communication
This release brings a complete UI/UX overhaul with professional polish:
- Fullscreen Modals - Help, Add Contact, and Panic screens now use full terminal
- Box-Bordered Buttons - Professional button styling with clean separators
- Mouse Click Support - All buttons and action bar clickable
- Animated Status Bar - Rotating messages with typewriter effect
- Colored Avatars - Unique colors per contact based on name hash
- Unread Badges - Orange
(N)counter for unread messages
- Create New Address - Proper delete→create workflow
- Auto-Refresh - Modal updates automatically after address creation
- Share Address - Display and copy invite links
- Connect via Link - Add contacts using SimpleX invite links
- Real-Time Delivery - WebSocket-based instant messaging
- Status Tracking - ○ (pending) → ✓ (sent) → ✓✓ (delivered)
- Correct Routing - Messages appear in the right chat
- Blinking Cursor - Visual feedback in input field
cd ~/simplex-tui
git pull
cargo build --release| Feature | Description |
|---|---|
| Real-Time Messaging | WebSocket connection to SimpleX CLI backend |
| Contact List | Navigable list with selection markers and avatars |
| Message History | Per-contact message storage with timestamps |
| Delivery Status | ○ pending → ✓ sent → ✓✓ delivered |
| Unread Counters | Badge showing unread messages per contact |
| Address Management | Create, refresh, share invite links |
| Connect to Contacts | Add contacts via SimpleX invite links |
| Keyboard Navigation | Full keyboard control (vim-style optional) |
| Mouse Support | Click on contacts, buttons, action bar |
| Dark Theme | Cyan/blue color scheme optimized for terminals |
| Animated Status | Rotating status messages with typewriter effect |
| Help System | Built-in keyboard shortcut reference |
| Panic Mode | Quick screen clear for privacy |
| Feature | Status | Target |
|---|---|---|
| File Transfers | Planned | v0.2.0 |
| Group Chats | Planned | v0.2.0 |
| Settings UI | Planned | v0.2.0 |
| Tor Integration | Planned | v0.3.0 |
| Notifications | Planned | v0.3.0 |
For users running cyberdeck hardware like the uConsole with AIO V2 expansion, an optional radio transport layer is planned for v0.5.0. This is entirely optional and designed for advanced users who want resilient off-grid communication.
| Feature | Description |
|---|---|
| LoRa Transport | Encrypted messaging over 868 MHz (EU) / 915 MHz (US) |
| Reticulum Support | Interoperability with existing mesh network ecosystem |
| Custom Protocol | Lightweight option for closed groups |
| Dual Transport | Automatic fallback: Tor when online, radio when offline |
| RTL-SDR Monitor | Optional spectrum awareness integration |
| GPS Integration | Optional location-aware features |
Range Expectations:
| Environment | Metric | Imperial |
|---|---|---|
| Urban (buildings) | 2-5 km | 1-3 miles |
| Suburban | 8-15 km | 5-10 miles |
| Line of sight | 50+ km | 30+ miles |
⚠️ Note: Radio features require additional hardware and are subject to local regulations. See DISCLAIMER.md for details.
| Feature | Description |
|---|---|
| Message Search | Search through chat history |
| Export/Import | Backup and restore conversations |
| Themes | Customizable color schemes |
| Plugins | Extensible architecture for testing and automation |
Coming soon
Coming soon
Coming soon
┌─────────────────────────────────────────────────────────────────┐
│ SIMPLEX TUI (Terminal) │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ UI Layer (ratatui) │ │
│ │ ├── Contact List ├── Chat View ├── Input Field │ │
│ │ ├── Status Bar ├── Modals └── Action Bar │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ Event Loop (crossterm) │
│ │ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ App State │ │
│ │ ├── Contacts ├── Messages ├── Current Chat │ │
│ │ ├── Mode (Normal/Input/Modal) └── Invite Link │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ WebSocket (tokio-tungstenite) │
│ │ │
└──────────────────────────────┼──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ SIMPLEX CHAT CLI (Backend) │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ WebSocket API (Port 5225) │ │
│ │ ├── /contacts ├── /ad (address) ├── /c (connect)│ │
│ │ ├── @contact msg ├── /sa (show addr) └── Events │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ SimpleX Protocol │
│ │ │
└──────────────────────────────┼──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ SMP/XFTP SERVERS │
│ (Your own .onion servers or public SimpleX infrastructure) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ SIMPLEX TUI (Terminal) │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ UI Layer (ratatui) │ │
│ │ ├── Contact List ├── Chat View ├── Input Field │ │
│ │ ├── Status Bar ├── Modals └── Action Bar │ │
│ │ └── Transport Indicator: [🧅 Tor] [📡 Radio] │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Transport Manager │ │
│ │ ├── SimpleX Transport (WebSocket → CLI → Tor → .onion) │ │
│ │ ├── Radio Transport (Serial → LoRa → Encrypted RF) │ │
│ │ │ ├── Reticulum/LXMF Mode (mesh interoperability) │ │
│ │ │ └── Custom Protocol Mode (closed groups) │ │
│ │ └── Capability Detection (per contact) │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┴───────────────┐ │
│ ▼ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ SimpleX CLI │ │ LoRa Module │ │
│ │ (Tor Transport) │ │ (Radio Transport) │ │
│ └──────────┬──────────┘ └──────────┬──────────┘ │
└─────────────┼───────────────────────────────┼───────────────────┘
│ │
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────────────┐
│ SMP/XFTP SERVERS │ │ RADIO NETWORK │
│ (.onion via Tor) │ │ ├── Direct P2P (custom proto) │
└─────────────────────────┘ │ └── Mesh (Reticulum network) │
└─────────────────────────────────┘
| Requirement | Version | Notes |
|---|---|---|
| Rust | 1.92+ | With cargo |
| SimpleX CLI | Latest | Running with WebSocket enabled |
| Terminal | Any | 256-color support recommended |
| Hardware | Description | Notes |
|---|---|---|
| uConsole AIO V2 | Primary target platform | LoRa + RTL-SDR + GPS integrated |
| RNode | Reticulum-native LoRa device | For mesh interoperability |
| USB LoRa Module | SX1262/SX1276 based | Alternative for desktop use |
# Clone repository
git clone https://github.com/cannatoshi/simplex-tui.git
cd simplex-tui
# Build release binary
cargo build --release
# Binary location
./target/release/simplex-tuiComing soon in GitHub Releases
# Start simplex-chat with WebSocket API enabled
simplex-chat -p 5225# From the project directory
./target/release/simplex-tui
# Or if installed globally
simplex-tui| Key | Action |
|---|---|
↑/↓ or j/k |
Navigate contacts |
Enter |
Open chat / Send message |
i |
Add contact (show address) |
Esc |
Close modal / Cancel |
q |
Quit application |
? |
Show help |
p |
Panic mode (clear screen) |
| Key | Action |
|---|---|
↑ / k |
Move up in contact list |
↓ / j |
Move down in contact list |
Enter |
Select contact / Send message |
Tab |
Switch focus (contacts ↔ input) |
| Key | Action |
|---|---|
i |
Add contact (show invite address) |
r |
Refresh contacts |
? |
Toggle help modal |
p |
Panic mode (emergency clear) |
q |
Quit application |
Esc |
Close modal / Cancel input |
| Key | Action |
|---|---|
g |
Refresh address |
c |
Create new address |
Enter |
Connect using pasted link |
Esc |
Close modal |
- Click contact → Select and open chat
- Click buttons → Activate (Refresh, Create, Close)
- Click action bar → [i]Add, [r]Rfsh, [?]Help
# WebSocket connection (default: ws://localhost:5225)
SIMPLEX_WS_URL=ws://localhost:5225
# Enable debug logging
RUST_LOG=debugThe TUI requires SimpleX CLI running with WebSocket API:
# Basic setup
simplex-chat -p 5225
# With custom database
simplex-chat -p 5225 -d ~/.simplex/myprofile
# With Tor (for .onion servers)
simplex-chat -p 5225 --socks-proxy=localhost:9050simplex-tui/
├── src/
│ ├── main.rs # Entry point, event loop
│ ├── app.rs # Application state
│ ├── types.rs # Data structures
│ ├── colors.rs # Color scheme and avatar colors
│ ├── handlers.rs # Keyboard and mouse event handlers
│ ├── websocket.rs # WebSocket connection to SimpleX CLI
│ └── ui/
│ ├── mod.rs # UI module exports
│ ├── layout.rs # Main layout structure
│ ├── contacts.rs # Contact list rendering
│ ├── chat.rs # Chat view rendering
│ ├── input.rs # Input field rendering
│ ├── status.rs # Animated status bar
│ └── modals.rs # Help, Add Contact, Panic modals
├── Cargo.toml # Rust dependencies
├── README.md # This file
├── LICENSE # AGPL-3.0
├── CHANGELOG.md # Version history
└── screenshots/ # UI screenshots
| Component | Technology |
|---|---|
| Language | Rust 1.92+ |
| TUI Framework | ratatui 0.29 |
| Terminal Backend | crossterm |
| Async Runtime | tokio |
| WebSocket | tokio-tungstenite |
| JSON Parsing | serde_json |
| Backend | SimpleX Chat CLI |
| Component | Technology | Purpose |
|---|---|---|
| Serial Communication | serialport | LoRa module interface |
| Key Exchange | x25519-dalek | Curve25519 ECDH |
| Encryption | chacha20poly1305 | Message encryption |
| Signatures | ed25519-dalek | Message authentication |
| Reticulum | reticulum (Python) | Mesh interoperability |
See ROADMAP.md for detailed development plans.
| Version | Target | Highlights |
|---|---|---|
| v0.2.0 | Feb 2026 | File transfers, group chats |
| v0.3.0 | Apr 2026 | Tor integration, encryption indicators |
| v0.4.0 | Jul 2026 | Themes, plugins, multi-instance testing |
| v0.5.0 | Oct 2026 | Radio transport (LoRa, Reticulum) |
| v1.0.0 | Mar 2027 | Stable release |
# Check if SimpleX CLI is running
ps aux | grep simplex-chat
# Start SimpleX CLI with WebSocket
simplex-chat -p 5225
# Check port is listening
ss -tlnp | grep 5225# Verify SimpleX CLI has contacts
# In SimpleX CLI directly:
/contacts
# Check WebSocket response
websocat ws://localhost:5225# Check terminal size (minimum 80x24 recommended)
echo "Columns: $COLUMNS, Lines: $LINES"
# Enable debug logging
RUST_LOG=debug ./target/release/simplex-tui# Update Rust
rustup update
# Clean and rebuild
cargo clean
cargo build --releaseContributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feat/amazing-feature) - Commit your changes (
git commit -s -m 'feat: Add amazing feature') - Push to the branch (
git push origin feat/amazing-feature) - Open a Pull Request
See CONTRIBUTING.md for detailed guidelines.
| Area | Difficulty | Impact |
|---|---|---|
| File Transfer UI | Medium | High |
| Group Chat Support | Hard | High |
| Theme System | Easy | Medium |
| Vim Keybindings | Easy | Medium |
| Documentation | Easy | High |
| Radio Protocol Testing | Hard | High |
- SimpleX Chat - The SimpleX Chat application
- SimpleX Private Infrastructure - Deploy SimpleX servers on Raspberry Pi
- SimpleX SMP Monitor - Web-based monitoring for SimpleX infrastructure
- Reticulum Network Stack - Cryptographic networking for mesh communication
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
See LICENSE for the full license text.
This software is provided "AS IS" without warranty of any kind. The authors are not responsible for any damages or issues arising from its use.
Note: This project is not affiliated with or endorsed by SimpleX Chat Ltd.
"SimpleX" is a trademark of SimpleX Chat Ltd. See TRADEMARK.md for details.
Radio Features: Radio transmission is subject to local regulations. Users are responsible for compliance with applicable laws. See DISCLAIMER.md for details.
For complete legal information, see:
- LEGAL.md - Legal documentation overview
- TRADEMARK.md - Trademark information
- DISCLAIMER.md - Full liability disclaimer
See CHANGELOG.md for detailed version history.
v0.1.1-alpha (2026-01-06)
- Complete UI/UX redesign
- Address management system
- Message routing fix
- Unread counters
- Mouse support
- Animated status bar
v0.1.0-alpha (2026-01-05)
- Initial release
- Basic messaging
- Contact list
- WebSocket integration
- GitHub: @cannatoshi
- Issues: GitHub Issues
Disclaimer: This project is not affiliated with, endorsed by, or officially connected with SimpleX Chat Ltd.
"SimpleX" is a trademark of SimpleX Chat Ltd. See TRADEMARK.md for details.
Built with 💙 for the SimpleX ecosystem and cyberdeck enthusiasts.
i(N) cod(E) w(E) trus(T)
