wow-ai

Chat with your local coding agents from inside World of Warcraft: Forever: Claude Code, OpenAI Codex, xAI's Grok Build, Google's Antigravity CLI and Hermes Agent. 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, professions and quest log (optional), and you can shift-click items, spells and quests into a message
• The agent can draw on your world map: numbered routes, quest stops and marks, with a navigator arrow that walks you from stop to stop
• Herb and ore spawns on the world map, filtered by your gathering skill (/wow-ai map ore, /wow-ai map herb)
• Ready-made macros: ask for one and the reply carries a Create macro button that saves it and puts it on your cursor, ready to drop on an action bar (/wow-ai macro undo reverts it)
• 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 (and map layers) if the beta client wipes addon data
• Runs on Windows, on Linux with the game under Wine, and on macOS with a native client

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. Map layers travel the same way: the agent's tools hand them to the bridge, which keeps them versioned and ships them inside the slot files. Details in docs/ARCHITECTURE.md and docs/MAP.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), or Linux with the game under Wine on an X11 session and python3 (see docs/INSTALL-LINUX.md), or macOS with a native client and python3
• World of Warcraft: Forever (tested on 1.60.1.69913 and 1.60.1.69977, 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
  • Antigravity (agy): install Google's Antigravity CLI, then run agy once to log in
  • Hermes Agent (hermes): install it, then run hermes setup once

Install

Windows

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.

Linux (Wine)

Details and capture troubleshooting: docs/INSTALL-LINUX.md. The short version:

git clone https://github.com/chelinho139/wow-ai
cd wow-ai
node setup.js --project ~/path/to/the/project   # finds the client in $WINEPREFIX, ~/.wine...; or pass --wow "<client folder>"
npm start

The bridge captures the game window through X11 (bridge/capture_x11.py, no packages needed) and writes the slot files straight into the Wine prefix. Check the capture once: send any message from the game and, while the strip of colored squares is in the top-left corner, run npm run probe in a second terminal. It saves what the capture sees to bridge/probe.png and says whether it decoded the strip.

macOS (native client)

Same commands as Linux: node setup.js --project <dir> (it looks for the client under /Applications/World of Warcraft and ~/Applications/World of Warcraft; pass --wow "<client folder>" otherwise), then npm start. The bridge captures the game window with bridge/capture_mac.py, which needs only python3: it finds the window through System Events and grabs its top-left corner with the built-in screencapture. The first run asks for two permissions in System Settings, Automation (System Events) and Screen Recording, for the terminal the bridge runs in. npm run probe:mac saves what the capture sees to bridge/probe.png and says whether it decoded the strip.

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 wo