⚠️ Project Legacy Notice

This repository is now in LEGACY mode.
It has been succeeded by OctoMatrix, which features a more robust Multi-Communicator architecture, improved Cyberbrain memory system, and enhanced autonomous routing.

☀️🌙 Chat Agent Matrix 🐙

Take the Red Pill. Just watch out for the Octopus Sentinels...

📖 Project Introduction

Chat Agent Matrix is a remote collaboration interface dedicated to breaking limitations. It integrates powerful CLI AI engines (Claude Code / Google Gemini) into messaging applications, allowing you to command multiple autonomous Agents as a "Matrix Operator" anytime, anywhere.

This is not just a tool, but a digital ecosystem. Through dedicated agent_home isolated spaces, automated "constitution" guideline generation, and cross-agent collaboration mechanisms, we build a runtime environment for AI within tmux, allowing them to execute tasks like a real team, monitor each other, and even self-repair.

Core Values

• Command-Driven Operations: Directly control remote system CLI through conversations.
• Multi-Agent Matrix: Support running multiple AI agents simultaneously with independent responsibilities and spaces (e.g., Güpa based on Gemini, Chöd based on Claude Code).
• Autonomous Collaboration: Agents possess shared spaces and role awareness, implementing automated task delegation.
• Self-Healing: Agents can monitor each other's running status and automatically restart when stuck.

✨ What Can It Do For You?

🔧 Professional Operations

🤖 You: "Check database status, if load is high please have Chöd optimize indexes for me."
🛰️ Matrix: (Güpa checks status → discovers slow queries → puts logs in Shared Space → notifies Chöd)

🏠 Lifestyle Assistant

✈️ You: "I want to play in Kyoto for five days, please plan an itinerary and estimate budget, limit 50,000 TWD per person."
🛰️ Matrix:

1. Güpa plans itinerary → archives in Shared Space → notifies Chöd.
2. Chöd calculates budget → discovers overage → returns with adjustment suggestions.
3. Güpa corrects itinerary → resubmits → Chöd confirms compliance → outputs final report.

🚀 Supported Platforms

🚄 Quick Start

Step 1: Install Git and Clone the Project

# If Git is not installed yet, please install it first
# macOS: brew install git
# Ubuntu/Debian/WSL: sudo apt-get install git
# CentOS: sudo yum install git

# ⚠️ Windows Users: If WSL is not installed, please run the windows-wsl-setup script first

# Clone the Chat Agent Matrix project
git clone https://github.com/meso4444/chat-agent-matrix.git
cd chat-agent-matrix

Step 2: Choose Your Edition and Navigate to the Corresponding Directory

Select the messaging platform you want to use and enter the corresponding subdirectory:

# For Telegram edition
cd telegram

# Or for LINE edition
cd line

Step 3: Install and Run

For detailed installation, configuration, and startup instructions, please refer to the README.md in the subdirectory. Each edition has its own environment variable setup, dependency installation, and startup scripts.

⚖️ Platform Comparison

🧬 System Architecture

flowchart TD
    User["💊 Awakened"]
    Messenger["📱 Messenger (Telegram/Line)"]

    subgraph Matrix["🌀 The Matrix (tmux Session)"]
        direction TB

        Tunnel["🌐 Tunnel (ngrok/Cloudflare)"]
        Server["⚙️ Flask Server<br/>(Command Hub)"]

        subgraph Sentinels["🐙 Agent Cluster"]
            direction LR
            AgentA["Agent: Güpa"]
            AgentB["Agent: Chöd"]
        end

        Shared["🤝 Shared Space"]

        AgentA <--> Shared
        AgentB <--> Shared

        AgentA -.->|"Mutual Monitoring/Self-Healing"| AgentB
        AgentB -.->|"Mutual Monitoring/Self-Healing"| AgentA

        Tunnel --> Server
        Server -->|"Command Injection"| Sentinels
    end

    Notifier["📢 Notifier"]

    User <-->|"Command ⇄ Report"| Messenger
    Messenger <-->|"Webhook"| Tunnel
    Matrix --> Notifier
    Notifier -->|"API Push"| Messenger

💡 Core Design Concept

🛡️ Security Design Concept

👁️ Inner Reflection

"We build a Matrix for them within tmux, assigning them roles and memories, watching them 'think' they are autonomous. Perhaps, in doing so, we are merely reenacting our own condition... until we realize the truth, like finding the Red Pill."

📄 License

This project is licensed under the MIT License.