🗨️ Plural Chat

A desktop chat application designed specifically for plural systems, featuring PluralKit integration and intelligent proxy detection.

📑 Table of Contents

• ✨ Features
• 📸 Screenshots
• ⚠️ Known Issues
• 📋 Project Documentation
• 🚀 Quick Start
  • Prerequisites
  • Installation
  • First Time Setup
• 🎯 Proxy Detection
• 🔧 PluralKit Integration
  • API Token Setup
  • What Gets Imported
• 📁 File Structure
• 🎨 Themes
• 📤 Sharing Systems
• 🛠️ Development
  • Tech Stack
  • Project Structure
• 🤝 Contributing
• 📄 License
• 💝 Credits
• 🔗 Links

✨ Features

• 🏠 Local Desktop Chat - Private conversations between system members
• 🔗 PluralKit Integration - Import members, avatars, and proxy tags from your PK system
• 🎯 Smart Proxy Detection - Automatic member switching based on proxy patterns
• 💾 SQLite Database - Fast, reliable local storage
• 🎨 Modern Themes - 15+ beautiful themes via ttkbootstrap
• 📤 Export/Import - Share system configurations with other plural folks
• 🖼️ Avatar Support - Display member avatars in chat
• 📔 Personal Diary - Private journal system for individual members

📸 Screenshots

Main Chat Interface	Settings & Custom Themes	Personal Diary System
Active Conversations	Help Documentation	Theme Showcase

⚠️ Known Issues

• Private Members: Private members cannot have their avatars downloaded via API (this is expected behavior for privacy protection)
• Minor "FINAL STATUS" errors: Occasional minor errors during sync operations (under investigation)
• Sample Members: Sample members are not added upon developer cleanup (manual setup required for fresh installations)

📋 Project Documentation

• Installation Guide - Detailed installation instructions for all platforms
• Contributing Guide - How to contribute to the project
• Code of Conduct - Community guidelines and standards
• Security Policy - Security practices and vulnerability reporting
• Development Roadmap - Future features and development plans
• Community Disclaimer - Our inclusive ethos and stance on plural community drama
• Third-Party Notices - Licensing and attribution information

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)

Installation

1. Clone or download this repository

   https://github.com/Ktiseos-Nyx/plural_chat.git

2. Install:

     cd plural_chat
     pip install .

3. Run the application:

   plural-chat

Developer Mode Options

git clone https://github.com/Ktiseos-Nyx/plural_chat.git
cd plural_chat
pip install -e .
plural-chat

First Time Setup

1. Add Members - Use the Settings → Members tab to add your system members
2. Set Avatars - Add avatar images for visual identification
3. PluralKit Sync (Optional) - Import your existing PK system data via PK's API or via Json export via pk;export on Discord.
4. Choose Theme - Pick from 15+ modern themes in Settings

🎯 Proxy Detection

If you've imported from PluralKit or set up proxy tags, the app will automatically detect them:

• Type member: hello there → Auto-selects "member" and sends "hello there"
• Visual feedback shows when proxy is detected
• Clean messages without proxy tags in chat history

Future Foward Issue

Not 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!

🔧 PluralKit Integration

API Token Setup

1. Get your PK token from PluralKit Dashboard
2. Click "PluralKit Sync" in the app
3. Enter your token and test connection
4. Choose "Sync Members" or "Full Import"

What Gets Imported

• ✅ Member names and display names
• ✅ Pronouns and descriptions
• ✅ Proxy tags for auto-detection
• ✅ Avatar images (downloaded locally)
• ✅ Member colors and metadata
• ✅ Chat history (if present in export)

📁 File Structure

• app.db - Application settings and preferences
• system.db - Your system's members and chat history
• avatars/ - Downloaded avatar images
• *.json - Export files for sharing

🎨 Themes

Choose from these beautiful themes:

• superhero, darkly, solar, cyborg, vapor
• pulse, flatly, journal, litera, lumen
• minty, morph, sandstone, united, yeti

📤 Sharing Systems

Export your system:

• Click "Export System" → Save as JSON
• Share file with other plural folks
• Includes members, chat history, and settings

Import a system:

• Click "Import System" → Select JSON file
• Supports PluralKit exports (auto-detects and converts)
• Our export format is compatible for re-importing

🛠️ Development

Tech Stack

• Python 3.8+ - Core language
• ttkbootstrap - Modern UI framework
• SQLite - Local database
• Pillow - Image processing
• Requests - HTTP client for PluralKit API
• aiohttp - Asynchronous HTTP client
• aria2p - High-performance download manager

Project Structure

plural_chat/
├── main.py                 # Main application
├── database_manager.py     # SQLite database handling
├── pluralkit_api.py       # PK API integration
├── pluralkit_dialog.py    # PK sync UI
├── pk_export_parser.py    # PK export file parser
├── member_manager.py      # Member management UI
├── settings_manager.py    # Settings UI
├── about_dialog.py        # About dialog
├── requirements.txt       # Python dependencies
├── pyproject.toml        # Project configuration
└── LICENSE               # MIT license

🤝 Contributing

We welcome contributions from the plural community! Whether it's:

• 🐛 Bug reports
• 💡 Feature suggestions
• 🔧 Code improvements
• 📖 Documentation updates

Please read our Contributing Guide and Code of Conduct before getting started.

Want to see what's coming next? Check out our Development Roadmap to see planned features and find areas where you can help!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

For third-party components and attributions, see NOTICES.md.

💝 Credits

• Created by: Duskfall Portal Crew
• Inspired by: The amazing plural community
• Thanks to: PluralKit team for the fantastic API
• UI Framework: ttkbootstrap developers

🔗 Links

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Community discussions and Q&A
• PluralKit - The bot that inspired this project
• ttkbootstrap - Modern tkinter themes
• Support us - Help keep development going
• Ktiseos Nyx Discord - Development & AI Discord (Plural Friendly!)
• Earth & Dusk Media Discord - Our Twitch & Media Discord (PK enabled!)

---

Made with 💜 by and for the plural community