{"id":28426017,"url":"https://github.com/xiaoconstantine/maestro","last_synced_at":"2026-04-07T13:31:11.632Z","repository":{"id":281738111,"uuid":"924261786","full_name":"XiaoConstantine/maestro","owner":"XiaoConstantine","description":"Local AI code review assistant built on dspy-go.","archived":false,"fork":false,"pushed_at":"2026-03-08T02:44:32.000Z","size":1548,"stargazers_count":28,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-08T07:41:45.224Z","etag":null,"topics":["agent","claude-code","gemini-cli","golang","llm","local"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XiaoConstantine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-29T17:39:20.000Z","updated_at":"2026-03-05T05:32:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"fc537e4c-5b1d-413d-b487-666bbc4075a9","html_url":"https://github.com/XiaoConstantine/maestro","commit_stats":null,"previous_names":["xiaoconstantine/maestro"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/XiaoConstantine/maestro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XiaoConstantine%2Fmaestro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XiaoConstantine%2Fmaestro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XiaoConstantine%2Fmaestro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XiaoConstantine%2Fmaestro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XiaoConstantine","download_url":"https://codeload.github.com/XiaoConstantine/maestro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XiaoConstantine%2Fmaestro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31515144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","claude-code","gemini-cli","golang","llm","local"],"created_at":"2025-06-05T11:08:19.448Z","updated_at":"2026-04-07T13:31:11.625Z","avatar_url":"https://github.com/XiaoConstantine.png","language":"Go","readme":"# Maestro - Advanced AI-Powered Code Review Assistant\n\nMaestro is an intelligent code review assistant built with DSPy-Go that provides comprehensive, file-level code analysis for GitHub pull requests. It combines advanced AST parsing, semantic analysis, and LLM-powered reasoning to deliver high-quality, actionable code review feedback.\n\n\n## 🏗️ Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│                              USER INTERFACE                                     │\n│  ┌─────────────────┐  ┌─────────────────────────────┐  ┌─────────────────────┐  │\n│  │    CLI Mode     │  │   TUI v2 (Bubbletea)        │  │    GitHub API       │  │\n│  │                 │  │  ┌─────────────────────────┐│  │                     │  │\n│  │  • Spinner      │  │  │ Vim Keybindings        ││  │  • PR Changes       │  │\n│  │  • Progress     │  │  │ Command Palette        ││  │  • Review Comments  │  │\n│  │  • Prompts      │  │  │ File Tree / TODOs      ││  │  • OAuth2           │  │\n│  │                 │  │  │ Review Display         ││  │                     │  │\n│  └────────┬────────┘  │  └─────────────────────────┘│  └──────────┬──────────┘  │\n│           │           └──────────────┬──────────────┘             │             │\n└───────────┼──────────────────────────┼────────────────────────────┼─────────────┘\n            │                          │                            │\n            ▼                          ▼                            ▼\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│                           MAESTRO SERVICE                                       │\n│               (Singleton - created once per session)                            │\n│                                                                                 │\n│  ┌─────────────────────────────────────────────────────────────────────────┐   │\n│  │                         AgentPool (Persistent)                          │   │\n│  │  ┌─────────────────────┐              ┌─────────────────────────────┐   │   │\n│  │  │   PRReviewAgent     │              │   UnifiedReActAgent (QA)    │   │   │\n│  │  │   (persistent)      │              │   (persistent, shared mem)  │   │   │\n│  │  └─────────────────────┘              └─────────────────────────────┘   │   │\n│  │                                                                          │   │\n│  │  ┌─────────────────────┐              ┌─────────────────────────────┐   │   │\n│  │  │   ClaudeProcessor   │              │   GeminiProcessor           │   │   │\n│  │  │   (Sonnet 4.5)      │              │   (Gemini 3 Pro Preview)    │   │   │\n│  │  └─────────────────────┘              └─────────────────────────────┘   │   │\n│  └─────────────────────────────────────────────────────────────────────────┘   │\n│                                     │                                           │\n│  ┌──────────────────────────────────┴───────────────────────────────────────┐  │\n│  │                      ProcessRequest Router                                │  │\n│  │   /review → ReviewAgent    /ask → QAAgent    /claude    /gemini          │  │\n│  └──────────────────────────────────────────────────────────────────────────┘  │\n└─────────────────────────────────────────────────────────────────────────────────┘\n                                      │\n          ┌───────────────────────────┼───────────────────────────┐\n          ▼                           ▼                           ▼\n┌─────────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐\n│    REVIEW ENGINE    │    │   UNIFIED REACT      │    │   SEARCH ENGINE     │\n│                     │    │      AGENT           │    │                     │\n│ • Chunker           │    │ • Iterative Search   │    │ • Semantic Search   │\n│ • Workflow Chain    │    │ • Tool Selection     │    │ • Hybrid Matching   │\n│ • Parallel Review   │    │ • Context Management │    │ • Code Indexing     │\n│ • 120 Workers       │    │ • Quality Tracking   │    │                     │\n└─────────────────────┘    └──────────────────────┘    └─────────────────────┘\n          │                           │                           │\n          └───────────────────────────┼───────────────────────────┘\n                                      ▼\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│                          INTELLIGENCE LAYER                                     │\n│  ┌────────────────────┐  ┌───────────────────┐  ┌────────────────────────────┐  │\n│  │   Sgrep Search     │  │     RAG Store     │  │   LLM Orchestration        │  │\n│  │                    │  │                   │  │       (DSPy-Go)            │  │\n│  │ • Semantic Search  │  │ • Guidelines      │  │                            │  │\n│  │ • Hybrid Search    │  │ • Code Patterns   │  │  • Anthropic / Gemini      │  │\n│  │ • Code Indexing    │  │ • Similarity      │  │  • Ollama / LLaMA.cpp      │  │\n│  └─────────┬──────────┘  └─────────┬─────────┘  └─────────────┬──────────────┘  │\n└────────────┼───────────────────────┼──────────────────────────┼─────────────────┘\n             │                       │                          │\n             ▼                       ▼                          ▼\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│                             DATA LAYER                                          │\n│  ┌────────────────────────┐  ┌─────────────────────┐  ┌──────────────────────┐  │\n│  │   SQLite + sqlite-vec  │  │  Embedding Router   │  │   Shared Memory      │  │\n│  │                        │  │                     │  │   (Configurable)     │  │\n│  │  • Vector Storage      │  │  • Local (Sgrep)    │  │  • InMemory          │  │\n│  │  • Metadata Index      │  │  • Cloud Fallback   │  │  • SQLite (optional) │  │\n│  │  • Pattern Matching    │  │  • Smart Routing    │  │                      │  │\n│  └────────────────────────┘  └─────────────────────┘  └──────────────────────┘  │\n└─────────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 🎯 Core Features\n\n### **Advanced Context Analysis**\n- **AST-Based Parsing**: Deep Go code structure analysis including packages, imports, types, and functions\n- **File-Level Context**: Comprehensive understanding of code relationships and dependencies  \n- **Semantic Purpose Detection**: Automatic identification of code chunk functionality\n- **Enhanced Chunk Metadata**: Rich context with 15+ lines of surrounding code\n\n### **Intelligent Review Pipeline**\n- **Multi-Stage Processing**: Context preparation → Analysis → Validation → Aggregation\n- **File-Level Aggregation**: Groups related issues by file with intelligent deduplication\n- **Advanced Debugging**: Comprehensive logging and performance metrics\n- **Configurable Processing**: Environment variables for fine-tuning behavior\n\n### **GitHub Integration**\n- **Seamless PR Workflow**: Direct integration with GitHub pull request comments\n- **Bulk Processing**: Efficient handling of large PRs with parallel processing\n- **Real-time Feedback**: Live processing status and progress indicators\n\n### **Terminal UI (TUI v2)**\n- **Modern Framework**: Built on Bubbletea v2 + Lipgloss v2 with real-time updates\n- **Vim-Style Navigation**: Full Vim keybindings with Normal, Insert, Visual, Command, and Search modes\n- **Multi-Mode Interface**: Input mode, Review mode, and Dashboard mode\n- **Fuzzy Command Palette**: Quick command access with autocomplete and history\n- **PR Review Display**: Inline comments grouped by file with severity-based color coding\n- **File Tree Explorer**: Navigate repository with expand/collapse and filtering\n- **Task Tracking**: Built-in TODO list for agent planning visibility\n- **Split-Pane Layout**: IDE-like interface with configurable panels\n\n### **Semantic Code Search (Sgrep)**\n- **Semantic Understanding**: Search code by meaning, not just keywords\n- **Hybrid Search**: Combine semantic + keyword matching for precise results\n- **Embedding Provider**: Local embeddings via nomic-embed-text model (768 dimensions)\n- **Guideline Discovery**: Semantic search for code guidelines and patterns\n- **Agent Integration**: Available as a tool for ReAct agents during reasoning\n\n### **Unified Agent Architecture**\n- **MaestroService**: Singleton service created once per session for unified request handling\n- **Persistent Agents**: Agent pool maintains persistent agents across requests (no ad-hoc creation)\n- **Shared Memory**: Configurable memory backend (InMemory or SQLite) shared across agents\n- **Request Routing**: Single entry point (`ProcessRequest`) routes `/review`, `/ask`, `/claude`, and `/gemini` commands\n- **Multi-Model Subagents**: Claude (Sonnet 4.5) and Gemini (3 Pro Preview) available as subagents with file-based context sharing\n\n### **Flexible Model Support**\n- **Multiple Backends**: Anthropic Claude, Google Gemini, Local models (Ollama, LLaMA.cpp)\n- **Unified Embedding**: Consistent vector representations for code and guidelines\n- **Performance Optimization**: Intelligent model selection and caching\n\n## 🛠️ Enhanced Technical Capabilities\n\n### **Review Dimensions**\n- **Code Defects**: Logic flaws, error handling issues, resource management\n- **Security Vulnerabilities**: Injection attacks, insecure data handling, authentication issues\n- **Maintainability**: Code organization, documentation, naming conventions, complexity\n- **Performance**: Algorithmic efficiency, data structures, resource utilization\n\n### **Advanced Features**\n- **Vector-Based Similarity**: SQLite with sqlite-vec for efficient code pattern matching\n- **Deduplication Engine**: Levenshtein distance-based issue consolidation\n- **Context Extraction**: Go AST parsing with semantic analysis\n- **Background Indexing**: Non-blocking repository analysis\n- **Parallel Processing**: Concurrent chunk analysis for performance\n\n## 📦 Getting Started\n\n### **Prerequisites**\n- Go 1.24.2 or higher\n- SQLite with sqlite-vec extension\n- GitHub API access token\n- Supported LLM backend (Claude, Gemini, or local model)\n- For local models: llama.cpp installed (can be automated with `make setup`)\n\n### **Installation**\n\n```bash\n# Clone the repository\ngit clone https://github.com/XiaoConstantine/maestro.git\ncd maestro\n\n# Install dependencies\ngo mod download\n\n# Build the binary\ngo build -o maestro\n\n# Set up GitHub token\nexport MAESTRO_GITHUB_TOKEN=your_github_token\n```\n\n### **Local Model Setup (Optional)**\n\nFor using local LLM models with llama.cpp:\n\n```bash\n# One-time setup: Install llama.cpp and download models\n# Creates ~/.maestro/models and downloads:\n# - nomic-embed-text-v1.5.Q8_0.gguf (embedding model)\n# - Qwen3-1.7B-Q8_0.gguf (inference model)\nmake setup\n\n# Start both llama servers in separate tmux sessions\n# Embedding server runs on port 8080\n# LLM server runs on port 8081\nmake local\n\n# View server logs\ntmux attach -t embedding  # Embedding server logs\ntmux attach -t llm        # LLM server logs\n```\n\n### **Quick Start**\n\n```bash\n# Launch TUI (default when no PR specified)\n./maestro\n\n# Or explicitly with interactive flag\n./maestro -i\n\n# Direct CLI usage for a specific PR\n./maestro --owner=username --repo=repository --pr=123\n\n# In TUI mode, use slash commands:\nmaestro\u003e /review 123          # Review PR #123\nmaestro\u003e /ask how does auth work?  # Ask about the codebase\n\n# With enhanced debugging\nexport MAESTRO_LOG_LEVEL=debug\nexport MAESTRO_RAG_DEBUG_ENABLED=true\n./maestro --owner=username --repo=repository --pr=123 --verbose\n```\n\n## ⚙️ Configuration\n\n### **Environment Variables**\n\n#### **Core Configuration**\n```bash\nMAESTRO_GITHUB_TOKEN=your_token          # GitHub API access\nMAESTRO_LOG_LEVEL=debug                  # Logging level (debug, info, warn, error)\nANTHROPIC_API_KEY=your_key               # For /claude subagent (Claude Sonnet 4.5)\nGOOGLE_API_KEY=your_key                  # For /gemini subagent (Gemini 3 Pro Preview)\n```\n\n#### **Enhanced Processing (Phase 4.1)**\n```bash\n# File-level aggregation\nMAESTRO_FILE_AGGREGATION_ENABLED=true    # Enable file-level result aggregation\nMAESTRO_DEDUPLICATION_THRESHOLD=0.8      # Issue similarity threshold (0.0-1.0)\n\n# AST Context extraction  \nMAESTRO_CONTEXT_EXTRACTION_ENABLED=true  # Enable AST-based context extraction\nMAESTRO_CHUNK_CONTEXT_LINES=15          # Lines of context around chunks\nMAESTRO_ENABLE_SEMANTIC_CONTEXT=true     # Enable semantic purpose detection\nMAESTRO_ENABLE_DEPENDENCY_ANALYSIS=true  # Enable dependency tracking\n\n# Advanced debugging\nMAESTRO_RAG_DEBUG_ENABLED=true           # RAG retrieval debugging\nMAESTRO_LLM_RESPONSE_DEBUG=true          # LLM response debugging  \nMAESTRO_SIMILARITY_LOGGING=true          # Similarity score logging\n```\n\n#### **Sgrep / Local Embeddings**\n```bash\nMAESTRO_LOCAL_EMBEDDING_ENABLED=true     # Enable local embeddings\nMAESTRO_LOCAL_EMBEDDING_PROVIDER=sgrep   # Provider: sgrep, ollama, llamacpp\nMAESTRO_LOCAL_EMBEDDING_MODEL=nomic-embed-text  # Embedding model (768 dims for sgrep)\n```\n\n#### **Feature Toggles**\n```bash\nMAESTRO_ENHANCED_REASONING=true          # Enhanced reasoning capabilities\nMAESTRO_COMMENT_REFINEMENT=true          # Comment refinement processing\nMAESTRO_CONSENSUS_VALIDATION=true        # Consensus validation\n```\n\n### **Command Line Options**\n- `--github-token`: GitHub personal access token\n- `--owner`: Repository owner\n- `--repo`: Repository name\n- `--pr`: Pull request number to review\n- `--model`: LLM backend selection\n- `--index-workers`: Concurrent indexing workers\n- `--review-workers`: Concurrent review workers\n- `--verbose`: Enable detailed logging\n- `-i, --interactive`: Launch TUI (also default when no PR specified)\n\n### **TUI Commands**\n- `/help`: Show available commands\n- `/review \u003cpr\u003e`: Review a pull request\n- `/ask \u003cquestion\u003e`: Ask questions about the repository (uses ReAct agent)\n- `/claude \u003cprompt\u003e`: Send prompt to Claude Sonnet 4.5 subagent\n- `/gemini \u003cprompt\u003e`: Send prompt to Gemini 3 Pro Preview subagent\n- `/clear`: Clear conversation history\n- `/exit`, `/quit`: Exit the TUI\n\n### **TUI Keybindings**\n\n#### **Normal Mode**\n| Key | Action |\n|-----|--------|\n| `h/j/k/l` or arrows | Navigate |\n| `i` | Enter Insert mode |\n| `v` | Enter Visual mode |\n| `:` | Enter Command mode |\n| `/` | Enter Search mode |\n| `g` / `G` | Jump to top / bottom |\n| `ctrl+u` / `ctrl+d` | Page up / down |\n| `tab` | Cycle focus between panes |\n| `ctrl+b` | Toggle file tree |\n| `ctrl+t` | Toggle TODO panel |\n| `enter` | Select / expand item |\n| `space` | Expand/collapse in file tree |\n| `x` | Mark TODO complete |\n| `q` / `ctrl+c` | Quit |\n\n#### **Review Mode**\n| Key | Action |\n|-----|--------|\n| `j/k` | Navigate comments |\n| `space` | Expand/collapse file groups |\n| `enter` / `l` | Toggle detail view |\n| `h` | Close detail view |\n| `tab` | Switch to input |\n| `esc` | Clear review results |\n\n### **Model Selection**\n\n```bash\n# Use local LLaMA.cpp\n./maestro --model=\"llamacpp:\" --pr=123\n\n# Use Ollama with specific model\n./maestro --model=\"ollama:codellama\" --pr=123\n\n# Use Anthropic Claude\n./maestro --model=\"anthropic:claude-3-sonnet\" --api-key=your_key --pr=123\n\n# Use Google Gemini\n./maestro --model=\"google:gemini-pro\" --api-key=your_key --pr=123\n```\n\n## 📊 Performance \u0026 Metrics\n\n### **Current Scale**\n- **Codebase**: 27,000+ lines across 17 internal packages\n- **Dependencies**: DSPy-Go v0.66.0, SQLite-vec, GitHub API v68\n- **Processing**: Handles 300+ chunks per PR with file-level aggregation\n- **Performance**: ~500ms average per chunk with parallel processing\n\n### **Recent Improvements**\n- **Multi-Model Subagents**: `/claude` (Sonnet 4.5) and `/gemini` (Gemini 3 Pro Preview) commands with file-based context sharing\n- **Unified Architecture**: MaestroService singleton with persistent AgentPool\n- **TUI v2**: Modern Bubbletea v2 interface with Vim keybindings and multi-mode support\n- **Sgrep Integration**: Semantic code search for intelligent code understanding\n- **Shared Memory**: Configurable memory backend for cross-request context\n- **File Aggregation**: 371 chunks → 21 files (proper grouping)\n- **Context Enhancement**: 5 → 15+ lines of chunk context\n- **Debug Visibility**: Comprehensive RAG and processing metrics\n- **Lint Compliance**: Zero golangci-lint issues\n\n## 🔬 Advanced Usage\n\n### **Debug Mode**\n```bash\n# Full debug mode with all logging enabled\nexport MAESTRO_LOG_LEVEL=debug\nexport MAESTRO_RAG_DEBUG_ENABLED=true\nexport MAESTRO_LLM_RESPONSE_DEBUG=true\nexport MAESTRO_SIMILARITY_LOGGING=true\nexport MAESTRO_CONTEXT_EXTRACTION_ENABLED=true\n\n./maestro --owner=user --repo=project --pr=123 --verbose\n```\n\n### **Performance Tuning**\n```bash\n# Optimize for speed\nexport MAESTRO_CHUNK_CONTEXT_LINES=10\nexport MAESTRO_DEDUPLICATION_THRESHOLD=0.9\n\n# Optimize for accuracy  \nexport MAESTRO_CHUNK_CONTEXT_LINES=20\nexport MAESTRO_DEDUPLICATION_THRESHOLD=0.7\nexport MAESTRO_ENABLE_DEPENDENCY_ANALYSIS=true\n```\n\n## 📄 License\n\nMaestro is released under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaoconstantine%2Fmaestro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxiaoconstantine%2Fmaestro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaoconstantine%2Fmaestro/lists"}