Agent Visualizations
Audio-reactive visual identities for every AI assistant in QuoxCORE.
Overview
Every AI assistant in QuoxCORE has a visual identity — a canvas-based animation displayed in the chat sidebar that reacts to what the agent is doing and how it sounds. When CommanderQ is thinking, its HAL eye pulses. When SENTINEL speaks, its sphere expands with the audio. When CIPHER listens, its DNA helix rotates faster.
The system ships with 13 hand-built visualizer themes. HAL (the red iris) is free with every installation. The remaining 12 are premium, validated against a licence key with tamper protection.
Tier: Standard
How It Works
Each visualizer is a React component that draws to a <canvas> element using requestAnimationFrame. Two inputs drive every animation:
- Agent state — idle, listening, speaking, thinking, or error. Each state has independent speed, scale, sensitivity, and colour parameters.
- Audio frequency data — extracted from the Web Audio API. Particle speed, ring intensity, pupil dilation, and motion parameters all respond to the audio spectrum in real-time.
The visualizer appears in the chat sidebar via VisualizerSection, which wraps the canvas in a collapsible panel with a voice button, status badge, and popout control.
Architecture
VisualizerSection (sidebar panel)
└── VisualizerFactory (selects theme by agent ID)
└── [Theme Component] (canvas renderer)
├── getStateConfig() — speed, scale, hue for current state
├── getAudioFeatures() — energy, zero-crossing from frequency data
└── requestAnimationFrame loop — draws to canvas
Themes
HAL (Free Default)
A red iris with audio-reactive pupil dilation and a glowing ring halo. Assigned to CommanderQ by default. The pupil contracts when idle, dilates when listening, and pulses when speaking.
Premium Themes
| Theme | Description | Default Agent |
|---|---|---|
| Atom | Orbiting electrons around a nucleus. Orbit speed responds to audio energy. | NOVA |
| Brain | Neural network with firing synapses. Connection brightness follows frequency data. | PRISM |
| DNA | Double helix rotation. Strand speed and colour shift with audio. | CIPHER |
| Sphere | Pulsing 3D sphere. Surface displacement responds to frequency bands. | SENTINEL, ATLAS |
| Fluid | Physics-based particle system with flow-field noise. Particles attract and repel based on audio. | — |
| HoloField | Holographic rings driven by MFCC audio features. | SCHOLAR |
| Nexus | 3D particle network in JARVIS style. Connection density responds to audio. | FORGE |
| KITT | Knight Rider scanner bar. Sweep speed matches audio intensity. | METRICS |
| Ripple | Concentric expanding rings. Ring spacing and speed react to frequency. | INSIGHT, BEACON |
| Iris | Hyper-realistic human iris with dilation and colour shift. | — |
| Codex | Scrolling manuscript columns with pattern highlighting. Built for ARCHIVIST. | ARCHIVIST |
| Core | Central nucleus with five orbital rings and cognitive implant nodes. Built for COREY. | COREY |
Default Assignments
Each agent ships with a default visualizer and base hue. Users can override both.
| Agent | Visualizer | Hue |
|---|---|---|
| CommanderQ | HAL | 0 (red) |
| SENTINEL | Sphere | 210 (blue) |
| CIPHER | DNA | 280 (purple) |
| NOVA | Atom | 150 (green) |
| PRISM | Brain | 220 (blue) |
| ATLAS | Sphere | 30 (orange) |
| METRICS | KITT | 15 (red-orange) |
| INSIGHT | Ripple | 25 (orange) |
| SCHOLAR | HoloField | 175 (cyan) |
| BEACON | Ripple | 140 (green) |
| FORGE | Nexus | 160 (teal) |
| ARCHIVIST | Codex | custom |
| COREY | Core | custom |
Agent States
Each visualizer responds to five states. Every state has independent configuration for speed, scale, sensitivity, and colour (HSL hue).
| State | Behaviour |
|---|---|
| Idle | Slow breathing animation. Minimal motion. Base hue. |
| Listening | Faster motion, higher sensitivity. Responds to microphone input. |
| Speaking | Peak animation intensity. Full audio reactivity from TTS output. |
| Thinking | Moderate speed, distinct hue shift. Indicates processing. |
| Error | Reduced motion, desaturated or red-shifted colour. |
Settings Editor
The Visualization Editor is accessible from Settings or from individual agent detail views. It provides:
- Theme grid — visual picker showing all 13 themes. Free (HAL) and premium themes are clearly marked.
- Per-state controls — sliders for speed, scale, and sensitivity. HSL hue picker for colour. Each of the five states has its own panel.
- Live preview — renders the selected theme with simulated audio so you can see changes in real-time before saving.
- State switcher — buttons to toggle the preview between idle, listening, speaking, thinking, and error.
- Colour overview — chip display showing the hue for each state at a glance.
Settings are stored per-agent in localStorage at quox-viz-config.
Sidebar Integration
VisualizerSection is the sidebar wrapper component that displays the visualizer during chat. It provides:
- Collapse/expand — toggle to show or hide the visualizer. Preference persists in localStorage.
- Popout — open the visualizer in a separate window for a larger view.
- Push-to-talk — integrated voice button that triggers the listening state.
- Status badge — shows the current agent state (idle, listening, speaking, thinking, error).
- Voice error display — surfaces microphone or transcription errors inline.
Licensing
HAL is included free with every QuoxCORE installation. The remaining 12 themes require a valid Visualizations licence. Licence validation runs both client-side and server-side. If validation fails, the visualizer downgrades to HAL automatically.