XCOpenCodeWeb/AGENTS.md

# OpenChamber - AI Agent Reference (verified)

## Core purpose
OpenChamber is a web-based UI runtime for interacting with an OpenCode server (local auto-start or remote URL). UI uses HTTP + SSE via `@opencode-ai/sdk`.

## Tech stack (source of truth: `package.json`, resolved: `bun.lock`)
- Runtime/tooling: Bun (`package.json` `packageManager`), Node >=20 (`package.json` `engines`)
- UI: React, TypeScript, Vite, Tailwind v4
- State: Zustand (`ui/src/stores/`)
- UI primitives: Radix UI (`package.json` deps), HeroUI (`package.json` deps), Remixicon (`package.json` deps)
- Server: Express (`web/server/index.js`)

## Monorepo layout
No longer using workspaces (see `package.json`).
- Shared UI: `ui`
- Web app + server + CLI: `web`

## Documentation map
Before changing any mapped module, read its module documentation first.

### web
Web runtime and server implementation for OpenChamber.

#### lib
Server-side integration modules used by API routes and runtime services.

##### quota
Quota provider registry, dispatch, and provider integrations for usage endpoints.
- Module docs: `web/server/lib/quota/DOCUMENTATION.md`

##### git
Git repository operations for the web server runtime.
- Module docs: `web/server/lib/git/DOCUMENTATION.md`

##### github
GitHub authentication, OAuth device flow, Octokit client factory, and repository URL parsing.
- Module docs: `web/server/lib/github/DOCUMENTATION.md`

##### opencode
OpenCode server integration utilities including config management, provider authentication, and UI authentication.
- Module docs: `web/server/lib/opencode/DOCUMENTATION.md`

##### notifications
Notification message preparation utilities for system notifications, including text truncation and optional summarization.
- Module docs: `web/server/lib/notifications/DOCUMENTATION.md`

##### terminal
WebSocket protocol utilities for terminal input handling including message normalization, control frame parsing, and rate limiting.
- Module docs: `web/server/lib/terminal/DOCUMENTATION.md`

##### tts
Server-side text-to-speech services and summarization helpers for `/api/tts/*` endpoints.
- Module docs: `web/server/lib/tts/DOCUMENTATION.md`

##### skills-catalog
Skills catalog management including discovery, installation, and configuration of agent skill packages.
- Module docs: `web/server/lib/skills-catalog/DOCUMENTATION.md`

## Build / dev commands (verified)
All scripts are in `package.json`.
- Validate: `bun run type-check:web`, `bun run lint:web` (or use :ui variants)
- Build: `bun run build:web` and/or `bun run build:ui`

## Distribution

## Electron single-exe distribution
To package as a single portable exe with built-in server:
```bash
cd web/electron
npx electron-builder --win --x64
```
Output: `web/electron/release/OpenChamber.exe` (single portable exe, ~260MB)

The exe includes:
- Bundled Node.js runtime
- Server code, static files, and CLI
- System tray icon with context menu
- Auto-starts server on port 3000

## Runtime entry points
- Web bootstrap: `web/src/main.tsx`
- Web server: `web/server/index.js`
- Web CLI: `web/bin/cli.js` (package bin: `web/package.json`)

## OpenCode integration
- UI client wrapper: `ui/src/lib/opencode/client.ts` (imports `@opencode-ai/sdk/v2`)
- SSE hookup: `ui/src/hooks/useEventStream.ts`
- Web server embeds/starts OpenCode server: `web/server/index.js` (`createOpencodeServer`)
- Web runtime filesystem endpoints: search `web/server/index.js` for `/api/fs/`
- External server support: Set `OPENCODE_HOST` (full base URL, e.g. `http://hostname:4096`) or `OPENCODE_PORT`, plus `OPENCODE_SKIP_START=true`, to connect to existing OpenCode instance

## Key UI patterns (reference files)
- Settings shell: `ui/src/components/views/SettingsView.tsx`
- Settings shared primitives: `ui/src/components/sections/shared/`
- Settings sections: `ui/src/components/sections/` (incl `skills/`)
- Chat UI: `ui/src/components/chat/` and `ui/src/components/chat/message/`
- Theme + typography: `ui/src/lib/theme/`, `ui/src/lib/typography.ts`
- Terminal UI: `ui/src/components/terminal/` (uses `ghostty-web`)

## External / system integrations (active)
- Git: `ui/src/lib/gitApi.ts`, `web/server/index.js` (`simple-git`)
- Terminal PTY: `web/server/index.js` (`bun-pty`/`node-pty`)
- Skills catalog: `web/server/lib/skills-catalog/`, UI: `ui/src/components/sections/skills/`

## Agent constraints
- Do not modify `../opencode` (separate repo).
- Do not run git/GitHub commands unless explicitly asked.
- Keep baseline green (run `bun run type-check:web`, `bun run lint:web`, `bun run build:web` before finalizing changes).

## Development rules
- Keep diffs tight; avoid drive-by refactors.
- Follow local precedent; search nearby code first.
- TypeScript: avoid `any`/blind casts; keep ESLint/TS green.
- React: prefer function components + hooks; class only when needed (e.g. error boundaries).
- Control flow: avoid nested ternaries; prefer early returns + `if/else`/`switch`.
- Styling: Tailwind v4; typography via `ui/src/lib/typography.ts`; theme vars via `ui/src/lib/theme/`.
- Toasts: use custom toast wrapper from `@/components/ui` (backed by `ui/src/components/ui/toast.ts`); do not import `sonner` directly in feature code.
- No new deps unless asked.
- Never add secrets (`.env`, keys) or log sensitive data.

## Theme System (MANDATORY for UI work)

When working on any UI components, styling, or visual changes, agents **MUST** study the theme system skill first.

**Before starting any UI work:**
```
skill({ name: "theme-system" })
```

This skill contains all color tokens, semantic logic, decision tree, and usage patterns. All UI colors must use theme tokens - never hardcoded values or Tailwind color classes.

## Recent changes
- Releases + high-level changes: `CHANGELOG.md`
- Recent commits: `git log --oneline` (latest tags: `v1.8.x`)