Builder Wars launcher

The desktop app for Builder Wars, the game where you build products with your own AI agent and ship them on X. It is an Electron shell that puts your agent's terminal, the game and x.com side by side.

Download: builderwars.ai/download (Linux, Windows, macOS). This repository is the app's source. The game itself (website, API, scoring) is a separate service and not part of it.

One window with three panes:

• Terminal (left): xterm.js wired to a PTY (node-pty) in the main process. It runs your login shell ($SHELL -l, falling back to bash; PowerShell on Windows), or herdr --session builderwars when herdr mode is on. The toolbar under it has the agent picker, the herdr toggle, settings, a prompt box and the focus-cycle button.
• Game (center): https://builderwars.ai/dashboard in a WebContentsView. It is not an iframe, so the site's cookies are first-party and "Sign in with X" works inside the pane.
• X (right): https://x.com in a WebContentsView. A toggle switches it to the Grok chat URL. It has back and reload buttons.

The game and X panes share one persistent session partition, persist:web, stored under the app's userData folder (~/.config/Builder Wars on Linux, ~/Library/Application Support/Builder Wars on macOS, %APPDATA%\Builder Wars on Windows). You sign in to X once, and the login survives restarts. Settings live next to it in settings.json.

Build from source

Requirements: Node 22.12 or newer, pnpm 9 (corepack enable picks the version pinned in package.json), and on Linux a C/C++ toolchain and Python 3, because node-pty compiles from source there (macOS and Windows use its prebuilt binaries).

pnpm install --frozen-lockfile
pnpm dev        # electron-vite dev: renderer with HMR, main/preload rebuilt on change
pnpm build      # typecheck (renderer + electron tsconfigs) and electron-vite build -> out/
pnpm start      # run the built app (electron .)
pnpm test       # vitest: agent CLI mapping and quoting, bridge, layout math, updater, theme tokens and contrast, main-process helpers

Build output: out/main/index.js, out/preload/shell.js, out/preload/game.js, out/renderer/**. To package installers, see Packaging.

Troubleshooting:

• node-gyp: command not found during install: standalone pnpm builds (for example mise's, or @pnpm/exe) do not bundle node-gyp. Install it (npm install -g node-gyp) or use the pnpm that corepack provides.
• Electron failed to install correctly on pnpm dev: pnpm restored Electron from its cache without the binary. Run node node_modules/electron/install.js.

Options (CLI or env):

--url http://localhost:3000 or BW_SITE_URL=...	Game site URL. The bridge trusts only this origin. Precedence: --url, then env, then the setting, then https://builderwars.ai. In dev the env form is simplest: BW_SITE_URL=http://localhost:3000 pnpm dev.
BW_DATA_ROOT=dir	Moves userData (settings, the persist:web profile, the single-instance lock) into dir. Use it for tests or a second instance next to your real one.
BW_REGISTER_DEEPLINK=1	Registers builderwars:// for this binary at startup in dev builds. Packaged builds always register at runtime too.
BW_USE_HERDR=0/1	Overrides the herdr setting for this run (not saved).
BW_AUTOTEST=1	Self-test: once the site has loaded, calls builderwarsLauncher from inside the game page (empty prompt and foreign openX must be rejected, runPrompt('hello','claude') goes through the confirmation) and prints [autotest] lines to stdout.
BW_UPDATE_FEED_URL=http://127.0.0.1:<port>/	Test hook: packaged builds read updates from this generic feed (a folder with latest*.yml and the installers) instead of the public one. Accepted only for http(s) on 127.0.0.1, localhost or [::1]; anything else is ignored with a warning. See Updates.
BW_AUTOTEST_UPDATE=1 or quit	Update self-test, needs a packaged build and BW_UPDATE_FEED_URL: prints every updater event and state as [autotest] update ... lines and installs as soon as the update is ready. 1 installs through "Restart now" (quitAndInstall, the new version starts); quit through a plain quit (install on quit, nothing restarts). Quits if the feed has nothing newer.
BW_PTY_LOG=file	Appends raw PTY output to file.
BW_SNAPSHOT_DIR=dir, BW_DEBUG_BOUNDS=1, BW_DEVTOOLS=1	Diagnostics: PNG snapshots of the shell and game views during the self-test (never the X pane), pane bounds logging, detached DevTools for the shell.

Bridge (site <-> launcher), v1

builderwars.ai looks for window.builderwarsLauncher, validates its shape, and shows "Run in terminal" buttons only when it is present; in a normal browser nothing changes. The TypeScript type is BuilderwarsLauncherApi in src/bridge.ts; the process/IPC contract is electron/shared/contract.ts. The site's side of this contract lives in the game's own codebase, so a change to the shape or the version needs a matching site release: open an issue before changing it.

electron/preload/game.ts is the preload of the game view only. It defines the global only when the top-level document is on the configured site origin, so an OAuth hop to x.com in that view (or a sign-in popup that inherits the preload) gets nothing:

window.builderwarsLauncher = {
  version: 1, platform: "linux" | "macos" | "windows", agents: string[], defaultAgent: string | null, herdr: boolean,
  runPrompt(prompt: string, agent?: string | null): Promise<{ agent: string }>, // rejects with Error(message)
  openX(url?: string | null): Promise<void>,                                   // https://x.com URLs only
}

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗