Serverless, peer-to-peer chat over a Bluetooth LE mesh — right in your terminal.
Wire-compatible with the bitchat app for public chat: exchange text, images, voice notes, and files one hop with a real bitchat phone in range.
- 🛰️ Serverless & decentralized — no internet, accounts, or servers. Just Bluetooth.
- 📡 Talks to the real app — interoperates with bitchat on iOS/Android for public/broadcast chat.
- 🖼️ Media support — send and receive images, voice notes, and files (
/send <path>); received media is saved to~/.bitchat/downloads/and opened automatically. - 🔐 Signed messages — every packet is Ed25519-signed, matching the format the app requires.
- 🎨 Themed terminal UI — timestamps, a stable color per peer, and clear status glyphs. Honors
NO_COLOR. - 🐍 Pure Python — built on
bleak, runs on Linux, macOS, and Windows.
Requires Python 3.8+ and a working Bluetooth LE adapter.
From PyPI (recommended):
pip install bitchat-cliFrom source:
git clone https://github.com/dearabhin/bitchat-cli.git
cd bitchat-cli
pip install -e .Once installed, launch it from anywhere:
bitchat # or: bitchat-cliFrom a source checkout you can also run python -m bitchat_cli.
It immediately starts scanning for nearby bitchat peers, connects to any in range, and broadcasts whatever you type. Type a message and press Enter to send it publicly.
| Command | Description |
|---|---|
<message> |
Any text not starting with / is broadcast publicly to peers. |
/send <path> |
Send an image, voice note, or file to peers (alias: /file). |
/w |
List known peers (peer ID → nickname). |
/name <nickname> |
Change your nickname and re-announce. |
/clear |
Clear the screen. |
/help |
Show the list of available commands. |
bitchat-cli uses bleak as a BLE central that discovers, connects to, and exchanges packets with real bitchat peers in range. It implements bitchat's binary wire protocol — announce / leave / public-message / file-transfer packets, PKCS#7 padding, fragment reassembly, and Ed25519 packet signing — so it can take part in public chat with the official app.
Note
Scope & limitations. Only public/broadcast chat is supported. Private (Noise-encrypted) messaging, multi-hop mesh relaying, and advertising as a BLE peripheral are not implemented — bleak is central-only, so this client works one hop with peers it is connected to and is not itself discoverable when idle.
Verify the wire-protocol implementation without any Bluetooth hardware (needs only cryptography):
python selftest.pyRun it from a source checkout — it imports the bitchat_cli package and covers packet encode/decode, signatures, fragmentation, and the media file format.
Contributions are welcome!
- Fork the repository and clone your fork.
- Install in editable mode:
pip install -e . - Create a branch, make your change, and run
python selftest.py. - Open a Pull Request with a clear description.
An independent Python port of bitchat — the serverless BLE-mesh chat app. All the wire-format credit belongs to the upstream project; this CLI just speaks its language.
Released under the GNU GPL-3.0.