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
• Package for distribution: bun run package (outputs to dist-output/)

Distribution

Run bun run package to generate dist-output/ folder for distribution. Users then run:

cd dist-output
npm install --omit=dev
npm run start

Electron single-exe distribution

To package as a single portable exe with built-in server:

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)