For further Info on how this Project has evolved, read Vision.md in the master Branch.
Maestro is a high-performance, local-first AI agent framework designed for complex software engineering tasks. It utilizes a decentralized multi-agent architecture (Forest Architecture) to plan, execute, and validate code changes with surgical precision using small, fast local models (7B to 14B parameters).
- 🌲 Forest Architecture (v2): A strategic pipeline of specialized agents (Raven, Luna, Trees) that eliminates "Validator Fatigue."
- 🛡️ Surgical Precision: Forced output formatting via strict XML/Markdown parsing or vLLM guided decoding.
- 🔄 The Rescue Loop: Advanced error triage that compacts stacktraces into surgical fix instructions and fetches missing context via CXM RAG.
- 🖥️ Integrated UI: A modern React/FastAPI dashboard to visualize agent planning and execution in real-time.
- 🚀 Optimized for Consumer GPUs: Specialized memory handling for Ollama (keep-alive) and vLLM (ROCm/Vulkan support).
- 🏗️ SWE-bench Pro Ready: Built-in adapters for evaluating agent performance on real-world enterprise repositories.
Maestro operates as a transparent, auditable pipeline of specialized agents:
- 🦅 Raven (The Planner): Strategic architect. Analyzes requests and creates a
ForestPlan(JSON) broken down into isolatedTreeTaskelements. It delegates but never writes code. - 🌕 Luna (The Orchestrator & Monitor): The heartbeat of the system. Manages the execution loop, evaluates repository state, performs Error Compaction, and handles context injection.
- 🌲 Trees (The Workers): Specialized coding agents. They operate with a "Blank Slate" memory per task to prevent context bloating and maintain focus.
- 🧲 CXM (Context Machine): An external RAG bridge that fetches deep architectural context during failures (Rescue Harvesting).
- Python 3.10+
- Ollama or vLLM installed and running.
- (Optional) CXM for deep project context.
# Clone the repository
git clone https://github.com/Joeavaib/maestro.git
cd maestro
# Install dependencies
pip install -e .
# Setup UI dependencies (optional)
cd maestro_ui/backend && pip install -r requirements.txt
cd ../frontend && npm install
cd ../..The easiest way to use Maestro is through the integrated dashboard:
./mystic/start_maestro_ui.sh- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
For direct command-line control:
# Run a new task
python -m maestro.cli run --repo ./your-project --request "Add unit tests for auth.py" --cfg mystic/cfg.json --forest
# Preview the changes in the sandbox
python -m maestro.cli preview --cmd "pytest"
# Accept and apply the changes to your main repository
python -m maestro.cli acceptmystic/cfg.json: Defines the LLM backends (Ollama/vLLM) and models used for planning and execution.models/registries.json: Maps internal model names to your local provider (HuggingFace, Ollama, etc.).
Maestro is built for reliability. Follow these rules for all contributions:
- Tests first: ALWAYS run tests after changes:
pytest tests/ - Reproduction: For bug fixes, reproduce with a test case first.
- Clean Code: Use Google-style docstrings and strict type hints.
maestro/: Core logic (CLI, Orchestrators, LLM connectors).maestro_ui/: React frontend and FastAPI backend.benchmarks/: SWE-bench Pro adapters and evaluation tools.docs/: Detailed architectural specs and future visions.tests/: Comprehensive test suite.
🔥🚀🤯🎉😎✨ MAGIC AI AGENT STUFF HAPPENS HERE 🛠️⚡🤖💥🧠🔥 (But strictly scientifically above this line!) 🤓📈