Bitchat uses an IRC-style interface to send messages across two complementary transports: a Bluetooth Low Energy mesh network that works entirely offline, and a Nostr relay network for internet-connected messaging. You do not need an account, a phone number, or a server. Your identity is a cryptographic key pair generated the first time you launch the app.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/permissionlesstech/bitchat/llms.txt
Use this file to discover all available pages before exploring further.
Channel Types
Bitchat organizes conversations into three kinds of channels:#mesh (Bluetooth)
Local broadcast to every device within multi-hop Bluetooth range. No internet required. Works in disasters, protests, and areas with no connectivity.
Private DM
End-to-end encrypted one-to-one chat using the Noise Protocol over Bluetooth, with Nostr and courier fallbacks when the recipient is offline.
Location Channels
Geohash-scoped public rooms on Nostr relays. Requires internet. Scoped to a block, neighborhood, city, province, or region.
Sending a Public Mesh Message
The#mesh channel is the main public room. Every signed message you post is broadcast to all devices within multi-hop Bluetooth range (up to 7 hops) and cached for 6 hours so peers who join later can catch up.
Open the mesh timeline
Tap #mesh at the top of the channel list (or it opens by default on first launch).
Type your message
Tap the composer at the bottom of the screen and type your message. The composer accepts plain text up to the BLE packet limit.
Starting a Private Conversation
Private messages are end-to-end encrypted using the Noise Protocol. Once a Noise session is established between two devices, all private payloads ride inside it as opaque ciphertext — relaying nodes see only encrypted packets.Find the peer
In the peer list or in the mesh timeline, tap a peer’s name to open their profile, then tap Message. Alternatively, type
/msg @nickname in the composer.Wait for the handshake
Bitchat performs a Noise XX handshake automatically. This provides mutual authentication and forward secrecy for the live session. You will see a lock icon once the session is established.
How Bitchat Picks a Transport
When you send a private message, Bitchat evaluates three delivery paths in order and uses the best one available:- 1 · Bluetooth (preferred)
- 2 · Nostr fallback
- 3 · Courier queue
Direct Noise session over BLE mesh.
- Fastest and most private option.
- Requires a live, authenticated Noise XX session with the recipient.
- Intermediate relays see only opaque
noiseEncryptedpackets. - Used whenever the recipient is reachable within multi-hop Bluetooth range.
Message Delivery Indicators
Private messages show a delivery status that updates as the message progresses through the transport stack:| Status | Meaning |
|---|---|
| Sending… | Message is being transmitted |
| Sent | Message left your device successfully |
| Delivered | The recipient’s device acknowledged receipt |
| Read | The recipient opened the conversation |
| Failed | All transport paths exhausted; message was not delivered |
Delivery and read receipts are only available for private messages, not for public mesh broadcasts.
Composer Tips
- Type
/to open the command autocomplete panel and see a list of all available slash commands. - Use
@nicknameto address commands at a specific peer (e.g./msg @alice hello). - Images and voice notes can be attached using the camera and microphone buttons in the composer toolbar. Media is only available in the mesh and private chat contexts — not in location channels.
- Messages are LZ4-compressed before transmission to make the most of BLE bandwidth.