🤖 R2-D2 Agent Orchestrator

Multi-agent orchestration system for coordinating AI-powered development workflows.

🌟 Overview

R2-D2 (Rapid 2-way Deployment of 2 DevOps) is a sophisticated multi-agent orchestration system that coordinates 4 specialized AI agents working in parallel on complex software development projects. Named after the beloved Star Wars droid, R2-D2 acts as the "Jedi Master" orchestrator, managing agent workstreams, tracking progress, and ensuring successful mission completion.

Key Features

• 🤖 4-Agent Parallel Workstream - Coordinate multiple AI agents simultaneously
• 📊 Real-Time TUI Dashboard - Monitor progress with a beautiful terminal dashboard
• 📋 162-Task Tracking System - Comprehensive task management and progress tracking
• 🧘 CodeRabbit CLI Integration - Automated code quality reviews
• 🌟 SOLID Principles Enforcement - Maintain high code quality standards
• 📚 Tech Knowledge Base - Indexed documentation for 31 technologies
• 🎯 Five-Layer Architecture - Structured approach to complex implementations

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/hanax-ai/Agents---Tools.git
cd Agents---Tools

# Install R2-D2 (requires sudo for global installation)
./scripts/core/install.sh

# Verify installation
r2d2 help

First Run

# Check system status
r2d2 status

# Start the dashboard
r2d2 start

# View the dashboard
r2d2 dashboard

👥 Agent Roster

R2-D2 coordinates 4 specialized agents, each with unique responsibilities:

Agent	Codename	Role	Tasks	Specialization
Agent 1	🧙‍♂️ Obi-Wan Kenobi	Backend REST API Developer	33	Ansible, FastAPI, PostgreSQL
Agent 2	🛡️ Luke Skywalker	Frontend Foundation Developer	43	React, TypeScript, TDD
Agent 3	👑 Princess Leia	Pages Integration Developer	51	UI Components, State Management
Agent 4	🧘 Yoda	Testing & Validation Specialist	35	E2E Testing, Code Review

Total Tasks: 162 tasks, ~107 estimated hours

📊 Architecture

R2-D2 implements a Five-Layer Architecture for complex software systems:

graph TB
    subgraph Layer1["🎨 LAYER 1: FRONTEND"]
        UI1["Open WebUI<br/>:8080"]
        UI2["shield-ag-ui<br/>(Planned)"]
        UI3["shield-dashboard<br/>(Planned)"]
    end

    subgraph Layer2["🚪 LAYER 2: API GATEWAY"]
        Gateway["LiteLLM Gateway<br/>:4000/v1/chat/completions<br/><br/>• MCP Tool Registry<br/>• RBAC Guardrails<br/>• Rate Limiting"]
    end

    subgraph Layer3["🔧 LAYER 3: TOOL EXECUTION"]
        MCP["FastMCP Server<br/>:8081/sse<br/><br/>7 Tools:<br/>• crawl_web<br/>• ingest_doc<br/>• qdrant_find<br/>• qdrant_store<br/>• lightrag_query<br/>• get_job_status<br/>• health_check"]
    end

    subgraph Layer4["🧠 LAYER 4: ORCHESTRATION"]
        Orch["Orchestrator<br/>:8000<br/><br/>• LightRAG Engine<br/>• Worker Pool<br/>• Redis Streams<br/>• LangGraph<br/>• Pydantic AI"]
    end

    subgraph Layer5["💾 LAYER 5: DATA"]
        Qdrant["Qdrant<br/>Vector DB<br/>:6333"]
        Postgres["PostgreSQL<br/>Knowledge Graph<br/>:5432"]
        Redis["Redis Streams<br/>Event Bus<br/>:6379"]
        Ollama1["Ollama Embeddings<br/>:11434"]
        Ollama2["Ollama LLMs<br/>:11434"]
    end

    UI1 & UI2 & UI3 -->|"HTTP + SSE"| Gateway
    Gateway -->|"MCP Protocol"| MCP
    MCP -->|"HTTP API"| Orch
    Orch --> Qdrant & Postgres & Redis & Ollama1 & Ollama2

    classDef frontend fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    classDef gateway fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef tools fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef orchestration fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef data fill:#fce4ec,stroke:#880e4f,stroke-width:2px

    class UI1,UI2,UI3 frontend
    class Gateway gateway
    class MCP tools
    class Orch orchestration
    class Qdrant,Postgres,Redis,Ollama1,Ollama2 data

Loading

Architecture Layers

1. Frontend Layer - User interfaces (Open WebUI, AG-UI, Dashboard)
2. API Gateway Layer - LiteLLM with MCP tool registry and RBAC guardrails
3. Tool Execution Layer - FastMCP server with 7 production-ready tools
4. Orchestration Layer - FastAPI orchestrator with LightRAG and worker pools
5. Data Layer - PostgreSQL, Qdrant, Redis, and Ollama LLM nodes

For complete architecture details including data flows, circuit breaker patterns, and system topology, see docs/architecture/five-layer-design.md.

🔧 Usage

Basic Commands

r2d2 start              # Start dashboard in background
r2d2 stop               # Stop dashboard
r2d2 restart            # Restart dashboard
r2d2 status             # Show system status
r2d2 dashboard          # Open dashboard viewer (foreground)
r2d2 monitor            # Show monitoring setup guide

Agent Monitoring

Open separate terminals for each agent:

# Terminal 1: Main Dashboard
r2d2 dashboard

# Terminal 2-5: Individual Agents
r2d2-obi                # Monitor Obi-Wan (Backend)
r2d2-luke               # Monitor Luke (Frontend)
r2d2-leia               # Monitor Leia (Pages)
r2d2-yoda               # Monitor Yoda (Testing)

Progress Tracking

# View all progress
r2d2-progress

# View incomplete tasks
r2d2-tasks

# View agent logs
r2d2-logs

📚 Documentation

Quick Links

• Installation Guide - Complete installation instructions
• Quick Reference - Command reference
• Agent Onboarding - Comprehensive agent briefing
• Monitoring Guide - Real-time monitoring setup
• Architecture Overview - System design

Documentation Structure

docs/
├── getting-started/     # Installation & quick start guides
├── agent-guides/        # Agent-specific documentation
├── operations/          # Operational guides & monitoring
├── reference/           # Command & API reference
├── architecture/        # Architecture & design documents
└── contributing/        # Contribution guidelines

🎯 Use Cases

R2-D2 excels at coordinating complex software development projects:

• Multi-Agent Development - Coordinate 2-10 AI agents on parallel workstreams
• Five-Layer Architecture - Implement complete frontend-to-data-layer systems
• Test-Driven Development - Enforce TDD with contract-first approach
• Code Quality Assurance - Automated reviews with CodeRabbit CLI
• Real-Time Monitoring - Track progress across all agents simultaneously

🛠️ Technology Stack

Core Technologies

• Python 3.11+ - Dashboard and tracking scripts
• Bash - Orchestration and monitoring scripts
• Rich - Terminal UI library
• Git - Version control and collaboration

Supported Tech Stack (31 Technologies Indexed)

• Backend: FastAPI, Ansible, PostgreSQL, Redis, Ollama
• Frontend: React, Next.js, TypeScript, Zod, Zustand
• AI/ML: LiteLLM, LightRAG, LangGraph, Pydantic AI
• Data: Qdrant, Prisma, PostgreSQL, Redis
• Tools: Docker, Nginx, CodeRabbit, Crawl4AI, Docling

See docs/reference/tech-kb-index.md for complete index.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Clone and install in development mode
git clone https://github.com/hanax-ai/Agents---Tools.git
cd Agents---Tools
./scripts/setup/install.sh --dev

# Run tests
python -m pytest tests/

# Lint scripts
shellcheck scripts/**/*.sh

Code Standards

• SOLID Principles - All code must follow SOLID OOP principles
• Test-Driven Development - Write tests before implementation
• MCP Pattern - Write operations via Gateway → MCP → Orchestrator
• Code Review - All PRs reviewed by CodeRabbit + humans

📋 Project Status

• Current Version: 1.0.0
• Status: Production Ready ✅
• Tasks Tracked: 162 tasks
• Agents Active: 4 agents
• Demo Checkpoints: 3 milestones

Demo Checkpoints

• Demo 1 (Day 2): Foundation - API infrastructure + MCP validation
• Demo 2 (Day 6): Integration - All pages with real data
• Demo 3 (Day 7): Production - Tests passing, deployment validated

🔗 Related Projects

R2-D2 orchestrates multiple related projects:

• hx-citadel-ansible - Backend infrastructure (Ansible)
• citadel-shield-ui - Frontend React application
• ag-ui-protocol - AG-UI protocol library

These projects are coordinated via the GitHub Project.

📄 License

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

🙏 Acknowledgments

• Anthropic - Claude AI for agent coordination
• OpenAI - GPT models for agent capabilities
• CodeRabbit - Automated code review
• Star Wars - Inspiration for agent codenames

📞 Support

• Documentation: hana-x.ai
• Issues: GitHub Issues
• Email: [email protected]

---

🤖 R2-D2 standing by. May the Force be with you!

Built with ❤️ by the HANA-X AI Team