@pytt0n/moodle-rag

🚀 RAG (Retrieval-Augmented Generation) system for Moodle development with Claude Code CLI

Enhance your Moodle development workflow with semantic code search, intelligent context retrieval, and AI-powered assistance.

✨ Features

• 🔍 Semantic Code Search - Find code by meaning, not just text
• 🤖 7 AI Agents - Specialized assistants for Moodle development
• ⚡ 9 Slash Commands - Powerful development tools
• 📊 Analytics Dashboard - Monitor usage and performance
• 🎯 Smart Commits - Auto-generate conventional commit messages
• 📝 Auto Changelog - Generate changelogs from git history
• 🔄 Semantic Diff - Understand code changes by intent
• 💾 Local & Private - All processing happens on your machine

📦 Installation

Quick Install (Recommended)

# Navigate to your Moodle project
cd /path/to/your/moodle-project

# Install with one command (that's it!)
npx @pytt0n/moodle-rag install

That's literally it! No global installations, no complex setup. Just one command.

The installer automatically:

• ✅ Check system requirements (Python 3.8+, disk space)
• ✅ Download and setup the RAG system
• ✅ Create isolated Python virtual environment
• ✅ Install Python dependencies
• ✅ Download embeddings model (~80MB)
• ✅ Index your project (code, docs, tests)
• ✅ Start the RAG service

Time: ~10-15 minutes (first time, includes downloads)

Installation Options

# Custom port (default: 8000)
npx @pytt0n/moodle-rag install --port 8001

# Skip initial indexing (index later)
npx @pytt0n/moodle-rag install --skip-index

# Force reinstall (skip confirmation)
npx @pytt0n/moodle-rag install --force

# Specify project path
npx @pytt0n/moodle-rag install /path/to/project

🏗️ Architecture - Per-Project Installation

Each project gets its own independent RAG system. There is NO shared database between projects.

How It Works

When you run npx @pytt0n/moodle-rag install in a project:

/your/project/
  ├── .rag/                        ← Complete RAG system (per-project)
  │   ├── venv/                    ← Isolated Python environment
  │   ├── chromadb_data/           ← Project's vector database
  │   ├── services/                ← RAG service code
  │   ├── config.json              ← Project configuration
  │   └── logs/                    ← Service logs
  └── [your project files]

Multiple Projects Example

# Project 1: aula-virtual-infra
cd /home/user/aula-virtual-infra
npx @pytt0n/moodle-rag install --port 8000
# → Creates .rag/ with database indexing ONLY aula-virtual-infra code

# Project 2: otro-moodle
cd /home/user/otro-moodle
npx @pytt0n/moodle-rag install --port 8001
# → Creates .rag/ with database indexing ONLY otro-moodle code

Result: Two completely independent RAG systems, each with its own database and index.

Command Behavior

Commands like health, query, and stats work on the current directory's project:

# Check health of current project
cd /your/project
npx @pytt0n/moodle-rag health
# → Shows info for /your/project/.rag/

# Query current project
npx @pytt0n/moodle-rag query "How to validate CSV?"
# → Searches only current project's database

The system auto-detects the project from your current working directory.

🚀 Quick Start

1. Check Health

npx moodle-rag health

2. Query the System

npx moodle-rag query "How to validate CSV files in Moodle?"

3. View Statistics

npx moodle-rag stats

4. Open Dashboard

# Open in browser
open http://localhost:8000/docs

📚 Usage

Available Commands

# Install RAG system
npx moodle-rag install [project-path]

# Check service health
npx moodle-rag health

# Query the system
npx moodle-rag query "your question"

# View statistics
npx moodle-rag stats

# Reindex project
npx moodle-rag reindex

# Uninstall
npx moodle-rag uninstall

Command Options

Install

npx moodle-rag install \
  --port 8000 \
  --layers code,docs,tests \
  --skip-index

Query

npx moodle-rag query "your question" \
  -k 10 \
  -t 0.7 \
  -p 8000

Options:

• -k, --top-k - Number of results (default: 5)
• -t, --threshold - Similarity threshold 0-1 (default: 0.7)
• -p, --port - Service port (default: 8000)

🎯 Slash Commands (Claude Code CLI)

Once installed, use these commands in Claude Code:

/vuela-impact-analysis <file>

Analyze the impact of changes to a file

/vuela-impact-analysis local/sand_bulk_enrollment/validator.php

/vuela-rag-dashboard

Show complete RAG system dashboard

/vuela-rag-dashboard

/vuela-rag-similar <file>

Find similar code

/vuela-rag-similar validator.php

/vuela-rag-explain <module>

Explain a Moodle module

/vuela-rag-explain sand_bulk_enrollment --depth 2

/vuela-smart-commit

Generate commit message from staged changes

git add .
/vuela-smart-commit

/vuela-changelog <branch>

Generate changelog from branch

/vuela-changelog feature/OT-123 --ticket OT-123 --append

/vuela-rag-diff <branch>

Semantic diff between branches

/vuela-rag-diff feature/my-feature main

/vuela-rag-explore

Interactive codebase explorer

/vuela-rag-explore

/vuela-analytics

View analytics dashboard

/vuela-analytics

🤖 AI Agents

The system includes 7 specialized AI agents:

1. Moodle Development Expert - Validates Moodle best practices
2. Playwright Test Specialist - Suggests automated tests
3. UI/UX Design Validator - Validates Bootstrap/WCAG compliance
4. Architecture Decision Recorder - Captures technical decisions
5. Error Pattern Analyzer - Detects error patterns
6. Context Recovery - Recovers session context
7. Performance Optimizer - Finds performance issues

📊 REST API

The RAG service exposes a REST API:

# Health check
curl http://localhost:8000/health

# Query
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "How to validate CSV?", "top_k": 5}'

# Status
curl http://localhost:8000/status

# Reindex
curl -X POST http://localhost:8000/reindex

# Interactive docs
open http://localhost:8000/docs

⚙️ Configuration

Edit .rag/config.json to customize:

{
  "project_root": "/path/to/moodle",
  "rag_port": 8000,
  "rag_host": "127.0.0.1",

  "embeddings": {
    "model": "sentence-transformers/all-MiniLM-L6-v2",
    "batch_size": 32
  },

  "chunking": {
    "chunk_size": 1500,
    "chunk_overlap": 200
  },

  "indexing": {
    "excluded_dirs": ["node_modules", "vendor", "backup"],
    "max_file_size_mb": 1
  },

  "rag": {
    "top_k_results": 5,
    "similarity_threshold": 0.7
  }
}

After changes, restart the service:

cd .rag
pkill -f rag_service.py
venv/bin/python3 services/rag_service.py &

🔧 Requirements

• Python 3.8+
• Node.js 14+ (for npm)
• Disk Space 2GB minimum
• OS Linux, macOS, or Windows (WSL2)

📈 Performance

• Query latency: 150-250ms average
• Cache hit rate: 70-90% after warm-up
• Indexing speed: ~11 files/second
• Memory usage: 200-400MB (service)
• Disk usage: ~100-500MB (index)

🆘 Troubleshooting

Service won't start

# Check logs
tail -f .rag/logs/rag_service.log

# Verify Python
python3 --version  # Should be 3.8+

# Reinstall
npx moodle-rag uninstall --force
npx moodle-rag install

No query results

# Check index
npx moodle-rag stats

# Lower threshold
npx moodle-rag query "test" -t 0.3

# Reindex
npx moodle-rag reindex

Port already in use

# Use different port
npx moodle-rag install --port 8001

# Or kill existing process
lsof -i :8000
kill -9 <PID>

📚 Documentation

• Installation Guide - Detailed installation
• API Reference - REST API documentation
• Command Reference - All slash commands
• Configuration - Configuration options
• Architecture - System architecture

🤝 Contributing

Contributions welcome! Please read our Contributing Guide first.

# Fork the repo
git clone https://github.com/SuperPiTT/moodle-rag.git
cd moodle-rag

# Install dependencies
npm install

# Run tests
npm test

# Submit PR

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built with ChromaDB for vector storage
• Uses sentence-transformers for embeddings
• Powered by Claude Code CLI

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: Create an issue on GitHub

🌟 Star Us!

If you find this tool useful, please ⭐ star the repo!

Made with ❤️ by @pytt0n