System design, data flow, and component reference for the Liminal creative coding agent.
5-layer architecture from user interface to infrastructure.
CLI, Chat, Bubble Tea TUI
Entry points via bin/liminal, src/chat/, src/tui-bridge/.
RalphLoop, LLM Client
Generate → Evaluate → Iterate → Improve. Configurable model roles.
Brain, Compost, Evolution, Harness
Artistic knowledge, creative seeds, MAP-Elites, self-improvement.
12 launch creative domains
p5.js, SVG, GLSL, Three.js, Hydra, Strudel, Tone.js, Revideo, HyperFrames, ASCII, Kinetic, TextGen.
Guardrails, Security, FS, Ledger
M1-M18 guardrails, SSRF protection, LiminalFS, task ledger.
The iterative generation engine that drives all creative output.
Prompt → Brain (enhance) → LLM (generate) → Evaluator (score)
↑ ↓
← Harness (detect stagnation, adapt strategy) ← Guardrails (validate)| Role | Temperature | Purpose |
|---|---|---|
| Generator | 0.7 | Creative code generation |
| Evaluator | 0.2 | Quality assessment and scoring |
| Harness | 0.5 | Pattern detection and repair |
Roles configured in src/config/RoleConfig.ts. Provider detection via detectProviderFromUrl() in src/llm/MultiProviderConfig.ts.
Model-agnostic provider system with circuit breaker and failover.
| Provider | Base URL | Notes |
|---|---|---|
| MiniMax | api.minimax.io/anthropic | Preferred cloud |
| OpenAI | api.openai.com | Full support |
| Anthropic | api.anthropic.com | Full support |
| generativelanguage.googleapis.com | Gemini models | |
| Ollama | localhost:11434 | Local inference |
| OpenRouter | openrouter.ai | Multi-model router |
| GLM / ZhipuAI | api.z.ai | GLM models |
| Kimi Code | api.kimi.com/coding | K2P5 coding endpoint |
| Moonshot AI | api.moonshot.ai | Legacy Kimi endpoint |
| Custom | localhost:8000/v1 or configured URL | OpenAI-compatible endpoints |
Provider adapters live in src/llm/providers/. The ProviderFactory resolves the correct adapter from baseUrl. The CapabilityRegistry maintains a static model→capabilities map for 30+ models.
Self-improving system that observes failures, detects patterns, and applies targeted fixes.
| Tool | Rate Limit | Purpose |
|---|---|---|
read_file | 10 reads/min | Read source files for context |
write_file | 10 writes/min | Apply code changes |
build | 12 builds/min | Compile and check for errors |
test | 12 tests/min | Run test suites |
install_package | 5 installs/min | Add dependencies |
run_script | 10 runs/min | Execute arbitrary scripts |
query_knowledge | 15 queries/min | Search internal knowledge base |
Up to 3 retries per tool call. The LLM Mode Agent (src/harness/agent/LLMModeAgent.ts) orchestrates multi-step repair workflows using these tools. Safety: shell-free execFileSync in verifier, metacharacter guards.
12 launch generators unified under the TierBasedGenerator base class.
| Generator | Domain | Directory | Status |
|---|---|---|---|
| p5.js | 2D Canvas | src/generators/p5/ | Stable |
| SVG | Vector Art | src/generators/svg/ | Stable |
| GLSL | Shaders | src/generators/glsl/ | Stable |
| Three.js | 3D Scenes | src/generators/three/ | Stable |
| Strudel | Live Music | src/generators/strudel/ | Stable |
| Hydra | Visual Synth | src/generators/hydra/ | Stable |
| Tone.js | Web Audio | src/generators/tone/ | Stable |
| Revideo | Video | src/generators/revideo/ | Active |
| HyperFrames | HTML/GSAP Composition | src/generators/hyperframes/ | Active |
| ASCII | Terminal Art | src/generators/ascii/ | Stable |
| Kinetic | Motion Art | src/generators/kinetic/ | Active |
| TextGen | Generative Text | src/generators/textgen/ | Stable |
18-type multi-layer safety system in src/guardrails/.
Source structure: src/guardrails/{core,compliance,evolution,hygiene,correctness,validation,observation,remediation,rules}/ with standalone modules for AccessibilityGuardrails, RuntimeHealthMonitor, and SemanticValidator.
User Prompt
↓
Brain (src/brain/)
→ Artistic knowledge injection
→ Compost seed retrieval
→ Archive example selection
↓
RalphLoop (src/core/)
→ Enhanced prompt construction
↓
Generator (src/generators/*/)
→ Domain-specific code generation via LLM
↓
Evaluator (src/harness/)
→ Multi-dimensional quality scoring
→ 3-agent critique board (Minimalist / Expressionist / Technician)
↓
Guardrails (src/guardrails/)
→ M1-M18 validation pipeline
→ Aesthetic quality gate
↓
Output
→ Code file + evaluation report
→ Compost seed (if quality threshold met)
→ Archive entry (if novel)48 subsystems in src/.
src/
├── core/ Loop engine, validation, domain detection
├── llm/ LLM client, provider adapters, circuit breaker
├── config/ Configuration loading, role-based model selection
├── types/ Shared TypeScript types
├── constants/ Project-wide constants
├── errors/ Error types and handling
├── utils/ Utility functions
│
├── generators/ 11 domain generators (p5, glsl, three, strudel, ...)
│
├── harness/ Meta-harness: failure logging, pattern detection, agent
├── guardrails/ M1-M18 multi-layer guardrail system
├── security/ SSRF protection, rate limiting, sandbox
├── sandbox/ Code execution sandbox
│
├── brain/ Artistic knowledge, prompt enhancement
├── compost/ Compost Mill pipeline (digest, collide, score, promote)
├── evolution/ MAP-Elites, novelty archive, cross-domain crossover
├── embeddings/ Local SBERT embedding service
├── intuition/ Thompson Sampling, domain prototypes
├── learning/ Meta-learning and improvement tracking
│
├── audio/ Audio analysis, pitch detection, visual mapping
├── music/ Theory engine, Euclidean rhythms, Markov chains
├── musicToVisual/ Audio-to-visual parameter mapping
│
├── aesthetic/ Color theory, design tiers, multi-critic evaluation
├── calibration/ Aesthetic calibration and scoring
│
├── tui/ Terminal UI (NaturalInterface, routing)
├── tui-bridge/ HTTP/SSE bridge for Bubble Tea runtime
├── chat/ Interview-driven creative sessions
├── gui/ Web GUI (Express server)
│
├── collab/ Multi-agent board, swarm coordination
├── swarm/ Swarm generation strategies
├── routing/ Dual-model routing (fast + powerful)
│
├── fs/ LiminalFS: ProjectStore, EventStore, AssetStore
├── ledger/ Task corpus, runner, verifier
├── render/ Rendering pipeline
├── export/ Output format conversion
├── gallery/ Sketch gallery management
├── fix/ Auto-fix with LLM
├── quality/ Quality metrics and tracking
│
├── plugins/ Plugin system
├── composite/ Composite generation
├── composition/ Composition API
│
├── prompts/ Prompt templates and libraries
├── nodeprompt/ Node-based prompt construction
├── runtime-core/ Runtime environment management
├── ui/ Shared UI components
├── improvement/ Self-improvement tracking
├── entropy/ Entropy-based diversity measures
├── scavenger/ Scavenger agent for resource recovery
└── git/ Git integration utilities