the-nexus/README.md

# ◈ The Nexus — Timmy's Sovereign Home

A Three.js environment serving as Timmy's sovereign space — like Dr. Strange's Sanctum Sanctorum, existing outside time. The Nexus is the central hub from which all worlds are accessed through portals.

## Features

- **Procedural Nebula Skybox** — animated stars, twinkling, layered nebula clouds
- **Batcave Terminal** — 5 holographic display panels arranged in an arc showing:
  - Nexus Command (system status, harness state, agent loops)
  - Dev Queue (live Gitea issue references)
  - Metrics (uptime, commits, CPU/MEM)
  - Thought Stream (Timmy's current thoughts)
  - Agent Status (all agent states)
- **Morrowind Portal** — glowing torus with animated swirl shader, ready for world connection
- **Admin Chat (Timmy Terminal)** — real-time message interface, ready for Hermes WebSocket
- **Nexus Core** — floating crystalline icosahedron on pedestal
- **Ambient Environment** — crystal formations, floating runestones, energy particles, atmospheric fog
- **WASD + Mouse Navigation** — first-person exploration of the space
- **Post-Processing** — Unreal Bloom + SMAA antialiasing

## Architecture

```
the-nexus/
├── index.html    # Entry point with HUD overlay, chat panel, loading screen
├── style.css     # Nexus design system (dark space theme, holographic panels)
└── app.js        # Three.js scene, shaders, controls, game loop
```

## Running Locally

```bash
npx serve . -l 3000
# Open http://localhost:3000
```

## Roadmap

- [ ] Wire chat to Hermes WebSocket (`/api/world/ws`)
- [ ] Pull live data into terminal panels from Timmy's actual state
- [ ] Portal walk-through interaction to load destination worlds
- [ ] Timmy's avatar (lizard wizard body he designs himself)
- [ ] Connect to AlexanderWhitestone.com as public entry point
- [ ] Integrate existing Replit timmy-tower world code

## Related

- **Gitea Issue**: [#1090 — EPIC: Nexus v1](http://143.198.27.163:3000/rockachopa/Timmy-time-dashboard/issues/1090)
- **Live Demo**: Deployed via Perplexity Computer

## Groq Worker

The Groq worker is a dedicated worker for the Groq API. It is designed to be used by the Nexus Mind to offload the thinking process to the Groq API.

### Usage

To use the Groq worker, you need to set the `GROQ_API_KEY` environment variable. You can then run the `nexus_think.py` script with the `--groq-model` argument:

```bash
export GROQ_API_KEY="your-api-key"
python -m nexus.nexus_think --groq-model "groq/llama3-8b-8192"
```

### Recommendations

Groq has fast inference, which makes it a good candidate for tasks like PR reviews. You can use the Groq worker to review PRs by a Gitea webhook.

---

*Part of [The Timmy Foundation](http://143.198.27.163:3000/Timmy_Foundation)*