# kasket091/agent-floor architecture

> Architecture diagram of the GitHub repository kasket091/agent-floor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kasket091/agent-floor
- Repository: https://github.com/kasket091/agent-floor

## Overview

Agent Floor turns coding-agent activity into a live 3D office: integrations report events, the server normalizes and enriches them, and the browser renders agents, rooms, status, and interactions. Claude adds site-specific rooms, task plans, and standby staff; Codex, Cursor, and generic HTTP events are also documented. The graph emphasizes the evidenced event path and major documented scene capabilities. Some server routes and UI behavior are unsampled, so their links are omitted rather than inferred.

Main entry points: [`src/world/World.ts`](https://github.com/kasket091/agent-floor/blob/main/src/world/World.ts) (Scene orchestration), [`server/claude-ingest.mjs`](https://github.com/kasket091/agent-floor/blob/main/server/claude-ingest.mjs) (Claude ingestion), [`server/index.mjs`](https://github.com/kasket091/agent-floor/blob/main/server/index.mjs) (HTTP event service), [`src/main.ts`](https://github.com/kasket091/agent-floor/blob/main/src/main.ts) (Browser app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Agent integrations"]
  node_claude["Claude adapter<br/>[claude.mjs]"]
  node_codex["Codex adapter<br/>[codex.mjs]"]
  node_cursor["Cursor adapter<br/>[cursor.mjs]"]
  node_other(("HTTP event clients"))
end

subgraph group_server["Event server"]
  node_ingest_claude["Claude ingestion<br/>[claude-ingest.mjs]"]
  node_server_http["HTTP event service<br/>[index.mjs]"]
  node_redact["Payload redaction<br/>[redact.mjs]"]
  node_sites["Site rooms<br/>[sites.mjs]"]
  node_plans["Task plans<br/>[plan.mjs]"]
  node_staff["Standby staff<br/>[staff-desk.mjs]"]
end

subgraph group_state["Shared state"]
  node_protocol["Event protocol<br/>[protocol.js]"]
  node_browser_store[("Browser state store<br/>[store.ts]")]
  node_connection["Live connection<br/>[connection.ts]"]
end

subgraph group_visual["3D office"]
  node_world["Scene orchestration<br/>[World.ts]"]
  node_layout["Room layout<br/>[layout.ts]"]
  node_building["Office building<br/>[Building.ts]"]
  node_teamroom["Team rooms<br/>[TeamRoom.ts]"]
  node_character["Agent characters<br/>[Character.ts]"]
  node_workstation["Desks and screens<br/>[Workstation.ts]"]
  node_courier["Message courier<br/>[Courier.ts]"]
  node_screens["Room screens<br/>[Screen.ts]"]
  node_visual_assets["Scene styling<br/>[props.ts]"]
  node_palette["Brand and palette<br/>[brand.ts]"]
end

subgraph group_interface["Browser interface"]
  node_hud["Floor controls<br/>[hud.ts]"]
  node_app["Browser app<br/>[main.ts]"]
end

node_claude -->|"translates hooks"| node_ingest_claude
node_ingest_claude -->|"redacts payload"| node_redact
node_ingest_claude -->|"resolves rooms"| node_sites
node_ingest_claude -->|"updates plans"| node_plans
node_ingest_claude -->|"assigns staff"| node_staff
node_ingest_claude -->|"emits events"| node_protocol
node_other -->|"posts events"| node_server_http
node_server_http -->|"normalizes events"| node_protocol
node_codex -.->|"reports activity"| node_server_http
node_cursor -.->|"reports activity"| node_server_http
node_server_http -->|"routes hooks"| node_ingest_claude
node_connection -->|"delivers updates"| node_browser_store
node_connection -->|"uses event format"| node_protocol
node_browser_store -->|"applies reducer"| node_protocol
node_app -->|"opens stream"| node_connection
node_app -->|"reads state"| node_browser_store
node_app -->|"creates scene"| node_world
node_app -->|"creates controls"| node_hud
node_world -->|"calculates layout"| node_layout
node_world -->|"constructs building"| node_building
node_world -->|"creates rooms"| node_teamroom
node_world -->|"places agents"| node_character
node_world -->|"creates desks"| node_workstation
node_world -->|"animates messages"| node_courier
node_world -.->|"uses room screens"| node_screens
node_building -->|"builds with props"| node_visual_assets
node_teamroom -->|"uses characters"| node_character
node_workstation -->|"renders displays"| node_screens
node_character -->|"styles characters"| node_palette
node_world -->|"styles scene"| node_palette
node_hud -->|"shows state"| node_browser_store

click node_claude "https://github.com/kasket091/agent-floor/blob/main/adapters/claude.mjs"
click node_codex "https://github.com/kasket091/agent-floor/blob/main/adapters/codex.mjs"
click node_cursor "https://github.com/kasket091/agent-floor/blob/main/adapters/cursor.mjs"
click node_ingest_claude "https://github.com/kasket091/agent-floor/blob/main/server/claude-ingest.mjs"
click node_server_http "https://github.com/kasket091/agent-floor/blob/main/server/index.mjs"
click node_redact "https://github.com/kasket091/agent-floor/blob/main/server/redact.mjs"
click node_sites "https://github.com/kasket091/agent-floor/blob/main/server/sites.mjs"
click node_plans "https://github.com/kasket091/agent-floor/blob/main/server/plan.mjs"
click node_staff "https://github.com/kasket091/agent-floor/blob/main/server/staff-desk.mjs"
click node_protocol "https://github.com/kasket091/agent-floor/blob/main/shared/protocol.js"
click node_browser_store "https://github.com/kasket091/agent-floor/blob/main/src/core/store.ts"
click node_connection "https://github.com/kasket091/agent-floor/blob/main/src/core/connection.ts"
click node_world "https://github.com/kasket091/agent-floor/blob/main/src/world/World.ts"
click node_layout "https://github.com/kasket091/agent-floor/blob/main/src/world/layout.ts"
click node_building "https://github.com/kasket091/agent-floor/blob/main/src/world/Building.ts"
click node_teamroom "https://github.com/kasket091/agent-floor/blob/main/src/world/TeamRoom.ts"
click node_character "https://github.com/kasket091/agent-floor/blob/main/src/world/Character.ts"
click node_workstation "https://github.com/kasket091/agent-floor/blob/main/src/world/Workstation.ts"
click node_courier "https://github.com/kasket091/agent-floor/blob/main/src/world/Courier.ts"
click node_screens "https://github.com/kasket091/agent-floor/blob/main/src/world/Screen.ts"
click node_visual_assets "https://github.com/kasket091/agent-floor/blob/main/src/world/props.ts"
click node_palette "https://github.com/kasket091/agent-floor/blob/main/src/world/brand.ts"
click node_hud "https://github.com/kasket091/agent-floor/blob/main/src/ui/hud.ts"
click node_app "https://github.com/kasket091/agent-floor/blob/main/src/main.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude,node_codex,node_cursor,node_other toneBlue
class node_ingest_claude,node_server_http,node_redact,node_sites,node_plans,node_staff toneAmber
class node_protocol,node_browser_store,node_connection toneMint
class node_world,node_layout,node_building,node_teamroom,node_character,node_workstation,node_courier,node_screens,node_visual_assets,node_palette toneRose
class node_hud,node_app toneIndigo
```

## Components

### Agent integrations

- [Claude adapter](https://github.com/kasket091/agent-floor/blob/main/adapters/claude.mjs): `adapters/claude.mjs`
- [Codex adapter](https://github.com/kasket091/agent-floor/blob/main/adapters/codex.mjs): `adapters/codex.mjs`
- [Cursor adapter](https://github.com/kasket091/agent-floor/blob/main/adapters/cursor.mjs): `adapters/cursor.mjs`
- **HTTP event clients**

### Event server

- [Claude ingestion](https://github.com/kasket091/agent-floor/blob/main/server/claude-ingest.mjs): `server/claude-ingest.mjs`
- [HTTP event service](https://github.com/kasket091/agent-floor/blob/main/server/index.mjs): `server/index.mjs`
- [Payload redaction](https://github.com/kasket091/agent-floor/blob/main/server/redact.mjs): `server/redact.mjs`
- [Site rooms](https://github.com/kasket091/agent-floor/blob/main/server/sites.mjs): `server/sites.mjs`
- [Task plans](https://github.com/kasket091/agent-floor/blob/main/server/plan.mjs): `server/plan.mjs`
- [Standby staff](https://github.com/kasket091/agent-floor/blob/main/server/staff-desk.mjs): `server/staff-desk.mjs`

### Shared state

- [Event protocol](https://github.com/kasket091/agent-floor/blob/main/shared/protocol.js): `shared/protocol.js`
- [Browser state store](https://github.com/kasket091/agent-floor/blob/main/src/core/store.ts): `src/core/store.ts`
- [Live connection](https://github.com/kasket091/agent-floor/blob/main/src/core/connection.ts): `src/core/connection.ts`

### 3D office

- [Scene orchestration](https://github.com/kasket091/agent-floor/blob/main/src/world/World.ts): `src/world/World.ts`
- [Room layout](https://github.com/kasket091/agent-floor/blob/main/src/world/layout.ts): `src/world/layout.ts`
- [Office building](https://github.com/kasket091/agent-floor/blob/main/src/world/Building.ts): `src/world/Building.ts`
- [Team rooms](https://github.com/kasket091/agent-floor/blob/main/src/world/TeamRoom.ts): `src/world/TeamRoom.ts`
- [Agent characters](https://github.com/kasket091/agent-floor/blob/main/src/world/Character.ts): `src/world/Character.ts`
- [Desks and screens](https://github.com/kasket091/agent-floor/blob/main/src/world/Workstation.ts): `src/world/Workstation.ts`
- [Message courier](https://github.com/kasket091/agent-floor/blob/main/src/world/Courier.ts): `src/world/Courier.ts`
- [Room screens](https://github.com/kasket091/agent-floor/blob/main/src/world/Screen.ts): `src/world/Screen.ts`
- [Scene styling](https://github.com/kasket091/agent-floor/blob/main/src/world/props.ts): `src/world/props.ts`
- [Brand and palette](https://github.com/kasket091/agent-floor/blob/main/src/world/brand.ts): `src/world/brand.ts`

### Browser interface

- [Floor controls](https://github.com/kasket091/agent-floor/blob/main/src/ui/hud.ts): `src/ui/hud.ts`
- [Browser app](https://github.com/kasket091/agent-floor/blob/main/src/main.ts): `src/main.ts`

## Connections

- Claude adapter → Claude ingestion: translates hooks (evidence: `server/claude-ingest.mjs`)
- Claude ingestion → Payload redaction: redacts payload (evidence: `server/claude-ingest.mjs`)
- Claude ingestion → Site rooms: resolves rooms (evidence: `server/claude-ingest.mjs`)
- Claude ingestion → Task plans: updates plans (evidence: `server/claude-ingest.mjs`)
- Claude ingestion → Standby staff: assigns staff (evidence: `server/claude-ingest.mjs`)
- Claude ingestion → Event protocol: emits events (evidence: `server/claude-ingest.mjs`)
- HTTP event clients → HTTP event service: posts events
- HTTP event service → Event protocol: normalizes events (evidence: `server/index.mjs`)
- Codex adapter → HTTP event service: reports activity
- Cursor adapter → HTTP event service: reports activity
- HTTP event service → Claude ingestion: routes hooks (evidence: `server/index.mjs`)
- Live connection → Browser state store: delivers updates (evidence: `src/core/connection.ts`)
- Live connection → Event protocol: uses event format (evidence: `src/core/connection.ts`)
- Browser state store → Event protocol: applies reducer (evidence: `src/core/store.ts`)
- Browser app → Live connection: opens stream (evidence: `src/main.ts`)
- Browser app → Browser state store: reads state (evidence: `src/main.ts`)
- Browser app → Scene orchestration: creates scene (evidence: `src/main.ts`)
- Browser app → Floor controls: creates controls (evidence: `src/main.ts`)
- Scene orchestration → Room layout: calculates layout (evidence: `src/world/World.ts`)
- Scene orchestration → Office building: constructs building (evidence: `src/world/World.ts`)
- Scene orchestration → Team rooms: creates rooms (evidence: `src/world/World.ts`)
- Scene orchestration → Agent characters: places agents (evidence: `src/world/World.ts`)
- Scene orchestration → Desks and screens: creates desks (evidence: `src/world/World.ts`)
- Scene orchestration → Message courier: animates messages (evidence: `src/world/World.ts`)
- Scene orchestration → Room screens: uses room screens
- Office building → Scene styling: builds with props (evidence: `src/world/Building.ts`)
- Team rooms → Agent characters: uses characters (evidence: `src/world/TeamRoom.ts`)
- Desks and screens → Room screens: renders displays (evidence: `src/world/Workstation.ts`)
- Agent characters → Brand and palette: styles characters (evidence: `src/world/Character.ts`)
- Scene orchestration → Brand and palette: styles scene (evidence: `src/world/World.ts`)
- Floor controls → Browser state store: shows state (evidence: `src/ui/hud.ts`)