Ever wondered what all those files in your WoW folder actually are?
wowlab reads your World of Warcraft install, tells you what every file is and whether it is safe to touch,
snapshots your whole setup, and lets you change things and change them back.
It runs on your own machine, never touches the game while it runs, and never uploads anything.

---

Why you might want it

• "I broke my UI and I don't know how." Take a snapshot before you experiment. If something goes wrong, wowlab undo puts every file back exactly as it was.
• "What is config-cache.wtf and can I delete it?" wowlab explain answers that for any file in your install: what it is, who writes it, when, and whether editing it is safe.
• "My addon settings are a mess." Read any addon's saved settings as plain text, with nothing executed and nothing changed.
• "I play on the Forever beta and nothing is documented." wowlab was built against a real Forever install: its folder layout, file formats and combat log are written up in plain words.
• "I want to see, and later plan, my character offline." wowlab char show already shows what wowlab's own small in-game addon recorded for a character. Planning offline is on the menu for a later wave.
• "My macros and keybinds grew over years." Coming next: a macro checker that finds broken spell names, overlong and duplicate macros and macros on no action bar, and a keybind report built from what you actually cast. See where it is now.

✨ What it does today

	Feature	Command
🔍	Explain any file. Every path in your install mapped: what it is, who writes it, when, and whether wowlab may edit it.	wowlab explain PATH · wowlab tree --explain
🩺	Health check. Finds your install, its flavors and versions, whether the game is running, and your server-sync settings.	wowlab doctor
📸	Snapshots. Save your whole setup (settings, keybinds, macros, addons and their saved data) and compare any two snapshots, down to the individual addon setting.	wowlab snap create · snap diff A B
↩️	Undo, for real. Put a snapshot back, or undo the last change. You see the plan first, and it refuses while the game is running.	wowlab snap restore · wowlab undo
📜	Read your saved data. Addon SavedVariables, CVars, keybinds, macros and your addon list, as readable text or JSON.	wowlab sv dump · cvar · binds · macros · addons
📚	Game data. Any game table for your exact build, from wago.tools, cached forever and keyed by build.	wowlab db2 fetch TABLE
⚔️	Combat log. A streaming combat-log reader and a live tail that follows the game as it writes, even across new log files.	wowlab log tail --follow
🎛️	Profiles. Save named UI setups (raid, clean, gamepad) and switch between them with one command. You see the plan first, applying one also deletes files created since it was saved, and wowlab undo reverses it.	wowlab profile save · profile apply
🔀	Merge addon settings. Copy one addon's settings between characters, or from a snapshot, without clobbering the rest. Conflicts are listed and never guessed, and it first checks that the client has been loading saved data correctly.	wowlab sv merge
🧩	The lab-addon and your characters. wowlab's own small in-game addon records a character's gear, talents, customization, collections, currencies and professions (never a name) when you log out, and reads them back offline.	wowlab addon install lab · wowlab char show
🎨	Customization looks. Browse every race's customization options from the game's own tables, save and compare looks, import one from a character, and open it all as a local web page. Data only: it never touches the game.	wowlab looks races · save · compare · page

See it in action (output from a test copy of a Forever install)

$ wowlab explain WTF/Account/<ACCOUNT>/SavedVariables/DBM-Party-Vanilla.lua
WTF/Account/<ACCOUNT>/SavedVariables/DBM-Party-Vanilla.lua (in flavor folder _classic_beta_)
  what:         Account-wide addon data (`## SavedVariables:`)
  written by:   Client on logout / `/reload`
  edit:         yes, through wowlab's write gate only, with the client closed
  tier:         A: ordinary addon-user behaviour
  read by:      `luadata`

$ wowlab sv dump SavedVariables/DBM-StatusBarTimers.lua
DBT_AllPersistentOptions["Default"]["DBM"]["TimerY"] = -260
DBT_AllPersistentOptions["Default"]["DBM"]["TimerPoint"] = "TOPRIGHT"
DBT_AllPersistentOptions["Default"]["DBM"]["HugeBarsEnabled"] = true
…

$ wowlab doctor --offline
Flavor _classic_beta_: product wow_classic_beta, version 1.60.1.69913
Client: not running
Snapshot store: ~/.local/share/wowlab/store (not created yet)

🛡️ The safety promises

Important

These are hard rules in the code, checked by tests on every change, not intentions.

• Reading never writes. Looking at your install changes nothing: no temp files, caches or lock files inside it.
• One door for every change. Anything wowlab writes goes through a single write gate. The gate refuses while the game is running, takes a snapshot first, records what it did, and replaces files atomically. There is no "force" switch that skips any of that.
• No Lua is ever run. Addon data is read as data by a strict parser. Functions or code in a saved file are refused, never executed.
• Nothing is lost. The parsers keep every byte they don't understand. An unedited file comes back byte for byte.
• Stays on your machine. No accounts, no server, no uploads. The only network access is downloading public game tables from wago.tools, and you can skip it with --offline.
• Clearly out of bounds, permanently. No memory reading, no injection, no packet tampering, no input automation, no touching game Data/ or executables, no bypassing integrity checks (ADR-0023). wowlab only changes what the game itself treats as your settings.

⚙️ How it works

flowchart LR
    I[("Your WoW install<br/>WTF · Interface · Logs")]
    subgraph core["wowlab_core"]
      D[install discovery] --> L[layout + file map]
      L --> P["parsers<br/>SavedVariables · WTF · TOC · combat log"]
      G[game data<br/>wago.tools, by build]
      S[(snapshot store)]
      W{{write gate}}
    end
    I -- "read only" --> D
    P --> CLI[wowlab CLI]
    G --> CLI
    CLI -- "restore / undo / apply / merge" --> W
    W -- "1. game closed?<br/>2. snapshot first<br/>3. atomic write" --> I
    W --> S

Loading

Flavor folders, product codes and build numbers are discovered from your install, never hard-coded, so wowlab works the same on retail and on World of Warcraft: Forever. The details: docs/LAB_PLAN.md (the spec), docs/LAB_FILE_MAP.md (every path) and docs/LAB_FORMATS.md (every file format).

🧭 Where it is now

wowlab grows in waves: the owner picks each one after reviewing the last. Waves 1 and 2 are done: everything in the table above.

wowlab is becoming something other players can install (owner decision, 2026-10-13; ADR-0031). The promise does not change: reading never writes, every change asks first, a snapshot comes before it and wowlab undo reverses it, and nothing is uploaded. Wave 4, the first public release, is in progress:

	Feature	What you'll be able to do
📦	Releases	Install a tagged GitHub release with one uv tool install line, and check it against published SHA-256 sums. No installer, no app store, no hosted version.
🪟	Windows, tested	The test suite runs on Windows and macOS in CI, and a person runs the first-run flow on a real install of each before it is called supported. Until then it says "untested".
👋	A first run that explains itself	wowlab doctor finds your install (or says how to point it at one), says plainly what wowlab will and won't do, offers a first snapshot (kept in wowlab's own store, never in your install) and verifies it.
🙈	Bug reports without your names	wowlab doctor --redact prints output that is safe to paste into an issue: no character, realm, account, BattleTag, guild or home path.
📝	macros check	Finds macros over the length limit, spell names not in your spellbook, macros on no action bar, duplicates, unbalanced [ ] and a misplaced #showtooltip. Read-only.
⌨️	binds coach	From your own combat log: spells you cast often on awkward keys, spells you cast with no bind, and binds you never use. Read-only; the "awkward key" table is a default you can edit. May arrive in the second release.
🖥️	wowlab ui	A local page in your browser, served only to this machine, that runs wowlab's commands. Its first view is an install explorer: what every file is, and whether it is safe to touch. In this release it offers the commands that save only to wowlab's own data (snapshots, profiles, saved looks, the db2 cache, pages). Some of these overwrite what they saved before, such as looks import-char --replace, and none of them touches the game folder. It offers no command that changes your game files or that asks before changing anything (--yes).

After that, Wave 5 adds to wowlab ui the commands that ask before changing anything (--yes), each behind the same confirm step as the CLI, and is aimed at the second public release. Wave 3 was trimmed on 2026-10-14: its game-table database, talent planner and alt-dashboard are deferred, because players already have good talent planners. The character list and a daily check of the wiki stay.

Thirty days after the first release, the owner checks GitHub's own counts (no telemetry). If they show little use beyond the owner, meaning fewer than 50 downloads or fewer than 5 issues or discussions from other people, the owner may freeze the public side: releases stay up, no new public features are added, and wowlab goes back to being a personal lab. The plan and its tickets: docs/LAB_PLAN.md §15 and docs/BACKLOG.md.

🌌 The full vision

Here is what wowlab becomes as the ideas on the menu are built. It is a menu, not a promise: each wave is picked one at a time.

🧙 Your character, offline

• Plan builds without logging in. Capture a character and plan talents and gear offline, including Forever's own talent systems (char-planner). Export to SimulationCraft and run sims locally (simc-bridge).
• See your character in 3D. Render it in the browser from your own game files, with gear and transmog; design outfits; pose it, light it, turn it around, and export it to 3D formats or a printable model (character-studio, photo-studio, char-export).
• Every alt at a glance. A dashboard over every character; a timeline of how each one grew; scheduled archives of your full state (alt-dashboard, digital-twin, time-capsule).
• Collect smarter. What's left to collect and the cheapest order to get it; what in your bags is dead weight across every alt, and where to send it (collection-router, bag-triage).
• Learn your class faster. Nightly flashcards built from your spellbook, your talents, boss abilities and what actually killed you (drill-cards).
• Tell your character's story. A printable book and roleplay profile with your gear, portrait, firsts, zones and notable fights (codex). Also a D&D-style sheet, and a roguelike seeded by your real gear (tabletop-sheet, roguelike-me).
• Customize from inspiration. Match a concept image to the customization choices and appearances you own (look-from-image).

🎛️ Your UI, keybinds and settings

• Your whole setup as a file. Describe CVars, binds, macros and addon settings in one file, then plan, apply and roll back, with drift detection (wow-as-code).
• Keybinds that fit how you play. Spells you cast most on your easiest keys, spells you click that have no bind, and binds you never use, applied with undo (keybind-coach; the read-only report is planned for the first public releases).
• Macros that don't silently break. A linter that checks spell names and ranks, conditionals, length, unused and duplicate macros, with fixes through the write gate (macro-doctor; the check is planned for the first public release, and fixes are written only if a test shows the game keeps an edited macro file).
• Look and feel. Reversible font and texture packs, and nameplates designed outside the game with a live preview (skin-packs, nameplate-designer).
• A map of your install. A local website of your install, every file annotated, with viewers for saved data, settings and your snapshot timeline (explorer).

🧰 Addons

• Install and update addons safely. From GitHub, CurseForge or Wago, pinned and undoable, including the addon's saved data (addon-manager).
• Know where your addons came from. Compare every file to its upstream release and flag repacks or local edits (addon-provenance).
• Will it break on Forever? A static scan for the TOC version, removed APIs, the build-number trap and calls that go secret in combat (addon-audit).
• Is the game really loading your saved data? A doctor check that catches the SavedVariables loader bug if it ever returns (sv-health).
• For addon authors. Scaffolding, type stubs from the game's own API docs, a headless test harness, an in-game REPL, and an agent-friendly server over your install (addon-kit, api-types, addon-harness, dev-console, api-rag, lab-mcp).

📚 Game data and the world

• Query the game like a database. SQL over every game table, across builds; relationship graphs of items, spells, quests, NPCs and zones (db2lake, azeroth-graph).
• See what changed in each beta build. Automatic changelogs of the tables you care about, and hotfixes overlaid (build-diff, hotfix-reader).
• Fill in Forever's missing quests. Record givers, turn-ins and objectives as you play, exported as corrections Questie can use (quest-recorder).
• Auction-house memory. Your own price history, linked to patch changes that move prices (market-memory).
• Lore answers with sources. Questions answered only from quest, NPC and gossip text in the game's tables, with citations (lore-companion).
• Straight from the game files. Read models and textures from your own install, which unlocks everything 3D (casc-source).

📡 Live, fun and forensic

• Stream overlays and smart-home triggers. A local event feed from your saved data and combat log, driving OBS, Stream Deck, Home Assistant or Discord (event-bus, overlay-sinks).
• Your play, visualized. Fight replays and generative art from combat logs, heatmaps of where you've been, dashboards over your sessions (log2art, zone-heatmap, play-lake).
• Tidy screenshots. Tagged by character, zone and date, and searchable (screenshot-organizer).
• Why did it crash? Crash reports linked to the addons, settings and zone at the time (crash-forensics).
• Play between sessions. Offline mini-games or planners whose results your addon picks up at next login (companion-loop).

👥 Social (waiting on a privacy decision)

• Remember good groups. Who you grouped with, their role and your notes (crew-book), and which dungeon groups your online guild could form right now (comp-builder). These store other players' names, so they wait for their own privacy decision: opt-in, local only, never exported.

🚀 Try it

Note

wowlab runs on your own machine, against your install, under your control, and never uploads anything. Tagged GitHub releases are on the way (ADR-0031); until the first one, it runs from source. There is no hosted version. It is developed on macOS; untested on Windows and Linux.

You need uv (it brings Python 3.12). A game install is not needed to run the tests.

git clone https://github.com/sandgraal/wowlab && cd wowlab
make setup
uv run wowlab doctor        # finds your install and checks everything
uv run wowlab --help        # every command

Set WOWLAB_WOW_ROOT if your install is not in a default location (.env.example). Machine setup without a package manager: docs/SETUP.md.

Tip

Exit codes: 0 ok, 1 error, 2 usage, 3 refused by the write gate. Only these commands change your install: snap restore, undo, profile apply, sv merge and addon install / addon remove. Every one goes through the write gate and shows the plan and asks first unless you pass --yes; most of them also take --dry-run.

Developer commands

Target	What it does
make lint	ruff check, ruff format check, mypy --strict. The commit gate.
make test	The full pytest suite. Anything marked live is excluded and never runs in CI.
make test-parser	Parser fixtures and round-trip suites. Required green for any parser change.
make hooks-test	The agent hook scripts under Python 3.12 and 3.9.
make ci	Everything CI runs.

🏗️ How it's built

wowlab is written by Claude Code agents coordinated by a conductor session, while the owner makes every decision and captures the real test files from the game. Each change is a small ticket with checkable acceptance criteria. Every branch gets an independent code review, plus security and WoW-accuracy reviews wherever they apply. The files that rewrite your data (the SavedVariables parser, the write gate, sv-merge and profiles) get their tests written first by a different agent than the one that writes the code. Test files are real captures from the game, scrubbed of names and identifiers before they are committed. Details: docs/AGENT_WORKFLOW.md and AGENTS.md.

lab/core/   wowlab-core: the library and the wowlab CLI (later apps: lab/<app>/)
scripts/    repository tooling, including the fixture capture and scrub tool
tests/      tests for the agent harness hooks
docs/       spec, formats, file map, ideas, decisions, backlog, glossary, workflow
.claude/    agent definitions, skills, path rules, guard hooks

📖 Documents

Document	What it holds
The wiki	Guides for every command, the safety rules in plain words, a command reference, notes on the Forever beta, a glossary and the roadmap.
docs/LAB_PLAN.md	The spec: purpose, architecture, every module, testing, how waves work, the Wave 2, 3 and 4 plans.
docs/LAB_FILE_MAP.md	Every path in an install: what it is, who writes it, whether it is safe to edit.
docs/LAB_FORMATS.md	The client file formats, with what real Forever captures showed.
docs/LAB_IDEAS.md	The menu for later waves.
docs/GLOSSARY.md	WoW and client terms, several of them misleading.
docs/DATA_SOURCES.md	The install, wago.tools, and a log of every surprise.
docs/DECISIONS.md	Architecture decisions (ADRs).
docs/BACKLOG.md	The current wave's tickets.
docs/handoffs/	Capture runbooks and wave reviews.
AGENTS.md	The constitution: the hard rules above, in full.
docs/AGENT_WORKFLOW.md · docs/SETUP.md	How work moves; machine setup.

License and affiliation

Apache-2.0. World of Warcraft and Blizzard Entertainment are trademarks of Blizzard Entertainment, Inc. wowlab is an independent project, not affiliated with or endorsed by Blizzard. No game assets or Blizzard code are committed here. Security and privacy reports: SECURITY.md. This repository previously held a different project, retired on 2026-09-21 (ADR-0025, git tag bronze-final).