The Matrix — Sovereign Agent World

A persistent 3D world for visualizing and commanding AI agent swarms. Built with Three.js, Matrix green/noir cyberpunk aesthetic.

Overview

The Matrix is a dark 3D environment — think the Matrix digital world meets a cyberpunk command center. The sovereign operator enters this world to observe and command their AI agent swarm. Each agent has a physical presence in the world with unique geometry, animations, and glow effects. The world visualizes the system's state in real-time.

Agents

Agent	Direction	Role	Visual
Timmy	North	Main Orchestrator	Wireframe humanoid, green glow
Forge	East	Builder Agent	Geometric anvil/hammer, orange glow
Seer	South	Planner/Observer	Crystal icosahedron, purple glow
Echo	West	Communications	Concentric pulse rings, cyan glow

How to Run Locally

Just serve the static files:

# Using npx serve (recommended)
npx serve . -l 3000

# Or Python
python3 -m http.server 3000

# Or any static file server

Open http://localhost:3000 in your browser.

Controls

• Rotate: Click/touch + drag
• Zoom: Scroll wheel / pinch
• Pan: Right-click drag / two-finger drag
• Select Agent: Tap/click on an agent
• Select Core: Tap/click on the central pillar
• Close Panel: Tap empty space or click ✕

Connecting a Real Agent Backend

Replace the MockWebSocket with a real WebSocket connection. The world expects to connect to:

ws://[host]:[port]/ws/world-state

See PROTOCOL.md for the complete WebSocket protocol specification.

Quick Start

1. Implement a WebSocket server that sends events in the format specified in PROTOCOL.md
2. In js/websocket.js, replace MockWebSocket usage with a native WebSocket:

const ws = new WebSocket('ws://your-server:8080/ws/world-state');
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // Dispatch to world systems
};

Adding Custom Agents

1. Add the agent definition to AGENT_DEFS in js/websocket.js
2. Add position to AGENT_POSITIONS in js/agents.js
3. Add color to AGENT_COLORS in js/agents.js
4. Create a geometry function (e.g., createMyAgent()) in js/agents.js
5. Register in AGENT_CREATORS map

iPad Access

Via Tailscale

1. Install Tailscale on your server and iPad
2. Run the server on the Tailscale IP
3. Open http://[tailscale-ip]:3000 in Safari on iPad

Add to Home Screen

1. Open the URL in Safari on iPad
2. Tap the Share button → "Add to Home Screen"
3. The app will run in full-screen mode

Tech Stack

• Three.js (v0.171.0) — 3D rendering via esm.sh CDN
• WebGL 2 — Hardware-accelerated rendering
• EffectComposer — Post-processing (bloom, scanlines, vignette)
• OrbitControls — Touch-friendly camera
• ES Modules — No build tools needed
• JetBrains Mono — Typography via Google Fonts

File Structure

the-matrix/
├── index.html          # Entry point
├── style.css           # All UI styles
├── js/
│   ├── main.js         # Bootstrap, scene setup, game loop
│   ├── world.js        # Ground plane, core pillar, grid
│   ├── agents.js       # Agent geometry, animations, labels
│   ├── effects.js      # Digital rain, particles, post-processing
│   ├── ui.js           # Panel, tabs, chat, task list, memory
│   ├── interaction.js  # Raycasting, selection, camera
│   └── websocket.js    # WebSocket client + MockWebSocket
├── README.md           # This file
└── PROTOCOL.md         # WebSocket protocol specification

Screenshots

Coming soon

License

MIT