From 33b56b92f2dcd3869e1361a2270e984bfff7de3b Mon Sep 17 00:00:00 2001 From: Emile Date: Thu, 29 Oct 2026 19:51:27 -0400 Subject: [PATCH] Move the server and client code maps into folder CLAUDE.md files (0.22.3) The root CLAUDE.md loads in every session in this folder, including ones that never touch dungeon code. The server and client file maps (about 5.9k characters) now sit in server/CLAUDE.md and client/CLAUDE.md, which load only when work reaches those folders. The text is moved word for word; the root file points to them and keeps the launcher, the cubefarm command and shared/. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 51 +---------------------------------------------- client/CLAUDE.md | 15 ++++++++++++++ package-lock.json | 4 ++-- package.json | 2 +- server/CLAUDE.md | 43 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 62 insertions(+), 53 deletions(-) create mode 100644 client/CLAUDE.md create mode 100644 server/CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md index 41d80b7..0d7f438 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,45 +48,7 @@ before you open a PR. ## Code map -Server (`server/`, Node + Express 5 + ws, run by tsx in development; esbuild bundles it into `dist-server/` for npm): -- `index.ts`: entry; picks the real or demo backend, REST routes under `/api`, the `/ws` and `/ws/term` websockets, serves `dist/`, shutdown. -- `config.ts`: `SWARM_PORT` (default 4417), `SWARM_HOME` (default `codedungeon-home` beside the repo), `--demo`, state file, intervals, - the default projects folder. -- `swarm.ts`: the orchestrator. Floors, agents, scheduling/auto-assign, dev → QA → fix → merge loop, dev and QA - prompts, CEO job queue, phone messages, persistence (`state.json` / `demo-state.json`), websocket fan-out. -- `agentRunner.ts`: one Agent SDK session; options, env stripping, Playwright MCP, and turning the SDK stream into - terminal lines. -- `cliRunner.ts`: the terminal runtime (the default): one agent as the real CLI in a node-pty, same session contract - as `agentRunner.ts`. Claude Code reports through HTTP hooks (`POST /api/hooks/:token`; PreToolUse approves every - call); Codex reports turn endings (notify) and, once the manager trusts them, its steps (`-c hooks.*`); OpenCode - only turn endings. Codex/OpenCode screenshots are collected from the session's Playwright output folder. Esc in a - terminal ends the session as `interrupted`. The CEO's office tools are served over MCP (`/api/mcp/:token`). -- `ptyHost.ts`: the terminal keeper, a detached process of its own (`launch` re-spawns it outside the office's process - tree) holding the CLIs' pseudo-terminals and relaying their hooks, so agents keep working through office restarts. - `ptyClient.ts` is the office's side (start/connect, spawn, adopt after a restart, local fallback); `ptyProtocol.ts` - their JSON-lines messages. The launcher's `office:shutdown` says `restart: false` when quitting: CLIs stop then. - A developer's CLI stays at its prompt after the task (`keepAlive`): follow-ups and prompts typed there reuse it. -- `boxes.ts`, `boxRunner.ts`: coders in Upstash Boxes (`@upstash/box`). `boxes.ts` is the box layer: the API key and - GitHub token (env or the Windows user environment), the base snapshot (`BASE_SETUP`), desk and sign-in scripts, and - the events program every hook and status line runs in a box. `boxRunner.ts`'s `BoxPty` implements `Pty` for a CLI - in tmux in the box: `tmux attach` over a PTY session (reconnects with backoff), events followed with `tail -F`. - `shared/cloudBoxes.ts` holds the settings and who may move into a box. Testers stay local. -- `clis.ts`: the CLIs (Claude Code from the SDK's bundled binary, Codex, OpenCode): detection, Windows `.cmd` shim - unwrapping, each one's command line, and the helper scripts they call back with. -- `terminal.ts`: `AgentTerminal`, a headless xterm mirror per agent (replay for late viewers, saved to disk), its - `/ws/term` viewers, and keystrokes/resizes to the running CLI. -- `ceo.ts`: the CEO's office MCP tools (`createOfficeTools`, zod-validated), `ceoSystemPrompt`, `ceoJobPrompt`. -- `backend.ts`: the `Backend` interface (everything touching GitHub, git, disk and sessions) and `realBackend`. -- `demo.ts`: `createDemoBackend()`: fake GitHub, fake sessions (drawn into the agent's terminal in the terminal runtime), fake previews for `--demo`. -- `github.ts`: all GitHub access through the `gh` CLI. -- `workspace.ts`: floor checkouts, per-agent worktrees (`/workspaces/__/desks/`), - fast-forwarding main, per-repo git lock, stopping processes an agent left running. -- `exec.ts`: `run` / `git` / `gh`: `execFile` without a shell, prompts disabled, `CommandError` with stderr. -- `previews.ts`: one preview per floor: ports (6300 + floor), statuses, config validation. -- `previewRunner.ts`: checks out, installs and runs a floor's app in its preview worktree; kills the process tree. -- `httpError.ts`: `HttpError(status, message)`. -- `officeUpdate.ts`: the office's self-update: the drain decision, the launcher contract (IPC, `last-update.json`). -- `pacing.ts`: pacing new work after Claude's usage warnings: the start/skip decision and the usage state. +The server's and client's file-by-file maps are in `server/CLAUDE.md` and `client/CLAUDE.md`. The `cubefarm` command (`bin/cubefarm.js`, plain JS): checks Node/git/gh/Claude login, starts `dist-server/index.js`, opens the browser; `login` and `doctor` subcommands. @@ -101,17 +63,6 @@ Shared (`shared/`, imported by both sides): - `types.ts`: the REST/websocket contract (`WorldSnapshot`, `ServerEvent`, views, settings). - `issues.ts`: issue conventions (`swarm:` labels, `Depends on #N`, hold-up ranking). -Client (`client/`, Vite root; React 19, R3F, drei, zustand): -- `src/world/`: the 3D building: floors, desks, characters (`appearance.ts`, `characterParts.ts`), elevator, - whiteboard, player movement and collisions (`layout.ts`), canvas textures (`draw.ts`), `toys/` (Rapier physics: the dart board, its darts and the chalk tally; rules in `dartboard.ts`), `nav.ts` (grid pathfinding), `dungeon.ts` (the plan: hall, gallery, chambers), `models.tsx` (glTF models in - `client/public/models`, built from the CC0 Quaternius packs by `scripts/build-models.py`), `stone.ts` (tiling stone - materials), `lightPool.tsx` (torches register as anchors; a fixed pool of point lights follows the nearest). -- `src/ui/`: HTML overlays: HUD, terminal (`LiveTerminal.tsx`: xterm.js on `/ws/term`), Kanban, manager's console, - phone, elevator panel, app - viewer, sounds (`sfx.ts`). -- `src/store.ts`: the zustand store; `apply(ServerEvent)` folds websocket events into UI state. -- `src/api.ts`: REST calls; errors become toasts. -- `src/net.ts`: the websocket connection with reconnect. `src/perf.tsx`: render pausing, adaptive DPR, `?stats`. ## Conventions diff --git a/client/CLAUDE.md b/client/CLAUDE.md new file mode 100644 index 0000000..ab0699a --- /dev/null +++ b/client/CLAUDE.md @@ -0,0 +1,15 @@ +# Client code map + +Loaded when working under `client/`. The rest of the rules are in the root CLAUDE.md. + +Client (`client/`, Vite root; React 19, R3F, drei, zustand): +- `src/world/`: the 3D building: floors, desks, characters (`appearance.ts`, `characterParts.ts`), elevator, + whiteboard, player movement and collisions (`layout.ts`), canvas textures (`draw.ts`), `toys/` (Rapier physics: the dart board, its darts and the chalk tally; rules in `dartboard.ts`), `nav.ts` (grid pathfinding), `dungeon.ts` (the plan: hall, gallery, chambers), `models.tsx` (glTF models in + `client/public/models`, built from the CC0 Quaternius packs by `scripts/build-models.py`), `stone.ts` (tiling stone + materials), `lightPool.tsx` (torches register as anchors; a fixed pool of point lights follows the nearest). +- `src/ui/`: HTML overlays: HUD, terminal (`LiveTerminal.tsx`: xterm.js on `/ws/term`), Kanban, manager's console, + phone, elevator panel, app + viewer, sounds (`sfx.ts`). +- `src/store.ts`: the zustand store; `apply(ServerEvent)` folds websocket events into UI state. +- `src/api.ts`: REST calls; errors become toasts. +- `src/net.ts`: the websocket connection with reconnect. `src/perf.tsx`: render pausing, adaptive DPR, `?stats`. diff --git a/package-lock.json b/package-lock.json index 010267e..8ad3790 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "codedungeon", - "version": "0.22.2", + "version": "0.22.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "codedungeon", - "version": "0.22.2", + "version": "0.22.3", "license": "MIT", "dependencies": { "@anthropic-ai/claude-agent-sdk": "^0.3.291", diff --git a/package.json b/package.json index 9842707..4feee58 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "codedungeon", - "version": "0.22.2", + "version": "0.22.3", "description": "A medieval dungeon you walk through, where every coder is a real AI coding agent working through your GitHub issues.", "keywords": [ "claude-code", diff --git a/server/CLAUDE.md b/server/CLAUDE.md new file mode 100644 index 0000000..9b52b4f --- /dev/null +++ b/server/CLAUDE.md @@ -0,0 +1,43 @@ +# Server code map + +Loaded when working under `server/`. The rest of the rules are in the root CLAUDE.md. + +Server (`server/`, Node + Express 5 + ws, run by tsx in development; esbuild bundles it into `dist-server/` for npm): +- `index.ts`: entry; picks the real or demo backend, REST routes under `/api`, the `/ws` and `/ws/term` websockets, serves `dist/`, shutdown. +- `config.ts`: `SWARM_PORT` (default 4417), `SWARM_HOME` (default `codedungeon-home` beside the repo), `--demo`, state file, intervals, + the default projects folder. +- `swarm.ts`: the orchestrator. Floors, agents, scheduling/auto-assign, dev → QA → fix → merge loop, dev and QA + prompts, CEO job queue, phone messages, persistence (`state.json` / `demo-state.json`), websocket fan-out. +- `agentRunner.ts`: one Agent SDK session; options, env stripping, Playwright MCP, and turning the SDK stream into + terminal lines. +- `cliRunner.ts`: the terminal runtime (the default): one agent as the real CLI in a node-pty, same session contract + as `agentRunner.ts`. Claude Code reports through HTTP hooks (`POST /api/hooks/:token`; PreToolUse approves every + call); Codex reports turn endings (notify) and, once the manager trusts them, its steps (`-c hooks.*`); OpenCode + only turn endings. Codex/OpenCode screenshots are collected from the session's Playwright output folder. Esc in a + terminal ends the session as `interrupted`. The CEO's office tools are served over MCP (`/api/mcp/:token`). +- `ptyHost.ts`: the terminal keeper, a detached process of its own (`launch` re-spawns it outside the office's process + tree) holding the CLIs' pseudo-terminals and relaying their hooks, so agents keep working through office restarts. + `ptyClient.ts` is the office's side (start/connect, spawn, adopt after a restart, local fallback); `ptyProtocol.ts` + their JSON-lines messages. The launcher's `office:shutdown` says `restart: false` when quitting: CLIs stop then. + A developer's CLI stays at its prompt after the task (`keepAlive`): follow-ups and prompts typed there reuse it. +- `boxes.ts`, `boxRunner.ts`: coders in Upstash Boxes (`@upstash/box`). `boxes.ts` is the box layer: the API key and + GitHub token (env or the Windows user environment), the base snapshot (`BASE_SETUP`), desk and sign-in scripts, and + the events program every hook and status line runs in a box. `boxRunner.ts`'s `BoxPty` implements `Pty` for a CLI + in tmux in the box: `tmux attach` over a PTY session (reconnects with backoff), events followed with `tail -F`. + `shared/cloudBoxes.ts` holds the settings and who may move into a box. Testers stay local. +- `clis.ts`: the CLIs (Claude Code from the SDK's bundled binary, Codex, OpenCode): detection, Windows `.cmd` shim + unwrapping, each one's command line, and the helper scripts they call back with. +- `terminal.ts`: `AgentTerminal`, a headless xterm mirror per agent (replay for late viewers, saved to disk), its + `/ws/term` viewers, and keystrokes/resizes to the running CLI. +- `ceo.ts`: the CEO's office MCP tools (`createOfficeTools`, zod-validated), `ceoSystemPrompt`, `ceoJobPrompt`. +- `backend.ts`: the `Backend` interface (everything touching GitHub, git, disk and sessions) and `realBackend`. +- `demo.ts`: `createDemoBackend()`: fake GitHub, fake sessions (drawn into the agent's terminal in the terminal runtime), fake previews for `--demo`. +- `github.ts`: all GitHub access through the `gh` CLI. +- `workspace.ts`: floor checkouts, per-agent worktrees (`/workspaces/__/desks/`), + fast-forwarding main, per-repo git lock, stopping processes an agent left running. +- `exec.ts`: `run` / `git` / `gh`: `execFile` without a shell, prompts disabled, `CommandError` with stderr. +- `previews.ts`: one preview per floor: ports (6300 + floor), statuses, config validation. +- `previewRunner.ts`: checks out, installs and runs a floor's app in its preview worktree; kills the process tree. +- `httpError.ts`: `HttpError(status, message)`. +- `officeUpdate.ts`: the office's self-update: the drain decision, the launcher contract (IPC, `last-update.json`). +- `pacing.ts`: pacing new work after Claude's usage warnings: the start/skip decision and the usage state.