openchamber/AGENTS.md

OpenChamber - AI Agent Reference (verified)

Core purpose

OpenChamber provides UI runtimes (web/desktop/VS Code) for interacting with an OpenCode server (local auto-start or remote URL). UI uses HTTP + SSE via @opencode-ai/sdk.

Runtime architecture (IMPORTANT)

• Desktop is a thin Tauri shell that starts the web server sidecar and loads the web UI from http://127.0.0.1:<port>.
• All backend logic lives in packages/web/server/* (and packages/vscode/* for the VS Code runtime). Desktop Rust is not a feature backend.
• Tauri is used only for stable native integrations: menu, dialog (open folder), notifications, updater, deep-links.

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 (packages/ui/src/stores/)
• UI primitives: Radix UI (package.json deps), HeroUI (package.json deps), Remixicon (package.json deps)
• Server: Express (packages/web/server/index.js)
• Desktop: Tauri v2 (packages/desktop/src-tauri/)
• VS Code: extension + webview (packages/vscode/)

Monorepo layout

Workspaces are packages/* (see package.json).

• Shared UI: packages/ui
• Web app + server + CLI: packages/web
• Desktop app (Tauri): packages/desktop
• VS Code extension: packages/vscode

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: packages/web/server/lib/quota/DOCUMENTATION.md

git

Git repository operations for the web server runtime.

• Module docs: packages/web/server/lib/git/DOCUMENTATION.md

github

GitHub authentication, OAuth device flow, Octokit client factory, and repository URL parsing.

• Module docs: packages/web/server/lib/github/DOCUMENTATION.md

opencode

OpenCode server integration utilities including config management, provider authentication, and UI authentication.

• Module docs: packages/web/server/lib/opencode/DOCUMENTATION.md

notifications

Notification message preparation utilities for system notifications, including text truncation and optional summarization.

• Module docs: packages/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: packages/web/server/lib/terminal/DOCUMENTATION.md

tts

Server-side text-to-speech services and summarization helpers for /api/tts/* endpoints.

• Module docs: packages/web/server/lib/tts/DOCUMENTATION.md

skills-catalog

Skills catalog management including discovery, installation, and configuration of agent skill packages.

• Module docs: packages/web/server/lib/skills-catalog/DOCUMENTATION.md

Build / dev commands (verified)

All scripts are in package.json.

• Validate: bun run type-check, bun run lint
• Build all: bun run build
• Desktop build: bun run desktop:build
• VS Code build: bun run vscode:build
• Release smoke build: bun run release:test (shell script: scripts/test-release-build.sh)

Runtime entry points

• Web bootstrap: packages/web/src/main.tsx
• Web server: packages/web/server/index.js
• Web CLI: packages/web/bin/cli.js (package bin: packages/web/package.json)
• Desktop: Tauri entry packages/desktop/src-tauri/src/main.rs (spawns web server sidecar + loads web UI)
• Tauri backend: packages/desktop/src-tauri/src/main.rs
• VS Code extension host: packages/vscode/src/extension.ts
• VS Code webview bootstrap: packages/vscode/webview/main.tsx

OpenCode integration

• UI client wrapper: packages/ui/src/lib/opencode/client.ts (imports @opencode-ai/sdk/v2)
• SSE hookup: packages/ui/src/hooks/useEventStream.ts
• Web server embeds/starts OpenCode server: packages/web/server/index.js (createOpencodeServer)
• Web runtime filesystem endpoints: search packages/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: packages/ui/src/components/views/SettingsView.tsx
• Settings shared primitives: packages/ui/src/components/sections/shared/
• Settings sections: packages/ui/src/components/sections/ (incl skills/)
• Chat UI: packages/ui/src/components/chat/ and packages/ui/src/components/chat/message/
• Theme + typography: packages/ui/src/lib/theme/, packages/ui/src/lib/typography.ts
• Terminal UI: packages/ui/src/components/terminal/ (uses ghostty-web)

External / system integrations (active)

• Git: packages/ui/src/lib/gitApi.ts, packages/web/server/index.js (simple-git)
• Terminal PTY: packages/web/server/index.js (bun-pty/node-pty)
• Skills catalog: packages/web/server/lib/skills-catalog/, UI: packages/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, bun run lint, bun run build before finalizing changes).

Development rules

• Keep diffs tight; avoid drive-by refactors.
• Backend changes: keep web/desktop/vscode runtimes consistent (if relevant).
• 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 packages/ui/src/lib/typography.ts; theme vars via packages/ui/src/lib/theme/.
• Shared UI patterns: for "series of items + divider + series of items" layouts, use shared UI primitives instead of duplicating ad-hoc markup in feature components.
• Toasts: use custom toast wrapper from @/components/ui (backed by packages/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.

CLI Parity and Safety Policy (MANDATORY)

Principle: policy-first, UX-second

All safety and correctness rules MUST be enforced in core command logic, independent of output mode.

Interactive/pretty UX (@clack/prompts) is a presentation layer only. It must never be the only place where validation or restriction is enforced.

Required parity across modes

The same functional outcome and safety gates MUST hold for all execution modes:

• Interactive TTY (full Clack UX)
• Non-interactive shells (piped/stdin-less automation)
• --quiet
• --json
• Fully pre-specified flags (no prompts)

In all modes, invalid operations MUST fail with non-zero exit code and deterministic error semantics.

Non-negotiable rule

Do not rely on prompts to enforce policy.

• Prompts MAY help users choose valid inputs.
• Core validators MUST run even when prompts are unavailable or skipped.
• --quiet suppresses non-essential output only; it does not weaken validation.
• --json changes output shape only; it does not weaken validation.

Detailed Clack UX patterns (primitives, prompt gating, and implementation checklist) are defined in the clack-cli-patterns skill and should not be duplicated here.

Clack CLI Skill (MANDATORY for terminal CLI work)

When working on terminal CLI commands, prompts, or output formatting, agents MUST study the Clack CLI skill first.

Before starting terminal CLI work:

skill({ name: "clack-cli-patterns" })

Scope: terminal CLI only (for example packages/web/bin/*). Do not apply this requirement to VS Code or web UI work.

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.4.6, v1.4.5)