https://github.com/dearabhin/bitchat-cli
This is a Python-based, command-line implementation of "bitchat", a secure, decentralized, peer-to-peer messaging app that works over Bluetooth mesh networks. This version is designed to be compatible with the original Swift application's protocol.
https://github.com/dearabhin/bitchat-cli
bitchat bitchat-cli bitchat-python
Last synced: 11 days ago
JSON representation
This is a Python-based, command-line implementation of "bitchat", a secure, decentralized, peer-to-peer messaging app that works over Bluetooth mesh networks. This version is designed to be compatible with the original Swift application's protocol.
- Host: GitHub
- URL: https://github.com/dearabhin/bitchat-cli
- Owner: dearabhin
- License: gpl-3.0
- Created: 2025-07-09T02:27:14.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-09T07:39:56.000Z (about 1 year ago)
- Last Synced: 2025-10-19T09:32:14.918Z (9 months ago)
- Topics: bitchat, bitchat-cli, bitchat-python
- Language: Python
- Homepage:
- Size: 48.8 KB
- Stars: 20
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# bitchat-cli
**Serverless, peer-to-peer chat over a Bluetooth LE mesh — right in your terminal.**
Wire-compatible with the [bitchat](https://github.com/permissionlesstech/bitchat) app for **public chat**:
exchange text, images, voice notes, and files one hop with a real bitchat phone in range.
[](https://pypi.org/project/bitchat-cli/)
[](https://pypi.org/project/bitchat-cli/)
[](https://github.com/dearabhin/bitchat-cli/stargazers)
[](https://github.com/dearabhin/bitchat-cli/actions/workflows/publish.yml)
[](https://github.com/dearabhin/bitchat-cli/releases)
[](LICENSE)
[](#-contributing)
---
## ✨ Features
- 🛰️ **Serverless & decentralized** — no internet, accounts, or servers. Just Bluetooth.
- 📡 **Talks to the real app** — interoperates with [bitchat](https://github.com/permissionlesstech/bitchat) on iOS/Android for public/broadcast chat.
- 🖼️ **Media support** — send and receive **images, voice notes, and files** (`/send `); 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`](https://github.com/hbldh/bleak), runs on Linux, macOS, and Windows.
## 📦 Installation
> Requires **Python 3.8+** and a working **Bluetooth LE** adapter.
**From PyPI (recommended):**
```bash
pip install bitchat-cli
```
**From source:**
```bash
git clone https://github.com/dearabhin/bitchat-cli.git
cd bitchat-cli
pip install -e .
```
## 🚀 Usage
Once installed, launch it from anywhere:
```bash
bitchat # or: bitchat-cli
```
From 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.
## 💬 Commands
| Command | Description |
| --- | --- |
| `` | Any text not starting with `/` is broadcast publicly to peers. |
| `/send ` | Send an image, voice note, or file to peers (alias: `/file`). |
| `/w` | List known peers (peer ID → nickname). |
| `/name ` | Change your nickname and re-announce. |
| `/clear` | Clear the screen. |
| `/help` | Show the list of available commands. |
## 🔧 How it works
bitchat-cli uses [`bleak`](https://github.com/hbldh/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.
## 🧪 Protocol self-test
Verify the wire-protocol implementation without any Bluetooth hardware (needs only `cryptography`):
```bash
python selftest.py
```
Run it from a source checkout — it imports the `bitchat_cli` package and covers packet encode/decode, signatures, fragmentation, and the media file format.
## 🤝 Contributing
Contributions are welcome!
1. Fork the repository and clone your fork.
2. Install in editable mode: `pip install -e .`
3. Create a branch, make your change, and run `python selftest.py`.
4. Open a Pull Request with a clear description.
## 🙌 Credits
An independent Python port of [**bitchat**](https://github.com/permissionlesstech/bitchat) — the serverless BLE-mesh chat app. All the wire-format credit belongs to the upstream project; this CLI just speaks its language.
## 📄 License
Released under the [GNU GPL-3.0](LICENSE).