Files

CI / validate (pull_request) Failing after 5s

Details

feat: WebSocket bridge to Timmy + trim fat (2211→1181 lines)

Adds real-time WebSocket connection to Timmy's backend:
- Agent behaviors driven by live cognitive state
- Chat routed to real Timmy (not fake responses)
- Dual-brain panel updates from WS
- Graceful degradation when offline

Trimmed 1030 lines (47% reduction):
- Simplified glass floor (removed 6-band edge system)
- Compacted dual-brain panel (removed per-frame scan canvas)
- Removed simulateAgentThought() (WS replaces it)
- Removed fake chat responses
- Compacted all functions

Refs #8

2026-03-25 16:30:08 +00:00

2.5 KiB

Raw Blame History

CLAUDE.md — The Nexus (Timmy_Foundation/the-nexus)

Project Overview

The Nexus is a Three.js environment — Timmy's sovereign home in 3D space. It serves as the central hub for all portals to other worlds. Stack: vanilla JS ES modules, Three.js 0.183, no bundler.

Architecture

index.html    # Entry point: HUD, chat panel, loading screen, live-reload script
style.css     # Design system: dark space theme, holographic panels
app.js        # Three.js scene, shaders, controls, game loop, WS bridge (~all logic)
portals.json  # Portal registry (data-driven)
vision.json   # Vision point content (data-driven)
server.js     # Optional: proxy server for CORS (commit heatmap API)

No build step. Served as static files. Import maps in index.html handle Three.js resolution.

WebSocket Bridge (v2.0)

The Nexus connects to Timmy's backend via WebSocket for live cognitive state:

URL: ?ws=ws://hermes:8765 query param, or default ws://localhost:8765
Inbound: agent_state, agent_move, chat_response, system_metrics, dual_brain, heartbeat
Outbound: chat_message, presence
Graceful degradation: When WS is offline, agents idle locally, chat shows "OFFLINE"

Conventions

ES modules only — no CommonJS, no bundler
Single-file app — logic lives in app.js; don't split without good reason
Color palette — defined in NEXUS.colors at top of app.js
Line budget — app.js should stay under 1500 lines
Conventional commits: feat:, fix:, refactor:, test:, chore:
Branch naming: claude/issue-{N} (e.g. claude/issue-5)
One PR at a time — wait for merge-bot before opening the next

Validation (merge-bot checks)

The nexus-merge-bot.sh validates PRs before auto-merge:

HTML validation — index.html must be valid HTML
JS syntax — node --check app.js must pass
JSON validation — any .json files must parse
File size budget — JS files must be < 500 KB

Always run node --check app.js before committing.

PR Rules

Base every PR on latest main
Squash merge only
Do NOT merge manually — merge-bot handles merges
If merge-bot comments "CONFLICT": rebase onto main and force-push your branch
Include Fixes #N or Refs #N in commit message

Running Locally

npx serve . -l 3000
# open http://localhost:3000
# To connect to Timmy: http://localhost:3000?ws=ws://hermes:8765

Gitea API

Base URL: http://143.198.27.163:3000/api/v1
Repo:     Timmy_Foundation/the-nexus

2.5 KiB Raw Blame History