{"id":29906115,"url":"https://github.com/ktiseos-nyx/plural_chat","last_synced_at":"2025-08-01T20:18:00.819Z","repository":{"id":304818842,"uuid":"1020097987","full_name":"Ktiseos-Nyx/plural_chat","owner":"Ktiseos-Nyx","description":"A private desktop chat app designed for plural systems with PluralKit sync and modern themes","archived":false,"fork":false,"pushed_at":"2025-07-15T11:56:31.000Z","size":125,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-16T00:37:54.280Z","etag":null,"topics":["accessibility","desktop-app","mental-health","neurodivergent-tools","plural","plural-systems","pluralkit","tkinter-gui","tkinter-python","ttkbootstrap","ttkbootstrap-python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ktiseos-Nyx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-15T10:37:42.000Z","updated_at":"2025-07-15T11:56:34.000Z","dependencies_parsed_at":"2025-07-16T02:33:15.105Z","dependency_job_id":"26414cbd-6c14-4569-84eb-77c175527478","html_url":"https://github.com/Ktiseos-Nyx/plural_chat","commit_stats":null,"previous_names":["ktiseos-nyx/plural_chat"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Ktiseos-Nyx/plural_chat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ktiseos-Nyx%2Fplural_chat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ktiseos-Nyx%2Fplural_chat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ktiseos-Nyx%2Fplural_chat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ktiseos-Nyx%2Fplural_chat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ktiseos-Nyx","download_url":"https://codeload.github.com/Ktiseos-Nyx/plural_chat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ktiseos-Nyx%2Fplural_chat/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268290776,"owners_count":24226649,"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-01T02:00:08.611Z","response_time":67,"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":["accessibility","desktop-app","mental-health","neurodivergent-tools","plural","plural-systems","pluralkit","tkinter-gui","tkinter-python","ttkbootstrap","ttkbootstrap-python"],"created_at":"2025-08-01T20:17:59.773Z","updated_at":"2025-08-01T20:18:00.807Z","avatar_url":"https://github.com/Ktiseos-Nyx.png","language":"Python","funding_links":["https://ko-fi.com/duskfallcrew"],"categories":[],"sub_categories":[],"readme":"# 🗨️ Plural Chat\n\nA desktop chat application designed specifically for plural systems, featuring PluralKit integration and intelligent proxy detection.\n\n## 📑 Table of Contents\n\n- [✨ Features](#-features)\n- [📸 Screenshots](#-screenshots)\n- [⚠️ Known Issues](#️-known-issues)\n- [📋 Project Documentation](#-project-documentation)\n- [🚀 Quick Start](#-quick-start)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [First Time Setup](#first-time-setup)\n- [🎯 Proxy Detection](#-proxy-detection)\n- [🔧 PluralKit Integration](#-pluralkit-integration)\n  - [API Token Setup](#api-token-setup)\n  - [What Gets Imported](#what-gets-imported)\n- [📁 File Structure](#-file-structure)\n- [🎨 Themes](#-themes)\n- [📤 Sharing Systems](#-sharing-systems)\n- [🛠️ Development](#️-development)\n  - [Tech Stack](#tech-stack)\n  - [Project Structure](#project-structure)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n- [💝 Credits](#-credits)\n- [🔗 Links](#-links)\n\n## ✨ Features\n\n- **🏠 Local Desktop Chat** - Private conversations between system members\n- **🔗 PluralKit Integration** - Import members, avatars, and proxy tags from your PK system\n- **🎯 Smart Proxy Detection** - Automatic member switching based on proxy patterns\n- **💾 SQLite Database** - Fast, reliable local storage\n- **🎨 Modern Themes** - 15+ beautiful themes via ttkbootstrap\n- **📤 Export/Import** - Share system configurations with other plural folks\n- **🖼️ Avatar Support** - Display member avatars in chat\n- **📔 Personal Diary** - Private journal system for individual members\n\n## 📸 Screenshots\n\n| Main Chat Interface | Settings \u0026 Custom Themes | Personal Diary System |\n| :-----------------: | :----------------------: | :-------------------: |\n| \u003cimg src=\"screenshots/main_interface.png\" alt=\"Main chat interface with member list and conversation history\" width=\"250\"\u003e | \u003cimg src=\"screenshots/settings_themes.png\" alt=\"Settings dialog with theme selection and personalized greeting options\" width=\"250\"\u003e | \u003cimg src=\"screenshots/diary_system.png\" alt=\"Personal diary system for individual member thoughts and memories\" width=\"250\"\u003e |\n| **Active Conversations** | **Help Documentation** | **Theme Showcase** |\n| \u003cimg src=\"screenshots/active_chat.png\" alt=\"Live conversation showing multiple system members chatting\" width=\"250\"\u003e | \u003cimg src=\"screenshots/help_documentation.png\" alt=\"Comprehensive help system with detailed feature documentation\" width=\"250\"\u003e | \u003cimg src=\"screenshots/theme_showcase.png\" alt=\"Beautiful ttkbootstrap themes including Criss's custom vapor-dark theme\" width=\"250\"\u003e |\n\n## ⚠️ Known Issues\n\n- **Private Members**: Private members cannot have their avatars downloaded via API (this is expected behavior for privacy protection)\n- **Minor \"FINAL STATUS\" errors**: Occasional minor errors during sync operations (under investigation)\n- **Sample Members**: Sample members are not added upon developer cleanup (manual setup required for fresh installations)\n\n## 📋 Project Documentation\n\n- **[Installation Guide](INSTALLATION.md)** - Detailed installation instructions for all platforms\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project\n- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines and standards\n- **[Security Policy](SECURITY.md)** - Security practices and vulnerability reporting\n- **[Development Roadmap](DEVELOPMENT_ROADMAP.md)** - Future features and development plans\n- **[Community Disclaimer](DISCLAIMER.md)** - Our inclusive ethos and stance on plural community drama\n- **[Third-Party Notices](NOTICES.md)** - Licensing and attribution information\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.8 or higher\n- pip (Python package installer)\n\n### Installation\n\n1. **Clone or download** this repository\n   ```bash\n   https://github.com/Ktiseos-Nyx/plural_chat.git\n   ```\n3. **Install:**\n   ```bash\n     cd plural_chat\n     pip install .\n   ```\n4. **Run the application:**\n   ```bash\n   plural-chat\n   ```\n#### Developer Mode Options\n\n   ```bash\n  git clone https://github.com/Ktiseos-Nyx/plural_chat.git\n  cd plural_chat\n  pip install -e .\n  plural-chat\n   ```\n\n### First Time Setup\n\n1. **Add Members** - Use the Settings → Members tab to add your system members\n2. **Set Avatars** - Add avatar images for visual identification\n3. **PluralKit Sync** (Optional) - Import your existing PK system data via PK's API or via Json export via pk;export on Discord.\n4. **Choose Theme** - Pick from 15+ modern themes in Settings\n\n## 🎯 Proxy Detection\n\nIf you've imported from PluralKit or set up proxy tags, the app will automatically detect them:\n\n- Type `member: hello there` → Auto-selects \"member\" and sends \"hello there\"\n- Visual feedback shows when proxy is detected\n- Clean messages without proxy tags in chat history\n\n### Future Foward Issue\nNot everyone uses member: proxy - so being that this was developed in less than 12 hours, it'd be amazing if anyone would want to help out in robustish level fix this!\n\n## 🔧 PluralKit Integration\n\n### API Token Setup\n\n1. Get your PK token from [PluralKit Dashboard](https://dash.pluralkit.me/dash/token)\n2. Click \"PluralKit Sync\" in the app\n3. Enter your token and test connection\n4. Choose \"Sync Members\" or \"Full Import\"\n\n### What Gets Imported\n\n- ✅ Member names and display names\n- ✅ Pronouns and descriptions  \n- ✅ Proxy tags for auto-detection\n- ✅ Avatar images (downloaded locally)\n- ✅ Member colors and metadata\n- ✅ Chat history (if present in export)\n\n## 📁 File Structure\n\n- `app.db` - Application settings and preferences\n- `system.db` - Your system's members and chat history  \n- `avatars/` - Downloaded avatar images\n- `*.json` - Export files for sharing\n\n## 🎨 Themes\n\nChoose from these beautiful themes:\n- superhero, darkly, solar, cyborg, vapor\n- pulse, flatly, journal, litera, lumen\n- minty, morph, sandstone, united, yeti\n\n## 📤 Sharing Systems\n\n**Export your system:**\n- Click \"Export System\" → Save as JSON\n- Share file with other plural folks\n- Includes members, chat history, and settings\n\n**Import a system:**\n- Click \"Import System\" → Select JSON file\n- Supports PluralKit exports (auto-detects and converts)\n- Our export format is compatible for re-importing\n\n## 🛠️ Development\n\n### Tech Stack\n\n- **Python 3.8+** - Core language\n- **ttkbootstrap** - Modern UI framework\n- **SQLite** - Local database\n- **Pillow** - Image processing\n- **Requests** - HTTP client for PluralKit API\n- **aiohttp** - Asynchronous HTTP client\n- **aria2p** - High-performance download manager\n\n### Project Structure\n\n```\nplural_chat/\n├── main.py                 # Main application\n├── database_manager.py     # SQLite database handling\n├── pluralkit_api.py       # PK API integration\n├── pluralkit_dialog.py    # PK sync UI\n├── pk_export_parser.py    # PK export file parser\n├── member_manager.py      # Member management UI\n├── settings_manager.py    # Settings UI\n├── about_dialog.py        # About dialog\n├── requirements.txt       # Python dependencies\n├── pyproject.toml        # Project configuration\n└── LICENSE               # MIT license\n```\n\n## 🤝 Contributing\n\nWe welcome contributions from the plural community! Whether it's:\n\n- 🐛 Bug reports\n- 💡 Feature suggestions  \n- 🔧 Code improvements\n- 📖 Documentation updates\n\n**Please read our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before getting started.**\n\n**Want to see what's coming next?** Check out our [Development Roadmap](DEVELOPMENT_ROADMAP.md) to see planned features and find areas where you can help!\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nFor third-party components and attributions, see [NOTICES.md](NOTICES.md).\n\n## 💝 Credits\n\n- **Created by:** Duskfall Portal Crew\n- **Inspired by:** The amazing plural community\n- **Thanks to:** PluralKit team for the fantastic API\n- **UI Framework:** ttkbootstrap developers\n\n## 🔗 Links\n\n- **[GitHub Issues](https://github.com/Ktiseos-Nyx/plural_chat/issues)** - Bug reports and feature requests\n- **[GitHub Discussions](https://github.com/Ktiseos-Nyx/plural_chat/discussions)** - Community discussions and Q\u0026A\n- **[PluralKit](https://pluralkit.me)** - The bot that inspired this project\n- **[ttkbootstrap](https://ttkbootstrap.readthedocs.io)** - Modern tkinter themes\n- **[Support us](https://ko-fi.com/duskfallcrew)** - Help keep development going\n- **[Ktiseos Nyx Discord](https://discord.gg/HhBSvM9gBY)** - Development \u0026 AI Discord (Plural Friendly!)\n- **[Earth \u0026 Dusk Media Discord](https://discord.gg/5t2kYxt7An)** - Our Twitch \u0026 Media Discord (PK enabled!)\n\n---\n\n*Made with 💜 by and for the plural community*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktiseos-nyx%2Fplural_chat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fktiseos-nyx%2Fplural_chat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktiseos-nyx%2Fplural_chat/lists"}