shader-agent

Shader Agent is a local-first software toolkit designed for creators and maintainers who need reproducible, offline-capable workflows for generating, reviewing, validating, and exporting shaders. It combines a Python CLI, a local Web UI, reference retrieval from SQLite with FTS5 support, license-aware filtering, render validation gates, and export helpers tailored for platforms like Shadertoy, WebGL, LÖVE 2D, and offline video production. The tool supports deterministic GLSL draft generation without requiring external API keys by default. Optional AI generation can be enabled via environment variables or session-only UI input, supporting OpenAI-compatible, OpenAI, Anthropic, Gemini, and Ollama providers. Users can configure AI settings such as model, base URL, retries, cache, and concurrency through environment variables — never commit real keys. Key features include ingestion of shader metadata/code from JSONL, multi-candidate iterative generation with render feedback, preflight checks for syntax, mainImage shape, license compliance, and smoke testing, and export packages compatible with Shadertoy and LÖVE 2D. The Web UI provides live WebGL previews, editable code, node graphs for non-destructive iteration, and controls for exporting frames or videos with configurable FPS, resolution, and muxing. It includes CLI chat mode with projectized outputs, reference audits, and commands like /search, /export, and /repair-ai. The architecture is modular: cli.py for command-line entry, webapp.py for the local server, agent.py for orchestration, store.py for storage/search, llm.py for provider routing, quality.py for validation gates, and targets/ for platform-specific adapters. The project has been used to produce 22 episodes of shader-based VFX videos published on Bilibili and YouTube, demonstrating long-form practical use beyond isolated experiments. Testing includes unit tests, acceptance scripts, and browser UI validations. Third-party components like ufbx are bundled under MIT license. Security guidance emphasizes keeping API keys, private prompts, generated media, and databases out of public issues or PRs. The roadmap includes publishing a public repository, adding CI badges, hosting screenshots/GIFs, improving render validation, and separating heavy tests from fast PR checks. Released under MIT License.