# agentsystemlabs/agent-office architecture

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

- Interactive diagram: https://gitdiagram.com/agentsystemlabs/agent-office
- Repository: https://github.com/agentsystemlabs/agent-office

## Overview

Agent Office is a browser-based shared 3D workspace for people collaborating with coding agents. Users enter a project floor, start an agent at a desk, and interact with its live terminal; GitHub issues, pull requests, queues and worktrees support the project workflow. The office also provides shared presence, chat, voice, screen sharing and a whiteboard. The graph reflects README-documented capabilities and sampled server/client responsibilities; unsampled feature wiring is represented only where documentation supports it.

Main entry points: [`src/server/server.ts`](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/server.ts) (HTTP and realtime server), [`src/client/main.ts`](https://github.com/agentsystemlabs/agent-office/blob/main/src/client/main.ts) (3D office client), [`src/server/workers.ts`](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/workers.ts) (Agent workers), [`src/server/github.ts`](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/github.ts) (GitHub boards and PRs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Office experience"]
  node_browser["3D office client<br/>[main.ts]"]
  node_world["Office world<br/>[office.ts]"]
  node_ui["Office interface"]
  node_state["Client state<br/>[state.ts]"]
end

subgraph group_agents["Workers and projects"]
  node_floor["Project floors<br/>[building.ts]"]
  node_workers["Agent workers<br/>[workers.ts]"]
  node_terminal["Live terminals<br/>[ptyhost.ts]"]
  node_queue["Task queues<br/>[queue.ts]"]
  node_github["GitHub boards and PRs<br/>[github.ts]"]
  node_worktrees["Git worktrees<br/>[worktrees.ts]"]
end

subgraph group_collaboration["Team collaboration"]
  node_chat["Chat and presence<br/>[server.ts]"]
  node_voice["Voice and screen sharing<br/>[voice.ts]"]
  node_whiteboard["Shared whiteboard<br/>[whiteboard.ts]"]
  node_notify["Worker notifications<br/>[webhook.ts]"]
end

subgraph group_server["Office services"]
  node_server["HTTP and realtime server<br/>[server.ts]"]
  node_protocol["Shared protocol<br/>[protocol.ts]"]
  node_services["Worker web services<br/>[services.ts]"]
  node_search["Chat and terminal search<br/>[search.ts]"]
end

node_user(("Team member"))
node_agentcli["Agent CLI tools"]
node_githubsvc["GitHub CLI"]

node_user -->|"uses"| node_browser
node_browser -->|"renders"| node_world
node_browser -->|"opens"| node_ui
node_browser -->|"reads and updates"| node_state
node_browser -->|"sends realtime events"| node_server
node_server -->|"sends office state"| node_browser
node_server -->|"uses message types"| node_protocol
node_server -->|"manages projects"| node_floor
node_server -->|"dispatches worker actions"| node_workers
node_workers -->|"runs processes"| node_terminal
node_workers -->|"starts agents"| node_agentcli
node_workers -->|"manages tasks"| node_queue
node_workers -->|"uses worktrees"| node_worktrees
node_workers -->|"handles issue and PR actions"| node_github
node_github -->|"runs GitHub commands"| node_githubsvc
node_server -->|"handles shared chat and presence"| node_chat
node_browser -->|"starts voice and sharing"| node_voice
node_server -->|"handles board updates"| node_whiteboard
node_server -->|"tracks worker status"| node_notify
node_server -->|"scans worker services"| node_services
node_server -->|"normalizes search terms"| node_search
node_server -->|"searches terminal buffers"| node_terminal

click node_browser "https://github.com/agentsystemlabs/agent-office/blob/main/src/client/main.ts"
click node_world "https://github.com/agentsystemlabs/agent-office/blob/main/src/client/world/office.ts"
click node_ui "https://github.com/agentsystemlabs/agent-office/tree/main/src/client/ui"
click node_state "https://github.com/agentsystemlabs/agent-office/blob/main/src/client/state.ts"
click node_server "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/server.ts"
click node_protocol "https://github.com/agentsystemlabs/agent-office/blob/main/src/shared/protocol.ts"
click node_floor "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/building.ts"
click node_workers "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/workers.ts"
click node_terminal "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/ptyhost.ts"
click node_queue "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/queue.ts"
click node_github "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/github.ts"
click node_worktrees "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/worktrees.ts"
click node_chat "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/server.ts"
click node_voice "https://github.com/agentsystemlabs/agent-office/blob/main/src/client/voice.ts"
click node_whiteboard "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/whiteboard.ts"
click node_notify "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/webhook.ts"
click node_services "https://github.com/agentsystemlabs/agent-office/blob/main/src/server/services.ts"
click node_search "https://github.com/agentsystemlabs/agent-office/blob/main/src/shared/search.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_browser,node_world,node_ui,node_state toneBlue
class node_floor,node_workers,node_terminal,node_queue,node_github,node_worktrees toneAmber
class node_chat,node_voice,node_whiteboard,node_notify toneMint
class node_server,node_protocol,node_services,node_search toneRose
class node_user,node_agentcli,node_githubsvc toneIndigo
```

## Components

### Office experience

- [3D office client](https://github.com/agentsystemlabs/agent-office/blob/main/src/client/main.ts): `src/client/main.ts`
- [Office world](https://github.com/agentsystemlabs/agent-office/blob/main/src/client/world/office.ts): `src/client/world/office.ts`
- [Office interface](https://github.com/agentsystemlabs/agent-office/tree/main/src/client/ui): `src/client/ui`
- [Client state](https://github.com/agentsystemlabs/agent-office/blob/main/src/client/state.ts): `src/client/state.ts`

### Workers and projects

- [Project floors](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/building.ts): `src/server/building.ts`
- [Agent workers](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/workers.ts): `src/server/workers.ts`
- [Live terminals](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/ptyhost.ts): `src/server/ptyhost.ts`
- [Task queues](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/queue.ts): `src/server/queue.ts`
- [GitHub boards and PRs](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/github.ts): `src/server/github.ts`
- [Git worktrees](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/worktrees.ts): `src/server/worktrees.ts`

### Team collaboration

- [Chat and presence](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/server.ts): `src/server/server.ts`
- [Voice and screen sharing](https://github.com/agentsystemlabs/agent-office/blob/main/src/client/voice.ts): `src/client/voice.ts`
- [Shared whiteboard](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/whiteboard.ts): `src/server/whiteboard.ts`
- [Worker notifications](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/webhook.ts): `src/server/webhook.ts`

### Office services

- [HTTP and realtime server](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/server.ts): `src/server/server.ts`
- [Shared protocol](https://github.com/agentsystemlabs/agent-office/blob/main/src/shared/protocol.ts): `src/shared/protocol.ts`
- [Worker web services](https://github.com/agentsystemlabs/agent-office/blob/main/src/server/services.ts): `src/server/services.ts`
- [Chat and terminal search](https://github.com/agentsystemlabs/agent-office/blob/main/src/shared/search.ts): `src/shared/search.ts`

### Other components

- **Team member**
- **Agent CLI tools**
- **GitHub CLI**

## Connections

- Team member → 3D office client: uses
- 3D office client → Office world: renders
- 3D office client → Office interface: opens
- 3D office client → Client state: reads and updates
- 3D office client → HTTP and realtime server: sends realtime events
- HTTP and realtime server → 3D office client: sends office state
- HTTP and realtime server → Shared protocol: uses message types
- HTTP and realtime server → Project floors: manages projects
- HTTP and realtime server → Agent workers: dispatches worker actions
- Agent workers → Live terminals: runs processes
- Agent workers → Agent CLI tools: starts agents
- Agent workers → Task queues: manages tasks
- Agent workers → Git worktrees: uses worktrees
- Agent workers → GitHub boards and PRs: handles issue and PR actions
- GitHub boards and PRs → GitHub CLI: runs GitHub commands
- HTTP and realtime server → Chat and presence: handles shared chat and presence
- 3D office client → Voice and screen sharing: starts voice and sharing
- HTTP and realtime server → Shared whiteboard: handles board updates
- HTTP and realtime server → Worker notifications: tracks worker status
- HTTP and realtime server → Worker web services: scans worker services
- HTTP and realtime server → Chat and terminal search: normalizes search terms
- HTTP and realtime server → Live terminals: searches terminal buffers