The Problem

OpenClaw developers need a live visual overview of generated assets and runtime activity. The usual workflow is a folder tree and log output, which makes it hard to see which assets are in use, how they move between rooms, or what the current game state is.

What This Does

ClawLibrary renders a 2‑D pixel‑game UI that mirrors OpenClaw’s internal resources. Asset definitions are read from src/data/*.json (e.g., asset.manifest.json, scene-art.manifest.json). Runtime telemetry is consumed by scripts/openclaw-telemetry.mjs and fed into the UI through the src/runtime/scene/LibraryScene.ts scene class. The main UI logic lives in src/main.ts, which wires the Vite dev server (vite.config.ts) to the HTML entry point index.html. UI helpers such as uiText, uiResourceId, and escapeHtml are heavily reused across the codebase (e.g., escapeHtml is called from 22 places).

How It Is Wired

Execution starts when Vite serves index.html and loads the compiled bundle generated from src/main.ts. The entry functions in src/main.ts—applyLocaleToChrome, openRecentActivityEntry, openResourceKind, openResourceKindMenu, openResourceModal, and refreshTelemetry—each cascade through dozens of internal calls (e.g., applyLocaleToChrome reaches 30 functions).

refreshTelemetry is the primary telemetry path: it reads telemetry files (one of the six file‑IO functions) and updates the UI state by invoking updateLobsterVisual, syncWorkStatus, and drawWorkZones. These functions in turn call the widely used helpers escapeHtml, uiText, and layerToDepth.

The scene class src/runtime/scene/LibraryScene.ts (105 functions, 9 types) is instantiated by src/main.ts and implements the Vite‑driven lifecycle methods preload, create, and update. It pulls geometry data from src/core/geometry.ts and path‑finding logic from src/core/pathfinder.ts. The core type definitions in src/core/types.ts are the most imported module (9 inbound edges) and provide the data contracts for resources, points, and walk graphs.

Utility scripts such as scripts/openclaw-telemetry.mjs (2,529 lines) read live telemetry and write to the same JSON files consumed by the UI; they are not part of the Vite bundle but affect the UI indirectly by mutating those files.

No circular dependencies were detected, so the import graph is a DAG; the most “blast‑radius” modules are src/main.ts (instability 1) and src/runtime/scene/LibraryScene.ts (instability 0.89), meaning changes there ripple widely.

How To Use It

# Clone the original repository
git clone https://github.com/moses-y/ClawLibrary ClawLibrary
cd ClawLibrary

# Install Node dependencies
npm install

# Validate type safety and linting
npm run validate

# Start the development server (local only)
npm run dev
# For LAN access, set the host variable
CLAWLIBRARY_SERVER_HOST=0.0.0.0 npm run dev

Configuration lives in clawlibrary.config.json; environment overrides can be set via a copied .env file (cp .env.example .env). Required variables are OPENCLAW_HOME and OPENCLAW_WORKSPACE. The UI becomes reachable at http://127.0.0.1:5173/ (or LAN URL when host is 0.0.0.0).

Real‑World Use

A studio CI job runs npm run validate && npm run build to generate a static bundle. The built bundle is then served alongside an OpenClaw instance; as the game runs, scripts/openclaw-telemetry.mjs writes telemetry JSON files that the UI reads, letting artists instantly see which sprite sheets are active and which rooms are being traversed.

Code Health & Issues

  • High – No test suite – 22 source files, zero test files. Fix: add at least one test per public entry point and run them in CI.
  • High – No CI pipeline – No .github/workflows or other CI config. Fix: add a GitHub Actions workflow that builds and runs the test suite on push/PR.
  • Medium – Dependabot missing – Only one manifest (package.json). Fix: add .github/dependabot.yml.
  • Medium – Large binaries in repo – public/ClawLibrary_preview-6s.gif (8.9 MB) and two PNGs >5 MB. Fix: move to Git LFS or external storage.
  • Low – Convention files missing – No .editorconfig, .gitattributes, or formatter config. Fix: add standard convention files.

The Bottom Line

ClawLibrary delivers a functional, real‑time visual overlay for OpenClaw assets, built on a clear React/Vite stack. The codebase works but is concentrated in a few large files and lacks automated testing or CI, making safe modification riskier. It is suitable for teams that need immediate visual insight and are prepared to add testing/CI infrastructure.