zero-drift-chat

A unified messaging TUI built in Rust. Aggregates multiple chat platforms into a single terminal interface.

Currently supports WhatsApp via whatsapp-rust (WhatsApp Web multi-device protocol).

See FEATURES.md for the full feature list.

Install

Download a pre-built binary

Grab the latest build for your platform from the Releases page.

Platform	Asset
Windows	zero-drift-chat-windows-x86_64.exe
macOS (Apple Silicon)	zero-drift-chat-macos-aarch64 or zero-drift-chat-macos-aarch64.dmg
Linux	zero-drift-chat-linux-x86_64

Install via script (no Rust needed)

macOS / Linux / WSL:

curl -fsSL https://raw.githubusercontent.com/mgblackwater/zero-drift-chat/master/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/mgblackwater/zero-drift-chat/master/install.ps1 | iex

From source

Requires Rust nightly (selected automatically via rust-toolchain.toml):

# Install from git
cargo install --git https://github.com/mgblackwater/zero-drift-chat

# Or install from a local clone
cargo install --path .

Usage

zero-drift-chat

On first launch with WhatsApp enabled, a QR code appears. Scan it with WhatsApp on your phone (Settings > Linked Devices > Link a Device). Make sure the terminal window is large enough for the QR code to render fully. Subsequent launches auto-reconnect.

Keybindings

Normal mode:

Key	Action
j / k	Navigate chats
Tab	Switch between chat list and messages
i / Enter	Start typing
r	Rename selected chat
s	Open settings
/	Open chat search
PgUp / PgDn	Scroll messages
y	Copy last message to clipboard
v	Enter Message Select mode
q	Quit

Insert mode:

Key	Action
Enter	Insert newline
Shift+Enter / Alt+Enter	Send message
← → / Home / End	Move cursor
Ctrl+U	Clear input
Esc	Back to normal mode

Message Select mode (v from Normal mode):

Navigate the message list and copy any message to your clipboard.

Key	Action
j / ↓	Select next message (newer)
k / ↑	Select previous message (older)
y / Enter	Copy selected message and exit
Esc / q	Cancel without copying

The selected message is highlighted with a cyan ▌ gutter and blue background. Copying uses the OSC 52 terminal escape sequence so no external tool is needed. A brief "Copied!" confirmation flashes in the status bar.

Terminal support: OSC 52 works out of the box in kitty, iTerm2, and WezTerm. In tmux, enable it with set -g set-clipboard on in your ~/.tmux.conf.

Settings overlay:

Key	Action
j / k	Navigate settings
Enter / Space	Toggle option
Ctrl+s	Save to config file
Esc	Cancel and close

Settings changes take effect on restart.

Configuration

Config file: configs/default.toml (auto-created with defaults if missing)

You can edit it manually or use the in-app settings overlay (s key).

[general]
log_level = "info"

[tui]
tick_rate_ms = 250
render_rate_ms = 33
chat_list_width_percent = 30

[mock_provider]
enabled = false

[whatsapp]
enabled = true

Data locations

File	Path
Database	~/.zero-drift-chat/zero-drift.db
WhatsApp session	~/.zero-drift-chat/whatsapp-session.db
Logs	~/.zero-drift-chat/zero-drift.log

Troubleshooting

• QR code won't scan: Make the terminal window larger. The QR must render fully without clipping.
• WhatsApp pairing stuck: Delete ~/.zero-drift-chat/whatsapp-session.db* and restart to re-pair.
• Chats show phone numbers: Custom names can be set with r. Group names populate automatically via history sync on first connect after pairing.

Building

git clone https://github.com/mgblackwater/zero-drift-chat
cd zero-drift-chat
cargo build --release

Requires nightly Rust (handled automatically via rust-toolchain.toml).

License

MIT