wow-ai

Chat with your local coding agents from inside World of Warcraft: Forever: Claude Code, OpenAI Codex and xAI's Grok Build. Send a task, go back to questing, get pinged in-game when the answer lands. No alt-tabbing, no /reload per message.

• Multiple chats, each its own persistent agent session (like separate terminals), running in parallel. Each chat picks its agent and its folder
• Live progress while the agent works: action count, elapsed time, the files it's editing and commands it's running
• Replies echoed into the game chat; /r replies to the agent when it was the last to message you
• The agent knows your character, level, zone, talents and professions (optional), and you can shift-click items, spells and quests into a message
• An Allow & retry button when Claude or Grok needs a command outside your allowlist
• A status light for the bridge, automatic retries, and recovery of your chats if the beta client wipes addon data

Nothing here injects code, reads game memory, or generates input. The addon uses documented addon APIs only; the companion reads your screen and writes ordinary files.

How it works, in one paragraph

WoW addons are sandboxed: no network, no file reads at runtime. Two doors remain. Out: the addon draws your message as a strip of colored 4-pixel squares in the top-left corner of the screen; the bridge screen-captures that corner four times a second, decodes it, and runs the chat's agent headless in the chat's folder. In: a load-on-demand addon reads its files from disk at the moment it is loaded, so the bridge writes the reply into a pool of 200 pre-made slot addons and the game loads a fresh one from a timer. Cheap "is it ready yet" checks ride on a third trick: an empty .wav won't play and a valid one will. Details in docs/ARCHITECTURE.md.

Agents

The bridge drives whichever of these you have installed; each chat can use a different one.

agent in bridge/config.json is the default (claude). /wow-ai agent codex switches the current chat, or right-click a chat in the left panel and pick Agent...; the reply bubbles and the game-chat echo are labelled with whoever answered. A session belongs to the agent that made it, so a chat that changes agent starts a fresh session there (its transcript stays). Install notes, the exact command lines, what each permission mode means per agent, and known limits are in docs/AGENTS.md.

Requirements

• Windows, NTFS
• World of Warcraft: Forever (tested on 1.60.1.69913, TOC 16001), windowed or borderless — exclusive fullscreen blocks screen capture
• Node.js 22.2 or newer
• At least one agent CLI, installed and logged in:
  • Claude Code: claude --version works
  • Codex: npm install -g @openai/codex, then codex once to log in
  • Grok Build: irm https://x.ai/cli/install.ps1 | iex, then grok login

Install

Step-by-step for a fresh machine, with troubleshooting: docs/INSTALL-WINDOWS.md. The short version:

git clone https://github.com/chelinho139/wow-ai
cd wow-ai
node setup.js --project "C:\path\to\the\project\you\want\to\work\on"

setup.js finds the client (pass --wow "<client folder>" if it can't), copies the addon into Interface\AddOns\WoWAI, writes bridge/config.json, reports which agent CLIs it found, and generates the slot pool and signal files (≈15,000 tiny files; that's normal — the client only discovers addon files at launch, so they have to exist up front).

Then fully quit and relaunch WoW, enable WoW AI on the AddOns screen, and start the bridge:

npm start               # in the current terminal (or: bridge\start.ps1)
bridge\start-window.cmd # double-click version: opens its own window

It restarts itself if it ever crashes. Ctrl+C (or closing the window) stops it. The banner lists every agent with where its executable was found, or what to install.

Upgrading from wow-claude

This project used to be called wow-claude, with a WoWClaude addon and a /wow-claude command. git pull (or clone the new name) and run node setup.js again: it copies your chats and settings from the old addon's saved data, removes the old WoWClaude addon and its slot folders so the two don't fight over /ai and /r, and rewrites the paths and the Claude settings in bridge/config.json into the new layout. Then quit and relaunch WoW. If you had installed the command, run npm unlink -g wow-claude and npm link again, and re-do /wow-ai bind <key> if you had a hotkey. Your agent sessions carry on: the bridge keeps them per chat.

wow-ai: start it from the project folder

Like the agent CLIs themselves, the bridge works in the folder you start it from. Install the command once:

npm link          # in the wow-ai folder; makes `wow-ai` available everywhere

Then, from any project:

cd C:\path\to\realms
wow-ai

Every chat that hasn't picked its own folder now works in realms, and the panel's cwd line shows it. wow-ai --project <dir> names the folder explicitly; npm start inside this repo falls back to defaultCwd in the config. Only one bridge can run at a time (two would fight over the screen and the slot files), so this sets the default folder rather than giving you one bridge per project.

Use

In game: /wow-ai opens the window. Until the bridge has answered, a Connect button sits where Send would be: start the bridge, click it, and the light turns green (a message typed before that stays in the box). Then click the input box, type, Enter. The reply arrives with the whisper sound; the window's light shows the bridge state (green/yellow/red, hover for details), and Reconnect shows up if the bridge goes quiet.

Right-clicking a chat in the left panel opens a small menu with Rename..., Folder... and Agent... (right-click again to close it); the trash can on the row deletes the chat after an OK/Cancel confirm. Folder... sets the folder this chat's agent works in (same as /wow-ai cd below), Agent... which agent answers it (same as /wow-ai agent); each chat keeps its own, so you can have chats on different projects, with different agents, side by side.

Click any message, or /wow-ai copy for the last reply, to open it in a selectable box for Ctrl+C.

The agent knows whe