# CLAUDE.md

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

## Project Overview
Windows-first Electron desktop shell for a bundled OpenClaw runtime.

## Key Development Commands
- `corepack pnpm install`: Install workspace dependencies
- `corepack pnpm dev`: Start UI and Electron shell for local development
- `corepack pnpm build`: Build all workspace packages in dependency order
- `corepack pnpm typecheck`: Run TypeScript type-checking across the workspace
- `corepack pnpm lint`: Run linting (currently maps to type-checking)
- `corepack pnpm package`: Materialize runtime payload, build packages, and create Windows installer
- `corepack pnpm clean`: Run clean scripts for all packages
- `corepack pnpm smoke:installer`: Run packaged installer smoke test

## Project Structure
Monorepo using pnpm workspaces:
- `apps/desktop/`: Electron main process, preload bridge, packaging config
- `apps/ui/`: React + Vite renderer UI
- `packages/shared-types/`: Shared IPC contracts and DTOs
- `packages/gateway-client/`: Gateway/WebSocket client library
- `packages/runtime-manager/`: Local runtime lifecycle management
- `build/scripts/`: PowerShell packaging and smoke-test scripts
- `vendor/openclaw-runtime/`: Placeholder for bundled runtime payload

## High-Level Architecture
### Process Structure
- **Main Process** (`apps/desktop/src/main/`): Electron main process handling system operations, runtime management, and window creation
- **Preload Script** (`apps/desktop/src/preload/`): Secure bridge between renderer and main process
- **Renderer Process** (`apps/ui/src/`): React UI running in Electron's sandboxed renderer

### Communication Flow
UI → Preload (API bridge) → Main Process → Local Runtime (OpenClaw via runtime-manager)

### Runtime Architecture
The application bundles and manages a complete OpenClaw runtime environment:
- Node.js runtime
- Python runtime with dependencies
- Playwright Chromium browser
- OpenClaw package entry point
- Configuration files

## Package Management
- Uses `corepack pnpm` (version 10.0.0) to ensure consistent package management
- `pnpm-workspace.yaml` defines workspace boundaries
- `tsconfig.base.json` provides base TypeScript configuration with path aliases for packages
- Electron packaging configured via `electron-builder.yml`

## Important Architecture Notes
1. **Security Boundary**: Renderer process must communicate through the preload bridge - no direct access to secrets, filesystem, or child processes from UI
2. **Type Safety**: All packages use strict TypeScript, with shared contracts in `packages/shared-types`
3. **Build Order**: Packages are built in dependency order: shared-types → gateway-client → runtime-manager → ui → desktop
4. **Runtime Materialization**: `vendor/openclaw-runtime/` is generated during packaging by `build/scripts/materialize-runtime-payload.ps1`
5. **Installer**: Windows NSIS installer created by `electron-builder` with custom branding hooks

## Key Files to Know
- `apps/desktop/src/main/index.ts`: Electron entry point
- `apps/desktop/src/preload/index.ts`: Preload bridge API
- `apps/desktop/electron-builder.yml`: Packaging configuration
- `build/scripts/materialize-runtime-payload.ps1`: Runtime materialization script
- `apps/ui/src/App.tsx`: Main React component
- `packages/shared-types/src/index.ts`: Shared type definitions

## Testing Approach
- Type-checking: `corepack pnpm typecheck` (strict TypeScript)
- Smoke Tests: PowerShell scripts in `build/scripts/` testing installation, startup, routing, and runtime bootstrap
- CI/CD: GitLab CI with `typecheck_windows` and manual `package_windows_installer` jobs

## Coding Style
- Strict TypeScript
- ESM modules throughout
- 2-space indentation
- Double quotes, no trailing semicolons
- PascalCase for React components/classes
- camelCase for functions/variables

## UI Layout Guardrails
- Keep renderer layout on a single, stable skeleton system
- Do not mix layout systems; use stable semantic class names
- Preserve two-column desktop structure: left sidebar, right workspace
- Scope conversation-only styling under `.conversation-shell ...`
- Before removing/hiding UI controls, check smoke helpers and test utilities

When editing `apps/ui/src/App.tsx` and `apps/ui/src/styles.css`, keep the renderer layout on a single, stable skeleton system.

- Do not mix two layout systems in the main renderer shell. The main workspace skeleton must be driven by stable semantic class names, not large Tailwind utility overrides in `App.tsx`.
- Keep the conversation workspace wired through the same structural classes every time: `conversation-shell`, `conversation-main-layout`, `conversation-content-area`, and `conversation-panel`.
- Do not redefine core layout classes multiple times in `styles.css`. In particular, keep only one final definition for `shell`, `sidebar`, `main-shell`, `page-topbar`, `content-area`, `conversation-panel`, `message-list`, and `composer-shell`.
- Scope conversation-only styling under `.conversation-shell ...` so chat-specific rules do not leak into plugins or settings pages.
- Preserve the two-column desktop structure: left sidebar, right workspace. Changes must not collapse the right workspace into a sidebar-like single-column page.
- Before removing or hiding UI controls, check whether smoke helpers, automation hooks, or renderer-side test utilities depend on those DOM nodes or selectors.
- Be careful with Chinese text encoding in UI files. Avoid introducing BOM or accidental encoding changes when patching `App.tsx`, `styles.css`, or other renderer text files.
- For UI skeleton changes, validate with `corepack pnpm typecheck` and `corepack pnpm build`, and manually confirm chat, experts, plugins, and settings still render with correct height and scrolling behavior.
## Commit & PR Guidelines
- Follow Conventional Commits with scopes (e.g., `fix(desktop): ...`, `feat(ui): ...`)
- Keep messages imperative and scoped to area changed
- PRs should include summary, validation commands run, screenshots for UI changes