Matrix bot for CI/CD automation through chat 🚀

---

ChatrixCD connects Matrix chat with Semaphore UI to automate CI/CD tasks right from your chat room. It's like having a friendly bot coworker who handles your deployments! 🤖

🎯 Quick Start

Just want to run it? Here's the fastest path:

1. Install

Linux (No Python needed!):

# Download the binary for your architecture
wget https://github.com/CJFWeatherhead/ChatrixCD/releases/latest/download/chatrixcd-linux-x86_64.dist.tar.gz
tar -xzf chatrixcd-linux-x86_64.dist.tar.gz
cd chatrixcd-linux-x86_64.dist

From Source (Windows/macOS/Linux):

pip install -e .

2. Configure

Create config.json:

{
  "matrix": {
    "homeserver": "https://matrix.org",
    "user_id": "@mybot:matrix.org",
    "auth_type": "password",
    "password": "your-secure-password"
  },
  "semaphore": {
    "url": "https://semaphore.example.com",
    "api_token": "your-api-token"
  }
}

3. Run

./chatrixcd              # Linux binary
# OR
chatrixcd                # From source install

That's it! Invite your bot to a Matrix room and start running tasks. 🎉

📚 Need More?

• Full Installation Guide - Detailed setup for all platforms
• Configuration Reference - All config options explained
• Quick Start Tutorial - Step-by-step walkthrough
• Complete Documentation - Everything you need to know

✨ Key Features

• 🔐 End-to-End Encryption - Secure Matrix rooms supported
• 🚀 Semaphore Integration - Start, monitor, and manage CI/CD tasks
• 💬 Chat Commands - Simple !cd run, !cd status, !cd logs
• 🎯 Smart Confirmations - Thumbs up/down reactions or text
• 🔖 Custom Aliases - Create shortcuts for common tasks
• 🖥️ Interactive TUI - Terminal UI for bot management
• 🎭 Fun Personality - Sassy responses with emoji (never rude!)

🎮 Basic Commands

!cd help                           # Show all commands
!cd projects                       # List projects
!cd templates 1                    # List templates for project 1
!cd run 1 5                        # Run template 5 in project 1
!cd status                         # Check task status
!cd logs                           # View task logs
!cd stop 123                       # Stop task 123

🔧 Command Line Options

chatrixcd                          # Run with TUI (default)
chatrixcd -L                       # Log-only mode (no TUI)
chatrixcd -D                       # Daemon mode (background)
chatrixcd -C                       # Enable colored output
chatrixcd -v                       # Verbose logging
chatrixcd -s                       # Show current config
chatrixcd -c custom.json           # Use custom config file

🏗️ Architecture

┌─────────────┐         ┌──────────────┐         ┌────────────────┐
│   Matrix    │ ◄────── │  ChatrixCD   │ ──────► │  Semaphore UI  │
│   Server    │         │     Bot      │         │  REST API      │
└─────────────┘         └──────────────┘         └────────────────┘
     Chat                   Commands                   CI/CD Tasks

ChatrixCD sits between Matrix and Semaphore, translating chat commands into API calls and streaming results back to your room.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Found a bug? Open an issue

📄 License

GNU General Public License v3.0 - See LICENSE

🙏 Acknowledgments

• Built with matrix-nio
• Integrates with Semaphore UI
• Inspired by matrix-commander for device verification and encryption handling patterns

AI/LLM Contributions

Important Notice: Significant portions of this codebase were developed with assistance from AI/LLM tools, including:

• GitHub Copilot for code generation and completion
• Large Language Models (LLMs) for architecture design, documentation, and implementation
• AI-assisted code review and testing strategies

While AI tools accelerated development, all code has been reviewed, tested, and validated by human developers. Users should be aware that:

• Code patterns and documentation may reflect AI-generated content
• The project follows standard software engineering practices for testing and quality assurance
• Contributions and improvements from the community are welcome and encouraged

This transparency aligns with emerging best practices for AI-assisted software development.

---

Ready to automate your CI/CD through chat? Get Started →