wolfs-basement CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

Wolf's Basement is a visual RPG-themed terminal multiplexer that runs up to 4 Claude Code CLI sessions simultaneously. It has two modules: a pixel-art dungeon game (Basement) rendered in Phaser 3, and a multi-tab terminal interface (Terminal) — both served from a single Express + WebSocket server.

Commands

npm start          # Start the server (default port 3000)
npm run dev        # Same as npm start
node server.js     # Direct launch

No build step. No bundler. No tests. The frontend is served as static files from public/.

Architecture

Three-file system

File	Lines	Role
server.js	~1100	Express server, WebSocket hub, Claude CLI process manager, git/auth/dev-server endpoints
public/index.html	~3500	Terminal UI, agent cards, status bar, WebSocket client, all CSS inline
public/game/main.js	~3500	Phaser 3 game scene — all rendering, animations, spatial awareness, agent behaviors

Data flow

Browser (index.html + game/main.js)
  ↕ WebSocket (JSON messages)
Server (server.js)
  ↕ stdin/stdout (stream-json NDJSON)
Claude CLI processes (one per agent)

The server spawns Claude CLI with --output-format stream-json --input-format stream-json. It keeps the process alive between commands using --resume <sessionId>. User commands go in via proc.stdin.write(), responses stream back via proc.stdout as NDJSON lines.

CRITICAL — argument order in sendCommand: --resume <id> MUST be pushed BEFORE --allowed-tools. The CLI declares --allowed-tools <tools...> as variadic; if --resume <uuid> follows it, the parser may swallow --resume and the UUID as additional tool names, the resume silently fails, and the agent spawns a fresh session with no prior context. Symptom: after clicking "ALLOW ALL" on a permission prompt, the agent responds "Looking at the current state, it seems like you might have been in the middle of something..." Also pass tools as ONE comma-separated arg (tools.join(',')), not multiple positional args — that's the documented format and the safer pattern.