A secure, decentralized, peer-to-peer messaging app that works over Bluetooth mesh networks. No internet required, no servers, no phone numbers - just pure encrypted communication.
This project is released into the public domain. See the LICENSE file for details.
- Decentralized Mesh Network: Automatic peer discovery and multi-hop message relay over Bluetooth LE
- End-to-End Encryption: X25519 key exchange + AES-256-GCM for private messages
- Channel-Based Chats: Topic-based group messaging with optional password protection
- Store & Forward: Messages cached for offline peers and delivered when they reconnect
- Privacy First: No accounts, no phone numbers, no persistent identifiers
- IRC-Style Commands: Familiar
/join,/msg,/whostyle interface - Message Retention: Optional channel-wide message saving controlled by channel owners
- Universal App: Native support for iOS and macOS
- Cover Traffic: Timing obfuscation and dummy messages for enhanced privacy
- Emergency Wipe: Triple-tap to instantly clear all data
- Performance Optimizations: LZ4 message compression, adaptive battery modes, and optimized networking
-
Install XcodeGen if you haven't already:
brew install xcodegen
-
Generate the Xcode project:
cd bitchat xcodegen generate -
Open the generated project:
open bitchat.xcodeproj
-
Open the project in Xcode:
cd bitchat open Package.swift -
Select your target device and run
- Open Xcode and create a new iOS/macOS App
- Copy all Swift files from the
bitchatdirectory into your project - Update Info.plist with Bluetooth permissions
- Set deployment target to iOS 16.0 / macOS 13.0
/j #channel- Join or create a channel/m @name message- Send a private message/w- List online users/channels- Show all discovered channels/block @name- Block a peer from messaging you/block- List all blocked peers/unblock @name- Unblock a peer/clear- Clear chat messages/pass [password]- Set/change channel password (owner only)/transfer @name- Transfer channel ownership/save- Toggle message retention for channel (owner only)
- Launch bitchat on your device
- Set your nickname (or use the auto-generated one)
- You'll automatically connect to nearby peers
- Join a channel with
/j #generalor start chatting in public - Messages relay through the mesh network to reach distant peers
- Password Protection: Channel owners can set passwords with
/pass - Message Retention: Owners can enable mandatory message saving with
/save - @ Mentions: Use
@nicknameto mention users (with autocomplete) - Ownership Transfer: Pass control to trusted users with
/transfer
- Private Messages: X25519 key exchange + AES-256-GCM encryption
- Channel Messages: Argon2id password derivation + AES-256-GCM
- Digital Signatures: Ed25519 for message authenticity
- Forward Secrecy: New key pairs generated each session
- No Registration: No accounts, emails, or phone numbers required
- Ephemeral by Default: Messages exist only in device memory
- Cover Traffic: Random delays and dummy messages prevent traffic analysis
- Emergency Wipe: Triple-tap logo to instantly clear all data
- Local-First: Works completely offline, no servers involved
- LZ4 Compression: Automatic compression for messages >100 bytes
- 30-70% bandwidth savings on typical text messages
- Smart compression: Skips already-compressed data
- Adaptive Power Modes: Automatically adjusts based on battery level
- Performance mode: Full features when charging or >60% battery
- Balanced mode: Default operation (30-60% battery)
- Power saver: Reduced scanning when <30% battery
- Ultra-low power: Emergency mode when <10% battery
- Background efficiency: Automatic power saving when app backgrounded
- Configurable scanning: Duty cycle adapts to battery state
- Optimized Bloom filters: Faster duplicate detection with less memory
- Message aggregation: Batches small messages to reduce transmissions
- Adaptive connection limits: Adjusts peer connections based on power mode
bitchat uses an efficient binary protocol optimized for Bluetooth LE:
- Compact packet format with 1-byte type field
- TTL-based message routing (max 7 hops)
- Automatic fragmentation for large messages
- Message deduplication via unique IDs
- Each device acts as both client and peripheral
- Automatic peer discovery and connection management
- Store- 64A6 and-forward for offline message delivery
- Adaptive duty cycling for battery optimization
For detailed protocol documentation, see the Technical Whitepaper.
- Set your development team in project settings
- Configure code signing
- Archive and distribute through App Store or TestFlight
The protocol is designed to be platform-agnostic. An Android client can be built using:
- Bluetooth LE APIs
- Same packet structure and encryption
- Compatible service/characteristic UUIDs