# chelinho139/wow-ai architecture

> Architecture diagram of the GitHub repository chelinho139/wow-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chelinho139/wow-ai
- Repository: https://github.com/chelinho139/wow-ai

## Overview

wow-ai connects a World of Warcraft addon to local coding-agent CLIs through a screen-captured pixel-strip channel and load-on-demand reply slots. The player sends a task in-game; the bridge decodes it, runs the selected agent, and returns the reply for the addon to display and echo in chat. Separate capabilities include persistent multi-chat sessions, character context, map layers and navigation, gathering nodes, macros, permission retries, and bridge-status signals. The bridge’s central orchestration and protocol modules are excerpted; addon internals and some integrations are represented from README documentation, so their detailed internal links are omitted.

Main entry points: [`bridge/bridge.js`](https://github.com/chelinho139/wow-ai/blob/main/bridge/bridge.js) (Bridge orchestrator), [`addon/WoWAI/WoWAI.lua`](https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/WoWAI.lua) (WoW AI addon), [`bridge/agents.js`](https://github.com/chelinho139/wow-ai/blob/main/bridge/agents.js) (Agent adapters), [`addon/WoWAI/Inbox.lua`](https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/Inbox.lua) (Inbox and replies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game["In-game experience"]
  node_addon["WoW AI addon<br/>[WoWAI.lua]"]
  node_pixel["Pixel codec<br/>[Codec.lua]"]
  node_inbox["Inbox and replies<br/>[Inbox.lua]"]
  node_mapaddon["Map display<br/>[Map.lua]"]
end

subgraph group_transport["Bridge transport"]
  node_capture["Screen capture<br/>[capture_x11.py]"]
  node_macapture["macOS capture<br/>[capture_mac.py]"]
  node_bridge["Bridge orchestrator<br/>[bridge.js]"]
  node_protocol["Protocol and formatting<br/>[protocol.js]"]
  node_slots["Reply slot files<br/>[install-slots.js]"]
  node_state[("Chat and session state<br/>[bridge.js]")]
end

subgraph group_runtime["Agent runtime"]
  node_agents["Agent adapters<br/>[agents.js]"]
end

subgraph group_capabilities["Chat capabilities"]
  node_chat["Multi-chat sessions<br/>[bridge.js]"]
  node_context["Character context<br/>[WoWAI.lua]"]
  node_map["Routes and map layers<br/>[protocol.js]"]
  node_gather["Gathering spawns<br/>[Map.lua]"]
  node_macros["Macro creation<br/>[protocol.js]"]
  node_permissions["Allow and retry<br/>[agents.js]"]
  node_status["Bridge status<br/>[bridge.js]"]
end

node_player(("Player"))
node_wow(("WoW client"))
node_agentcli(("Local agent CLIs"))

node_player -->|"sends task"| node_addon
node_addon -->|"encodes message"| node_pixel
node_pixel -->|"draws strip"| node_wow
node_wow -->|"shows strip"| node_capture
node_wow -.->|"shows strip"| node_macapture
node_capture -->|"emits decoded record"| node_bridge
node_macapture -->|"emits decoded record"| node_bridge
node_bridge -->|"uses protocol"| node_protocol
node_bridge -->|"starts agent"| node_agents
node_agents -->|"runs CLI"| node_agentcli
node_bridge -->|"persists sessions"| node_state
node_bridge -->|"writes reply slots"| node_slots
node_slots -->|"provides slot data"| node_inbox
node_wow -->|"loads reply slot"| node_inbox
node_inbox -.->|"displays reply"| node_addon
node_addon -->|"echoes reply"| node_player
node_addon -->|"supplies game context"| node_context
node_agents -.->|"provides map tools"| node_map
node_bridge -->|"processes map layers"| node_map
node_map -->|"ships map layers"| node_mapaddon
node_mapaddon -->|"shows routes"| node_wow
node_wow -->|"filters spawns"| node_gather
node_protocol -->|"extracts macros"| node_macros
node_bridge -->|"handles denials"| node_permissions
node_agents -->|"reports refusals"| node_permissions
node_bridge -->|"updates signals"| node_status
node_status -->|"signals presence"| node_wow

click node_addon "https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/WoWAI.lua"
click node_pixel "https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/Codec.lua"
click node_inbox "https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/Inbox.lua"
click node_mapaddon "https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/Map.lua"
click node_capture "https://github.com/chelinho139/wow-ai/blob/main/bridge/capture_x11.py"
click node_macapture "https://github.com/chelinho139/wow-ai/blob/main/bridge/capture_mac.py"
click node_bridge "https://github.com/chelinho139/wow-ai/blob/main/bridge/bridge.js"
click node_protocol "https://github.com/chelinho139/wow-ai/blob/main/bridge/protocol.js"
click node_slots "https://github.com/chelinho139/wow-ai/blob/main/bridge/install-slots.js"
click node_state "https://github.com/chelinho139/wow-ai/blob/main/bridge/bridge.js"
click node_agents "https://github.com/chelinho139/wow-ai/blob/main/bridge/agents.js"
click node_chat "https://github.com/chelinho139/wow-ai/blob/main/bridge/bridge.js"
click node_context "https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/WoWAI.lua"
click node_map "https://github.com/chelinho139/wow-ai/blob/main/bridge/protocol.js"
click node_gather "https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/Map.lua"
click node_macros "https://github.com/chelinho139/wow-ai/blob/main/bridge/protocol.js"
click node_permissions "https://github.com/chelinho139/wow-ai/blob/main/bridge/agents.js"
click node_status "https://github.com/chelinho139/wow-ai/blob/main/bridge/bridge.js"

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_addon,node_pixel,node_inbox,node_mapaddon,node_wow toneBlue
class node_capture,node_macapture,node_bridge,node_protocol,node_slots,node_state toneAmber
class node_agents toneMint
class node_chat,node_context,node_map,node_gather,node_macros,node_permissions,node_status toneRose
class node_player,node_agentcli toneIndigo
```

## Components

### In-game experience

- [WoW AI addon](https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/WoWAI.lua): `addon/WoWAI/WoWAI.lua`
- [Pixel codec](https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/Codec.lua): `addon/WoWAI/Codec.lua`
- [Inbox and replies](https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/Inbox.lua): `addon/WoWAI/Inbox.lua`
- [Map display](https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/Map.lua): `addon/WoWAI/Map.lua`

### Bridge transport

- [Screen capture](https://github.com/chelinho139/wow-ai/blob/main/bridge/capture_x11.py): `bridge/capture_x11.py`
- [macOS capture](https://github.com/chelinho139/wow-ai/blob/main/bridge/capture_mac.py): `bridge/capture_mac.py`
- [Bridge orchestrator](https://github.com/chelinho139/wow-ai/blob/main/bridge/bridge.js): `bridge/bridge.js`
- [Protocol and formatting](https://github.com/chelinho139/wow-ai/blob/main/bridge/protocol.js): `bridge/protocol.js`
- [Reply slot files](https://github.com/chelinho139/wow-ai/blob/main/bridge/install-slots.js): `bridge/install-slots.js`
- [Chat and session state](https://github.com/chelinho139/wow-ai/blob/main/bridge/bridge.js): `bridge/bridge.js`

### Agent runtime

- [Agent adapters](https://github.com/chelinho139/wow-ai/blob/main/bridge/agents.js): `bridge/agents.js`

### Chat capabilities

- [Multi-chat sessions](https://github.com/chelinho139/wow-ai/blob/main/bridge/bridge.js): `bridge/bridge.js`
- [Character context](https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/WoWAI.lua): `addon/WoWAI/WoWAI.lua`
- [Routes and map layers](https://github.com/chelinho139/wow-ai/blob/main/bridge/protocol.js): `bridge/protocol.js`
- [Gathering spawns](https://github.com/chelinho139/wow-ai/blob/main/addon/WoWAI/Map.lua): `addon/WoWAI/Map.lua`
- [Macro creation](https://github.com/chelinho139/wow-ai/blob/main/bridge/protocol.js): `bridge/protocol.js`
- [Allow and retry](https://github.com/chelinho139/wow-ai/blob/main/bridge/agents.js): `bridge/agents.js`
- [Bridge status](https://github.com/chelinho139/wow-ai/blob/main/bridge/bridge.js): `bridge/bridge.js`

### Other components

- **Player**
- **WoW client**
- **Local agent CLIs**

## Connections

- Player → WoW AI addon: sends task (evidence: `README.md`)
- WoW AI addon → Pixel codec: encodes message (evidence: `README.md`)
- Pixel codec → WoW client: draws strip (evidence: `README.md`)
- WoW client → Screen capture: shows strip (evidence: `README.md`)
- WoW client → macOS capture: shows strip (evidence: `README.md`)
- Screen capture → Bridge orchestrator: emits decoded record (evidence: `bridge/capture_x11.py`)
- macOS capture → Bridge orchestrator: emits decoded record (evidence: `bridge/capture_mac.py`)
- Bridge orchestrator → Protocol and formatting: uses protocol (evidence: `bridge/bridge.js`)
- Bridge orchestrator → Agent adapters: starts agent (evidence: `bridge/bridge.js`)
- Agent adapters → Local agent CLIs: runs CLI (evidence: `bridge/agents.js`)
- Bridge orchestrator → Chat and session state: persists sessions (evidence: `bridge/bridge.js`)
- Bridge orchestrator → Reply slot files: writes reply slots (evidence: `README.md`)
- Reply slot files → Inbox and replies: provides slot data (evidence: `bridge/install-slots.js`)
- WoW client → Inbox and replies: loads reply slot (evidence: `README.md`)
- Inbox and replies → WoW AI addon: displays reply
- WoW AI addon → Player: echoes reply (evidence: `README.md`)
- WoW AI addon → Character context: supplies game context (evidence: `README.md`)
- Agent adapters → Routes and map layers: provides map tools (evidence: `README.md`)
- Bridge orchestrator → Routes and map layers: processes map layers (evidence: `README.md`)
- Routes and map layers → Map display: ships map layers (evidence: `README.md`)
- Map display → WoW client: shows routes (evidence: `README.md`)
- WoW client → Gathering spawns: filters spawns (evidence: `README.md`)
- Protocol and formatting → Macro creation: extracts macros (evidence: `bridge/protocol.js`)
- Bridge orchestrator → Allow and retry: handles denials (evidence: `bridge/bridge.js`)
- Agent adapters → Allow and retry: reports refusals (evidence: `bridge/agents.js`)
- Bridge orchestrator → Bridge status: updates signals (evidence: `bridge/bridge.js`)
- Bridge status → WoW client: signals presence (evidence: `README.md`)
