{"id":30434297,"url":"https://github.com/bxdoan/py-bitchat","last_synced_at":"2025-08-22T23:32:43.618Z","repository":{"id":304633699,"uuid":"1019360423","full_name":"bxdoan/py-bitchat","owner":"bxdoan","description":"bluetooth mesh chat, IRC vibes","archived":false,"fork":false,"pushed_at":"2025-07-14T09:14:30.000Z","size":77,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-14T12:07:10.396Z","etag":null,"topics":["bitchat","bitchat-cli","bitchat-python","bluetooth","encryption","p2p"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bxdoan.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-14T07:57:49.000Z","updated_at":"2025-07-14T09:14:33.000Z","dependencies_parsed_at":"2025-07-14T12:08:55.928Z","dependency_job_id":"383dcae6-cc6b-426f-bdba-00ca8b168b75","html_url":"https://github.com/bxdoan/py-bitchat","commit_stats":null,"previous_names":["bxdoan/py-bitchat"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bxdoan/py-bitchat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxdoan%2Fpy-bitchat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxdoan%2Fpy-bitchat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxdoan%2Fpy-bitchat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxdoan%2Fpy-bitchat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bxdoan","download_url":"https://codeload.github.com/bxdoan/py-bitchat/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxdoan%2Fpy-bitchat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271717117,"owners_count":24808590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitchat","bitchat-cli","bitchat-python","bluetooth","encryption","p2p"],"created_at":"2025-08-22T23:32:40.316Z","updated_at":"2025-08-22T23:32:43.612Z","avatar_url":"https://github.com/bxdoan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cpre\u003e\n##\\       ##\\   ##\\               ##\\                  ##\\     \n## |      \\__|  ## |              ## |                 ## |    \n#######\\  ##\\ ######\\    #######\\ #######\\   ######\\ ######\\   \n##  __##\\ ## |\\_##  _|  ##  _____|##  __##\\  \\____##\\\\_##  _|  \n## |  ## |## |  ## |    ## /      ## |  ## | ####### | ## |    \n## |  ## |## |  ## |##\\ ## |      ## |  ## |##  __## | ## |##\\ \n#######  |## |  \\####  |\\#######\\ ## |  ## |\\####### | \\####  |\n\\_______/ \\__|   \\____/  \\_______|\\___|  \\__| \\_______|  \\____/ \n\u003c/pre\u003e\n\n**_bitchat the terminal v1.0.0_**\n\n**Decentralized • Encrypted • Peer-to-Peer • Open Source | Written in Python**\n\n\u003c/div\u003e\n\n---\n# BitChat Terminal - Python Implementation\n\nPython implementation of BitChat Terminal - a decentralized, encrypted, peer-to-peer chat application over Bluetooth LE.\n\n## Features\n\n- **Decentralized**: No central server required\n- **End-to-end Encryption**: Uses X25519 + Ed25519 + ChaCha20-Poly1305\n- **Peer-to-Peer**: Direct connection via Bluetooth LE\n- **Cross-platform**: Compatible with Rust, iOS and Android versions\n- **Password-protected Channels**: Support for private channels\n- **Message Fragmentation**: Handles large messages\n- **Delivery Confirmation**: Message delivery acknowledgments\n- **Terminal Interface**: Simple command-line interface\n\n## Installation\n\n### System Requirements\n\n- Python 3.11 or newer\n- Bluetooth LE hardware\n- Windows 10/11, macOS or Linux\n\n### Install Dependencies\n\n```bash\n# Create virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate  # Linux/macOS\n# or\nvenv\\Scripts\\activate  # Windows\n\n# Install dependencies\npip install -e .\n```\n\n## Usage\n\n### Launch Application\n\n```bash\n# Run normally\npython -m src.main\n\n# Or with debug mode\npython -m src.main -d      # Basic debug\npython -m src.main -dd     # Verbose debug\n```\n\n### Basic Commands\n\n#### Chat Commands\n- `/help` - Show help\n- `/exit` - Exit application\n- `/clear` - Clear screen\n- `/status` - Show connection status\n\n#### User Management\n- `/name \u003cnickname\u003e` - Change nickname\n- `/online` - See who's online\n- `/block @user` - Block user\n- `/unblock @user` - Unblock user\n\n#### Channels\n- `/j #channel` - Join public channel\n- `/j #channel \u003cpassword\u003e` - Join password-protected channel\n- `/channels` - List discovered channels\n- `/leave` - Leave current channel\n- `/pass \u003cpassword\u003e` - Set channel password (owner only)\n- `/transfer @user` - Transfer channel ownership\n\n#### Private Messages\n- `/dm \u003cnickname\u003e` - Start DM with user\n- `/dm \u003cnickname\u003e \u003cmessage\u003e` - Send direct private message\n- `/reply` - Reply to last private message\n\n#### Conversation Management\n- `/list` - Show active conversations\n- `/switch` - Interactive conversation switching\n- `1`, `2`, `3`... - Quick switch by number\n\n#### Sending Messages\nSimply type your message and press Enter to send to current context (public, channel, or DM).\n\n## Project Structure\n\n```\nsrc/\n├── __init__.py           # Package initialization\n├── main.py              # Entry point and main logic\n├── encryption.py        # Encryption handling (X25519, Ed25519, ChaCha20)\n├── compression.py       # Data compression (Zstandard)\n├── fragmentation.py     # Large message fragmentation\n├── terminal_ux.py       # Terminal interface and chat context\n└── persistence.py       # Settings and state storage\n```\n\n## Protocol Compatibility\n\nThe Python Terminal implementation is based on the original Bitchat projects:\n- Original Rust version by [ShilohEye](https://github.com/ShilohEye/bitchat-terminal)\n- iOS BitChat app by [Jack](https://github.com/permissionlesstech/bitchat)\n- Android BitChat app [Jack](https://github.com/permissionlesstech/bitchat-android)\n\nAll use the same:\n- Bluetooth LE service UUID: `F47B5E2D-4A9E-4C5A-9B3F-8E1D2C3A4B5C`\n- Characteristic UUID: `A1B2C3D4-E5F6-4A5B-8C9D-0E1F2A3B4C5D`\n- Binary protocol format\n- Encryption algorithms\n\n## Dependencies\n\n### Core Dependencies\n- `bleak` - Bluetooth LE library\n- `cryptography` - Cryptographic operations\n- `pynacl` - NaCl cryptography (Ed25519, X25519)\n- `pybloom-live` - Bloom filter implementation\n- `zstandard` - Fast compression\n- `colorama` - Terminal colors\n\n### Development Dependencies\n- `pytest` - Testing framework\n- `black` - Code formatter\n- `flake8` - Linting\n- `mypy` - Type checking\n\n## Configuration\n\nThe application automatically saves settings at:\n- **Windows**: `%APPDATA%\\BitChat\\state.json`\n- **macOS/Linux**: `~/.config/bitchat/state.json`\n\n### Saved Data\n- Nickname\n- Blocked users (by fingerprint)\n- Channel creators and settings\n- Password-protected channels (passwords encrypted)\n- Identity key for encryption\n\n## Security Features\n\n### Encryption\n- **X25519** for key exchange\n- **Ed25519** for digital signatures\n- **ChaCha20-Poly1305** for symmetric encryption\n- **HKDF** for key derivation\n\n### Privacy\n- Message padding to hide message length\n- Cover traffic for iOS compatibility\n- Local storage with encrypted passwords\n- No telemetry or analytics\n\n### Network Security\n- Peer authentication via public key cryptography\n- Message replay protection with bloom filters\n- TTL-based message propagation\n- Forward secrecy for ephemeral keys\n\n## Troubleshooting\n\n### Bluetooth Issues\n```bash\n# Linux: Ensure user has bluetooth permissions\nsudo usermod -a -G bluetooth $USER\n\n# Check Bluetooth service\nsystemctl status bluetooth\n```\n\n### Permission Issues\n- **Windows**: Run as Administrator if needed\n- **macOS**: Allow app to access Bluetooth in System Preferences\n- **Linux**: Ensure user is in `bluetooth` group\n\n### Debug Mode\n```bash\n# Basic debug - shows connection info\npython -m src.main -d\n\n# Verbose debug - shows all packet info\npython -m src.main -dd\n```\n\n## Development\n\n### Setup Development Environment\n```bash\ngit clone https://github.com/bxdoan/py-bitchat\ncd py-bitchat\npython -m venv venv\nsource venv/bin/activate\npip install -e \".[dev]\"\n```\n\n### Testing\n```bash\npytest tests/\n```\n\n### Code Formatting\n```bash\nblack src/\nflake8 src/\nmypy src/\n```\n\n## Roadmap\n\n- [ ] GUI wrapper with tkinter/PyQt\n- [ ] File transfer support\n- [ ] Voice message support\n- [ ] Group calls\n- [ ] Mobile notifications\n- [ ] Plugin system\n\n## License\n\nMIT License - see LICENSE file\n\n## Contributing\n\nAll contributions are welcome! Please:\n\n1. Fork the repository\n2. Create feature branch\n3. Commit changes\n4. Push to branch\n5. Create Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbxdoan%2Fpy-bitchat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbxdoan%2Fpy-bitchat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbxdoan%2Fpy-bitchat/lists"}