maestro
Public
Forked from brdcastro/maestro
Project Files
README
All-in-one LM Studio plugin: local tools, persistent memory, sub-agent delegation, media analysis, and design systems — optimized for local models with limited context.
File System — read, write, copy, move, delete, find, grep, diff, patch (atomic multi-edit), project snapshot, HTML asset audit, PDF/DOCX parsing. Read dedup cache avoids re-reading unchanged files. Workspace root prevents path traversal.
Git — status, diff, add, commit, log. Always enabled.
Web — search (SearXNG or DuckDuckGo fallback, auto-start), scrape, Wikipedia. No API keys.
Code Execution (opt-in) — Python, JavaScript/Deno, shell, terminal, background processes, test runner (2min timeout). Non-zero exits preserve stdout/stderr for self-correction.
macOS (opt-in) — AppleScript, JXA, screenshots (768px @ JPEG q45 default for token efficiency, configurable), Spotlight search, active app context. Dangerous APIs blocked by default.
Memory — Remember/Recall across conversations. SQLite + TF-IDF + embeddings. Tiered auto-injection (L0/L1/L2), AI fact extraction, duplicate/conflict detection, project scoping, decay system.
Sub-Agent — delegate to a secondary model (auto-detected via LM Link). Accepts a multimodal images parameter — vision-capable models (Gemma 4, Qwen3-VL) receive image bytes; text-only models ignore them. Large images auto-resized to 768px before transport. Permission levels: read-only, standard, full. Tool-call parser handles markdown-link [tool](json) format alongside classic JSON. Auto-save, auto-debug, depth limit of 2.
Design (opt-in) — 70 real-brand design system references (Apple, Linear, Spotify, Nike, Tesla, Bugatti, etc.) plus 9 design guides covering typography, color, motion, interaction, responsive, spatial, UX writing, frontend aesthetics (anti-AI-slop rules), and video composition (HyperFrames HTML→MP4 schema).
Video Rendering (opt-in) — render_html_video tool wraps npx hyperframes render to turn HyperFrames-compatible HTML compositions into MP4. Pairs with the video-composition design reference. Requires Node 22+ and FFmpeg.
Media — image analysis (JPEG/PNG/WebP/GIF/BMP/TIFF), video frame extraction (MP4/MOV/AVI/MKV/WebM). Requires ffmpeg for video.
System — clipboard, system info, notifications, HTML preview with structural analysis.
Structured errors — every tool error returns a numeric code (100-799), category, message, and recovery hint the model can act on.
Loop detection — 3 layers: exact-match blocking (3x same call), error streak detection (4x failures), denial tracking (repeated permission errors).
Spill-to-disk — large outputs saved to /tmp/maestro-spill/ with preview + path. Auto-cleanup after 30min.
Workflow phases — tracks tool usage to infer understand/plan/implement/verify phase and inject guidance.
16 settings total:
| Section | Settings |
|---|---|
| Workspace | Default working directory |
| Permissions | Code execution, macOS integration |
| Sub-Agent | Enable, frequency, permissions, auto-debug |
| Memory | Auto-inject, context count, AI extraction, active project |
| Search | SearXNG URL |
| Output | Tool output budget (compact / standard / generous / maximum) |
| Features | Design mode, media analysis, video rendering |
brew install colima docker colima start --cpu 2 --memory 2 docker run -d --name searxng -p 8080:8080 --restart unless-stopped \ -e SEARXNG_BASE_URL=http://localhost:8080 searxng/searxng docker exec searxng sed -i '/^ formats:/,/^[^ ]/{s/^ - html$/ - html\n - json/}' \ /etc/searxng/settings.yml docker restart searxng
Set SearXNG URL to http://localhost:8080 in plugin settings. The plugin auto-starts colima + Docker on demand.
Built on beledarians-lm-studio-tools and persistent-memory. Media analysis, reliability layers, design systems, and all optimizations are original.
MIT
Forked from brdcastro/maestro