openchamber/AGENTS.md

# OpenChamber - AI Agent & Contributor Reference

Technical reference for AI coding agents and human contributors working on this project.

## Core Purpose

Web and desktop interface for OpenCode AI coding agent. Provides cross-device continuity, remote accessibility, and a unified chat interface using the OpenCode API backend.

## Tech Stack

- **React 19.1.1**: Modern React with concurrent features
- **TypeScript 5.8.3**: Full type safety
- **Vite 7.1.2**: Build tool with HMR and proxy
- **Tailwind CSS v4.0.0**: Latest `@import` syntax
- **Zustand 5.0.8**: State management with persistence
- **@opencode-ai/sdk**: Official OpenCode SDK with typed endpoints and SSE
- **@remixicon/react**: Icon system
- **@radix-ui primitives**: Accessible component foundations

## Architecture Overview (Monorepo)

Workspaces:
- `packages/ui` - Shared UI components and stores
- `packages/web` - Web runtime, Express server, CLI
- `packages/desktop` - Tauri desktop app with native APIs
- `packages/vscode` - VS Code extension with webview UI

### Core Components (UI)
In `packages/ui/src/components/chat/`: ChatContainer, ChatEmptyState, ChatErrorBoundary, ChatInput, ChatMessage, FileAttachment, MarkdownRenderer, MessageList, ModelControls, PermissionCard, PermissionRequest, ServerFilePicker, StreamingTextDiff, AgentMentionAutocomplete, CommandAutocomplete, FileMentionAutocomplete.
In `packages/ui/src/components/chat/message/`: MessageBody, MessageHeader, ToolOutputDialog, DiffViewToggle, FadeInOnReveal; parts/ (AssistantTextPart, ReasoningPart, ToolPart, UserTextPart, etc.)
In `packages/ui/src/components/layout/`: MainLayout, Header, Sidebar, SidebarContextSummary, SettingsDialog, VSCodeLayout.
In `packages/ui/src/components/sections/`: AgentsPage, CommandsPage, GitIdentitiesPage, ProvidersPage, SettingsPage (with subsections for agents/, commands/, git-identities/, providers/, settings/).
In `packages/ui/src/components/session/`: DirectoryTree, DirectoryExplorerDialog, SessionDialogs, SessionSidebar.
In `packages/ui/src/components/ui/`: CommandPalette, HelpDialog, ConfigUpdateOverlay, ContextUsageDisplay, ErrorBoundary, MemoryDebugPanel, MobileOverlayPanel, FireworksAnimation, OpenChamberLogo, OpenCodeIcon, ProviderLogo, ScrollShadow, OverlayScrollbar, plus Radix-based primitives (button, dialog, input, select, etc.)
In `packages/ui/src/components/views/`: ChatView, GitView, DiffView, PierreDiffViewer, TerminalView.
In `packages/ui/src/components/terminal/`: TerminalViewport
In `packages/ui/src/components/onboarding/`: OnboardingScreen
In `packages/ui/src/components/providers/`: ThemeProvider

### State Management (UI)
In `packages/ui/src/stores/`: contextStore, fileStore, messageStore, permissionStore, sessionStore, useAgentsStore, useCommandsStore, useConfigStore, useDirectoryStore, useFileSearchStore, useGitIdentitiesStore, useGitStore, useSessionStore, useTerminalStore, useUIStore

### OpenCode SDK Integration (UI)
In `packages/ui/src/lib/opencode/`: client.ts wrapper around `@opencode-ai/sdk` with directory-aware API calls, SDK methods (session.*, message.*, agent.*, provider.*, config.*, project.*, path.*), AsyncGenerator SSE streaming (2 retry attempts, 500ms->8s backoff), automatic directory parameter injection.

In `packages/ui/src/hooks/`: useEventStream.ts for real-time SSE connection management.

### Web Runtime (server/CLI)
Express server and CLI in `packages/web`: API adapters in `packages/web/src/api`, server in `packages/web/server/index.js` (git/terminal/config), UI bundle imported from `@openchamber/ui`.

### Desktop Runtime (Tauri)
Native desktop app in `packages/desktop`: Tauri backend in `src-tauri/` (Rust), frontend API adapters in `src/api/` (settings, permissions, diagnostics, files, git, terminal, notifications, tools, updater), bridge layer in `src/lib/` for Tauri IPC communication.

### VS Code Extension Runtime
Extension in `packages/vscode`: Extension entry in `src/` (ChatViewProvider, bridge, theme), webview API adapters in `webview/api/` (bridge, editor, files, permissions, settings, tools), webview components in `webview/components/` (ChatPanel, SessionsListView, VSCodeLayout).

## Development Commands

### Code Validation
Always validate changes:

```bash
pnpm -r type-check   # TypeScript validation
pnpm -r lint         # ESLint checks
pnpm -r build        # Production build
```

### Building
```bash
pnpm run build                 # Build all packages
pnpm run desktop:build         # Build desktop app
pnpm vscode:build              # Build VS Code extension
```

## Communication & Output Discipline (MANDATORY)
- Default to brevity. Responses must be as short as possible (until you suggesting plan) while remaining correct.
- Do not narrate internal reasoning, step-by-step thinking, or deliberation.

## Key Patterns

### Section-Based Navigation
Modular section architecture with dedicated pages and sidebars. Sections: Agents, Commands, Git Identities, Providers, Sessions, Settings. Independent state management and routing.

### File Attachments
Drag-and-drop upload with 10MB limit (`FileAttachment.tsx`), Data URL encoding, type validation with fallbacks, integrated via `useFileStore.addAttachedFile()`.

### Theme System
In `packages/ui/src/lib/theme/`: TypeScript-based themes (Flexoki Light and Dark), CSS variable generation, component-specific theming, Tailwind CSS v4 integration.

### Typography System
In `packages/ui/src/lib/`: Semantic typography with 6 CSS variables, theme-independent scales. **CRITICAL**: Always use semantic typography classes, never hardcoded font sizes.

### Streaming Architecture
SDK-managed SSE with AsyncGenerator, temp->real session ID swap (optimistic UI), pendingAssistantParts buffering, empty-response detection via `window.__opencodeDebug`.

## Development Guidelines

### Lint & Type Safety

- Never land code that introduces new ESLint or TypeScript errors
- Run `pnpm run lint` and `pnpm run type-check` before finalizing changes
- Adding `eslint-disable` requires justification in a comment explaining why typing is impossible
- Do **not** use `any` or `unknown` casts as escape hatches; build narrow adapter interfaces instead
- Refactors or new features must keep existing lint/type baselines green

### Theme Integration

- Check theme definitions before adding colors or font sizes to new components
- Always use theme-defined typography classes, never hardcoded font sizes
- Reference existing theme colors instead of adding new ones
- Ensure new components support both light and dark themes
- Use theme-generated CSS variables for dynamic styling

### Code Standards

- **Functional components**: Exclusive use of function components with hooks
- **Custom hooks**: Extract logic for reusability
- **Type-first development**: Comprehensive TypeScript usage
- **Component composition**: Prefer composition over inheritance

## Feature Implementation Map

### Directory & File System
`packages/ui/src/components/session/`: DirectoryTree, DirectoryExplorerDialog
`packages/ui/src/stores/`: DirectoryStore
Backend: `packages/web/server/index.js` with `listLocalDirectory()`, `getFilesystemHome()`

### Session Switcher
`SessionSwitcherDialog.tsx`: Collapsible date groups, mobile parity with MobileOverlayPanel, Git worktree and shared session chips, streaming indicators.

### Settings & Configuration
`packages/ui/src/components/sections/`: AgentsPage, CommandsPage, GitIdentitiesPage, ProvidersPage, SessionsPage, SettingsPage
Related stores: useAgentsStore, useCommandsStore, useConfigStore, useGitIdentitiesStore

### Git Operations
`packages/ui/src/components/views/`: GitView, DiffView
`packages/ui/src/stores/`: useGitIdentitiesStore
Backend: `packages/ui/src/lib/gitApi.ts` + `packages/web/server/index.js` (simple-git wrapper)

### Terminal
`packages/ui/src/components/views/`: TerminalView
`packages/ui/src/components/terminal/`: TerminalViewport (Xterm.js with FitAddon)
`packages/ui/src/stores/`: useTerminalStore
Backend: `packages/web/server/index.js` (node-pty wrapper with SSE)

### Theme System
`packages/ui/src/lib/theme/`: themes (2 definitions), cssGenerator, syntaxThemeGenerator
`packages/ui/src/components/providers/`: ThemeProvider

### Mobile & UX
`packages/ui/src/components/ui/`: MobileOverlayPanel
`packages/ui/src/hooks/`: useEdgeSwipe, useChatScrollManager