ChatrixCD

Matrix bot for CI/CD automation through chat

---

Features

• 🔐 Native Matrix Authentication: Support for password and OIDC/SSO authentication with Matrix servers
• 🔒 E2E Encryption: Full support for end-to-end encrypted Matrix rooms with device verification
• 🖥️ Interactive TUI: Dual TUI modes - Turbo Vision-style (default) with menu bar and 3D windows, or classic interface
• 🧵 Threaded Responses: All bot replies are threaded for organized conversations
• 👍 Reaction Confirmations: Quick interactions with emoji reactions (👍/👎) for confirmations
• 🎭 Fun Personality: Varied greetings and sassy responses with emoji throughout
• 🚀 Semaphore UI Integration: Start and monitor CI/CD tasks via chat commands
• 📊 Real-time Updates: Automatic status updates for running tasks
• 🎯 Command-based Interface: Easy-to-use command system for task management
• 🔖 Command Aliases: Create custom shortcuts for frequently used commands
• ✅ Task Confirmation: Required confirmation before executing tasks with template details
• 🎨 Rich Formatting: Markdown and HTML formatting in messages with emoji support
• 🧠 Smart Parameters: Auto-fill project/template IDs when only one option available
• 📝 Enhanced Logs: Formatted output for Ansible and Terraform with intelligent tailing
• 🔧 Flexible Configuration: Support for HJSON config files (JSON with comments) with automatic migration
• ✅ Configuration Validation: Built-in schema validation with clear error messages
• 🔄 Auto-Migration: Automatic upgrade of configuration files when new features are added

Quick Links

• Installation Guide
• Quick Start
• Configuration
• Architecture
• Contributing
• Security Policy

Getting Started

ChatrixCD makes it easy to manage CI/CD tasks through Matrix chat. Choose your installation method:

Quick Install (Pre-built Binary)

No Python required! Download the standalone executable:

Linux (x86_64):

wget https://github.com/CJFWeatherhead/ChatrixCD/releases/latest/download/chatrixcd-linux-x86_64
chmod +x chatrixcd-linux-x86_64
./chatrixcd-linux-x86_64

macOS (Universal):

wget https://github.com/CJFWeatherhead/ChatrixCD/releases/latest/download/chatrixcd-macos-universal
chmod +x chatrixcd-macos-universal
./chatrixcd-macos-universal

Windows: Download chatrixcd-windows-x86_64.exe

See all platforms and architectures

Install from Source

For development or customization:

Install from Source

For development or customization:

git clone https://github.com/CJFWeatherhead/ChatrixCD.git
cd ChatrixCD
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

For detailed installation instructions, see the Installation Guide.

Basic Usage

Once installed and configured, you can:

1. Invite the bot to your Matrix room
2. List available projects with !cd projects
3. View templates with !cd templates <project_id>
4. Start tasks with !cd run <project_id> <template_id>
5. Monitor progress automatically

Installation

Prerequisites

• For pre-built binaries: None! Just download and run
• For source installation: Python 3.12 or higher (3.12, 3.13, 3.14 supported)
• Access to a Matrix homeserver
• Access to a Semaphore UI instance with API access

Download Pre-built Binaries

Choose your platform:

• Linux: x86_64

  i686

  ARM64

• Windows: x86_64

  ARM64

• macOS: Universal (Intel + Apple Silicon)

Quick Install from Source

git clone https://github.com/CJFWeatherhead/ChatrixCD.git
cd ChatrixCD
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

For detailed installation instructions, see the Installation Guide.

Support

• GitHub Issues - Bug reports and feature requests
• Support Guide - Troubleshooting and getting help

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.