diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fb1a42d9..95b0b7fa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,25 +1,47 @@
# Contributing to OpenChamber
-## Development
+## Getting Started
```bash
git clone https://github.com/btriapitsyn/openchamber.git
cd openchamber
bun install
-
-# Web development
-bun run dev:web:full
-
-# Desktop app (Tauri)
-bun run desktop:dev
-
-# VS Code extension
-bun run vscode:build && code --extensionDevelopmentPath="$(pwd)/packages/vscode"
-
-# Production build
-bun run build
```
+## Dev Scripts
+
+### Web
+
+| Script | Description | Ports |
+|--------|-------------|-------|
+| `bun run dev:web:full` | Build watcher + Express server. No HMR — manual refresh after changes. | `3001` (server + static) |
+| `bun run dev:web:hmr` | Vite dev server + Express API. **Open the Vite URL for HMR**, not the backend. | `5180` (Vite HMR), `3902` (API) |
+
+Both are configurable via env vars: `OPENCHAMBER_PORT`, `OPENCHAMBER_HMR_UI_PORT`, `OPENCHAMBER_HMR_API_PORT`.
+
+### Desktop (Tauri)
+
+```bash
+bun run desktop:dev
+```
+
+Launches Tauri in dev mode with WebView devtools enabled and a distinct dev icon.
+
+### VS Code Extension
+
+```bash
+bun run vscode:dev # Watch mode (extension + webview rebuild on save)
+```
+
+To test in VS Code:
+```bash
+bun run vscode:build && code --extensionDevelopmentPath="$(pwd)/packages/vscode"
+```
+
+### Shared UI (`packages/ui`)
+
+No dev server — this is a source-level library consumed by other packages. During development, `bun run dev` runs type-checking in watch mode.
+
## Before Submitting
```bash
@@ -31,21 +53,40 @@ bun run build # Must succeed
## Code Style
- Functional React components only
-- TypeScript strict mode - no `any` without justification
-- Use existing theme colors/typography - don't add new ones
+- TypeScript strict mode — no `any` without justification
+- Use existing theme colors/typography from `packages/ui/src/lib/theme/` — don't add new ones
- Components must support light and dark themes
+- Prefer early returns and `if/else`/`switch` over nested ternaries
+- Tailwind v4 for styling; typography via `packages/ui/src/lib/typography.ts`
## Pull Requests
1. Fork and create a branch
2. Make changes
-3. Run validation commands above
+3. Run the validation commands above
4. Submit PR with clear description of what and why
## Project Structure
+```
+packages/
+ ui/ Shared React components, hooks, stores, and theme system
+ web/ Web server (Express) + frontend (Vite) + CLI
+ desktop/ Tauri macOS app (thin shell around the web UI)
+ vscode/ VS Code extension (extension host + webview)
+```
+
See [AGENTS.md](./AGENTS.md) for detailed architecture reference.
+## Not a developer?
+
+You can still help:
+
+- Report bugs or UX issues — even "this felt confusing" is valuable feedback
+- Test on different devices, browsers, or OS versions
+- Suggest features or improvements via issues
+- Help others in Discord
+
## Questions?
-Open an issue.
+Open an [issue](https://github.com/btriapitsyn/openchamber/issues) or ask in [Discord](https://discord.gg/ZYRSdnwwKA).
diff --git a/FEATURES_PLAN.md b/FEATURES_PLAN.md
deleted file mode 100644
index b22c6ced..00000000
--- a/FEATURES_PLAN.md
+++ /dev/null
@@ -1,53 +0,0 @@
-**Plan**
-
-**1) Dynamic Window Title (web + desktop)**
-- Add `packages/ui/src/hooks/useWindowTitle.ts` and call it from `packages/ui/src/App.tsx`.
-- Title parts: `[projectName] | [instanceName if non-local] | OpenChamber`.
-- `projectName`: from `useProjectsStore` active project; prefer `label`, else basename of `path`.
-- `instanceName` (desktop only): reuse `desktopHostsGet + locationMatchesHost` logic (same as `Header.tsx`), omit when local.
-- Apply:
- - always set `document.title`
- - if Tauri: `@tauri-apps/api/window` → `getCurrentWindow().setTitle(title)` (best-effort)
-
-**2) Custom Project Icons (PNG/JPEG/SVG) stored on server + persisted in `settings.json`**
-- Extend project schema:
- - `packages/ui/src/lib/api/types.ts` `ProjectEntry` add `iconImage?: { mime: string; updatedAt: number; source: 'custom' | 'auto' } | null`
- - Update UI+server sanitizers to preserve it:
- - `packages/ui/src/stores/useProjectsStore.ts` `sanitizeProjects`
- - `packages/ui/src/lib/persistence.ts` `sanitizeProjects`
- - `packages/web/server/index.js` `sanitizeProjects`
-- Server storage + API (Express):
- - Add JSON parsing for `req.path.startsWith('/api/projects')` in the existing body-parser gate (`packages/web/server/index.js` around the `express.json` middleware switch).
- - Store icon files under `~/.config/openchamber/project-icons/` (i.e. `OPENCHAMBER_DATA_DIR/project-icons`), filename based on `sha1(projectId)` + extension (prevents path traversal / odd IDs).
- - New routes in `packages/web/server/index.js`:
- - `GET /api/projects/:projectId/icon` → serve file (Content-Type from stored mime, `Cache-Control: immutable` with `?v=updatedAt`)
- - `PUT /api/projects/:projectId/icon` body `{ dataUrl: string }` → validate mime, decode, write file, update `projects[].iconImage` in `settings.json` via `persistSettings`
- - `DELETE /api/projects/:projectId/icon` → delete file(s), clear `iconImage`, persist
- - `POST /api/projects/:projectId/icon/discover` → best-effort “try this first”: search project dir for `favicon.(ico|png|svg|jpg|jpeg|webp)` using existing `searchFilesystemFiles()`, pick shortest match, store it as `source:'auto'` (skip if `source:'custom'` unless `force=true`)
-- UI wiring:
- - Add async actions in `packages/ui/src/stores/useProjectsStore.ts`: `uploadProjectIcon(id, file)`, `removeProjectIcon(id)`, `discoverProjectIcon(id)`
- - Update renderers to prefer `iconImage` over `PROJECT_ICON_MAP`:
- - `packages/ui/src/components/layout/NavRail.tsx`
- - `packages/ui/src/components/sections/projects/ProjectsSidebar.tsx`
- - `packages/ui/src/components/chat/MobileSessionStatusBar.tsx`
- - Add upload/remove/(discover) UI controls:
- - `packages/ui/src/components/sections/projects/ProjectsPage.tsx`
- - `packages/ui/src/components/layout/ProjectEditDialog.tsx`
- - `` (small size, fits existing tile layout)
-
-**3) File Tree File-Type Icons (full icon pack)**
-- Vendor the full directory from `/tmp/opencode/packages/ui/src/assets/icons/file-types` into `packages/ui/src/assets/icons/file-types/`.
-- Add `packages/ui/src/lib/fileTypeIcons.ts`:
- - build an icon URL map with `import.meta.glob('../assets/icons/file-types/*.svg', { eager: true, as: 'url' })`
- - map filename/extension → icon key (use `getLanguageFromExtension()` + a small alias map, plus `_light` variant selection based on `useThemeSystem().currentTheme.metadata.variant`)
- - fallback to `document.svg`
-- Add `packages/ui/src/components/icons/FileTypeIcon.tsx` (renders the resolved icon URL).
-- Replace current generic file icons with `FileTypeIcon` (keep folder icons as-is):
- - `packages/ui/src/components/layout/SidebarFilesTree.tsx`
- - `packages/ui/src/components/views/FilesView.tsx`
- - `packages/ui/src/components/chat/ServerFilePicker.tsx`
-
-**Verification (end of build mode)**
-- `bun run type-check`
-- `bun run lint`
-- `bun run build`
diff --git a/README.md b/README.md
index 3dbdea13..30231b25 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,14 @@
# OpenChamber
[](https://github.com/btriapitsyn/openchamber/stargazers)
-[](https://github.com/btriapitsyn/openchamber/network/members)
[](https://github.com/btriapitsyn/openchamber/releases/latest)
[](https://opencode.ai)
-[](https://zread.ai/btriapitsyn/openchamber)
[](https://discord.gg/ZYRSdnwwKA)
[](https://ko-fi.com/G2G41SAWNS)
-Web and desktop interface for the [OpenCode](https://opencode.ai) AI coding agent. Works alongside the OpenCode TUI.
+**OpenCode, everywhere.** Desktop. Browser. Phone.
-The OpenCode team is actively working on their own desktop app. I still decided to release this project as a fan-made alternative.
-
-It was entirely built with OpenCode tool - first with the TUI version, then with the first usable version of OpenChamber, which I then used to build the rest.
-
-The whole project was built entirely with AI coding agents under my supervision. It started as a hobby project and proof of concept that AI agents can create genuinely usable software.
+A GUI for [OpenCode](https://opencode.ai) that works alongside the TUI — start a session in your terminal, pick it up on your phone, finish it on your laptop. Same conversation, any screen.
@@ -29,125 +23,81 @@ The whole project was built entirely with AI coding agents under my supervision.
-
+
-## Why use OpenChamber?
+## Why a GUI?
-- **Cross-device continuity**: Start in TUI, continue on tablet/phone, return to terminal - same session
-- **Remote access**: Use OpenCode from anywhere via browser
-- **Familiarity**: A visual alternative for developers who prefer GUI workflows
+OpenCode's TUI is excellent. OpenChamber is for those moments when you want a visual workspace — reviewing diffs side-by-side, keeping an eye on multiple agents at once, or just continuing a session from your phone while away from the keyboard.
-## Features
+They share the same sessions. Use whatever feels right.
-### Core (all app versions)
+## Highlights
-- Branchable chat timeline with `/undo`, `/redo`, and one-click forks from earlier turns
-- Smart tool UIs for diffs, file operations, permissions, and long-running task progress
-- Voice mode with speech input and read-aloud responses for hands-free workflows
-- Multi-agent runs from one prompt with isolated worktrees for safe side-by-side comparisons
-- Git workflows in-app: identities, commits, PR creation, checks, and merge actions
-- GitHub-native workflows: start sessions from issues and pull requests with context already attached
-- Plan/Build mode with a dedicated plan view for drafting and iterating implementation steps
-- Inline comment drafts on diffs, files, and plans that can be sent back to the agent
-- Context visibility tools (token/cost breakdowns, raw message inspection, and activity summaries)
-- Integrated terminal with per-directory sessions and stable performance on heavy output
-- Built-in skills catalog and local skill management for reusable automation workflows
+- **Use it from anywhere** — Cloudflare tunnel with QR code onboarding. Scan, connect, code from your couch.
+- **Branchable chat timeline** — Undo, redo, fork from any turn. Explore different approaches without losing your place.
+- **GitHub-native workflows** — Start sessions from issues and PRs with context already attached. Review checks, merge — all in-app.
+- **Project Actions** — Run dev servers, configure SSH port forwarding, open remote URLs locally. Your project commands, one click away.
+- **Connect to remote machines** — Desktop app connects to remote OpenChamber instances over SSH, with dedicated lifecycle and UX flows.
-### Web / PWA
+## Quick Start
-- Cloudflare tunnel access with two modes: Quick Tunnel (CLI) and Named Tunnel (in-app settings)
-- One-scan onboarding with tunnel QR + password URL helpers
-- Mobile-first experience: optimized chat controls, keyboard-safe layouts, and attachment-friendly UI
-- Background notifications plus reliable cross-tab session activity tracking
-- Built-in self-update + restart flow that keeps your server settings intact
+> **Prerequisite:** [OpenCode CLI](https://opencode.ai) installed.
-### Desktop (macOS)
+**Desktop (macOS)** — Download from [Releases](https://github.com/btriapitsyn/openchamber/releases).
-- Native macOS menu integration with polished app actions and deep-link handling
-- Multi-window support for parallel project/session workflows
-- "Open In" shortcuts for Finder, Terminal, and your preferred editor
-- Fast switching between local and remote instances
-- Workspace-first startup flow with directory picker and steadier window restore behavior
+**VS Code** — Install from [Marketplace](https://marketplace.visualstudio.com/items?itemName=fedaykindev.openchamber) or search "OpenChamber" in Extensions.
-### VS Code Extension
-
-- Editor-native workflow: open files directly from tool output and keep sessions beside your code
-- Agent Manager for parallel multi-model runs from a single prompt
-- Right-click actions to add context, explain selections, and improve code in-place
-- In-extension settings, responsive layout, and theme mapping that matches your editor
-- Hardened runtime lifecycle and health checks for faster startup and fewer stuck reconnect states
-
-### Custom Themes
-
-Create your own color schemes by dropping JSON files into `~/.config/openchamber/themes/`. Hot reload supported — no restart needed.
-
-[**Read the Guide: Custom Themes**](docs/CUSTOM_THEMES.md)
-
-## Installation
-
-### VS Code Extension
-
-Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=fedaykindev.openchamber) / [Open VSX Registry](https://open-vsx.org/extension/FedaykinDev/openchamber) or search "OpenChamber" in Extensions.
-
-### CLI (Web Server)
+**CLI (Web + PWA)** — requires Node.js 20+
```bash
-# Quick install (auto-detects your package manager)
curl -fsSL https://raw.githubusercontent.com/btriapitsyn/openchamber/main/scripts/install.sh | bash
-
-# Or install manually
-bun add -g @openchamber/web # or npm, pnpm, yarn
+openchamber --ui-password be-creative-here --daemon
```
+
+Advanced CLI options
+
```bash
-openchamber # Start on port 3000
openchamber --port 8080 # Custom port
openchamber --daemon # Background mode
openchamber --ui-password secret # Password-protect UI
-openchamber --try-cf-tunnel # Create a Cloudflare Quick Tunnel for remote access
-openchamber --try-cf-tunnel --tunnel-qr # Show QR code for easy mobile access
-openchamber --try-cf-tunnel --tunnel-password-url # Include password in URL for auto-login
-OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber # Connect to external OpenCode server
-OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber # Connect via custom host/HTTPS
+openchamber --try-cf-tunnel # Cloudflare Quick Tunnel
+openchamber --try-cf-tunnel --tunnel-qr # + QR code
+openchamber --try-cf-tunnel --tunnel-password-url # + password in URL
openchamber stop # Stop server
-openchamber update # Update to latest version
+openchamber update # Update to latest
```
-Named Tunnel mode is configured in-app (Settings -> OpenChamber -> Tunnel). The CLI currently supports Quick Tunnel flags only. `--tunnel ` is not supported yet.
+Connect to an existing OpenCode server:
+```bash
+OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber
+OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber
+```
-### Desktop App (macOS)
+
-Download from [Releases](https://github.com/btriapitsyn/openchamber/releases).
-
-### Docker Compose
+
+Docker
```bash
docker compose up -d
```
-The service will be available at `http://localhost:3000`.
-
-**UI Password (optional):** To enable password-protected access, uncomment and set the `UI_PASSWORD` environment variable in `docker-compose.yml`:
+Available at `http://localhost:3000`.
+**UI Password:**
```yaml
environment:
UI_PASSWORD: your_secure_password
```
-Or pass it via command line:
-
-```bash
-UI_PASSWORD=secret docker compose up -d
-```
-
-**Cloudflare Tunnel (optional):** To enable Cloudflare Quick Tunnel for remote access, set the `CF_TUNNEL` environment variable:
-
+**Cloudflare Tunnel:**
```yaml
environment:
- CF_TUNNEL: "true" # Options: true, qr, password, full
+ CF_TUNNEL: "true" # Options: true, qr, password
```
| Value | Description |
@@ -156,70 +106,159 @@ environment:
| `qr` | Enable tunnel + QR code |
| `password` | Enable tunnel + password in URL |
-### Named Cloudflare Tunnel (persistent hostname)
-
-OpenChamber also supports Named Tunnel mode for more reliable long-lived access with your Cloudflare account and custom hostname.
-
-- Configure it in-app at **Settings -> OpenChamber -> Tunnel** and switch mode to **Named**.
-- Named tunnels require a domain in your Cloudflare account.
-- Cloudflare setup guide: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/
-- CLI note: `--tunnel ` is not supported yet.
-
-**Data Directory Permission Note:** The `data/` directory is mounted into the container for persistent storage (config, sessions, SSH keys, workspaces). Before running, ensure the directory exists and has proper permissions:
+**Data directory permissions:** The `data/` directory is mounted for persistent storage. Before running:
```bash
-# Create data directories with correct ownership
mkdir -p data/openchamber data/opencode/share data/opencode/config data/ssh
-
-# Fix permissions (replace $USER with your username)
chown -R 1000:1000 data/
```
-Without proper permissions, the container may fail to start or encounter permission denied errors when writing to these directories.
+**SSH/Git:** If git push/pull fails, run `ssh -T git@github.com` in terminal.
-**SSH/Git Authentication Note:** If git pull/push fails. Run `ssh -T git@github.com` in terminal.
+
-## Prerequisites
+
+Named Cloudflare Tunnel (persistent hostname)
-- [OpenCode CLI](https://opencode.ai) installed
-- Node.js 20+ (for web version)
-- [cloudflared](https://github.com/cloudflare/cloudflared/releases) (required for `--try-cf-tunnel`)
+For reliable long-lived access with a custom hostname from your Cloudflare account:
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+- Configure in-app at **Settings > OpenChamber > Tunnel**, switch to **Named** mode.
+- Requires a domain in your Cloudflare account.
+- [Cloudflare setup guide](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/)
+- CLI `--tunnel ` support is coming very soon.
-## Tech Stack
+
-### Frontend
+## Features
-
-
-
-
+
+Chat & Interaction
-### State & UI
+- Branchable chat timeline with `/undo`, `/redo`, and one-click forks from any turn
+- Multi-agent runs from one prompt with isolated worktrees for safe side-by-side comparisons
+- Voice mode with speech input and read-aloud responses for hands-free workflows
+- Plan/Build mode with a dedicated plan view for drafting and iterating steps
+- Inline comment drafts on diffs, files, and plans — send feedback back to the agent
+- Shell mode via leading `!` with inline output
+- Share messages as images
+- Mermaid diagrams render inline with copy/download actions
+- Smart tool UIs for diffs, file operations, permissions, and task progress
-
-
+
-### Backend & Desktop
+
+Git & GitHub
-
-
-
+- Full Git sidebar with staging, commits, push/pull, branch management, and rebase/merge flows
+- PR creation with AI-generated descriptions, status checks, and merge actions
+- Start sessions from GitHub issues and pull requests with context baked in
+- Multi-remote push and fork-aware PR creation
+- Worktree integration: isolated sessions per branch, merge back with conflict handling
+- Git identities, gitmoji support, and multi-account GitHub auth
+
+
+
+
+Files, Diff & Terminal
+
+- Workspace file browser with inline editing, syntax highlighting, and markdown preview
+- Beautiful diff viewer with stacked/inline modes, lazy loading for large changesets
+- Integrated terminal with per-directory sessions, tabbed interface, and stable heavy-output performance
+- Clickable file paths in messages — jump to exact line locations
+- File-type icons across all views for faster visual scanning
+
+
+
+
+Web / PWA
+
+- Cloudflare tunnel with Quick and Named modes, secure one-time connect links, and QR onboarding
+- Mobile-first: optimized chat controls, keyboard-safe layouts, drag-to-reorder projects
+- Background notifications and cross-tab session tracking
+- Self-update + restart flow that keeps your server settings intact
+- Installable as PWA with project-aware naming
+
+
+
+
+Desktop (macOS)
+
+- Connect to remote OpenChamber instances over SSH with dedicated lifecycle flows
+- Project Actions: run dev servers, SSH port forwarding, open remote URLs locally
+- Multi-window support for parallel project workflows
+- "Open In" shortcuts for Finder, Terminal, and your preferred editor
+- Fast switching between local and remote instances
+- Native macOS menu, deep-link handling, and polished startup
+
+
+
+
+VS Code Extension
+
+- Editor-native: open files from tool output, keep sessions beside your code
+- Agent Manager for parallel multi-model runs from a single prompt
+- Right-click actions: add context, explain selections, improve code in-place
+- Session editor panel, responsive layout, and theme mapping to your editor
+- Edit-style tool results open directly in focused diff views
+
+
+
+
+Customization
+
+- 18+ built-in themes with light/dark variants
+- Custom themes via JSON files in `~/.config/openchamber/themes/` — hot reload, no restart
+- Configurable keyboard shortcuts for chat, panels, and services
+- Font size, spacing, corner radius, and layout controls
+- Customizable project icons with upload and automatic favicon discovery
+- Skills catalog and local skill management for reusable automation
+
+[Read the Guide: Custom Themes](docs/CUSTOM_THEMES.md)
+
+
+
+
+Context & Productivity
+
+- Token usage, cost breakdowns, and raw message inspection panel
+- Usage quota tracking across multiple providers with pace/prediction indicators
+- Favorite model cycling via keyboard shortcuts
+- Session folders and subfolders with drag-to-reorder
+- Persistent project notes and todos per project
+- Draft persistence per session with expanded focus mode for longer prompts
+
+
+
+## Roadmap
+
+Active development. Here's what's being worked on or planned:
+
+- Windows and Linux desktop apps
+- Mobile app with remote instance and laptop connectivity
+- More built-in tunneling options
+- Kanban board for multi-agent management — keeping the human in the loop and in control
+- Custom OpenCode plugins/tools built-in catalog
+- Linear integration
+- Built-in browser for running dev apps with agent integration
## Acknowledgments
-Independent project, not affiliated with OpenCode team.
+Independent project, not affiliated with the OpenCode team.
**Special thanks to:**
-- [OpenCode](https://opencode.ai) - For the excellent API and extensible architecture.
-- [Flexoki](https://github.com/kepano/flexoki) - Beautiful color scheme by [Steph Ango](https://stephango.com/flexoki).
-- [Pierre](https://pierrejs-docs.vercel.app/) - Fast, beautiful diff viewer with syntax highlighting.
-- [Tauri](https://github.com/tauri-apps/tauri) - Desktop application framework.
-- [Ghossty-web](https://github.com/coder/ghostty-web) - for a great implementeation of a Ghostty web renderer.
-- [David Hill](https://x.com/iamdavidhill) - who inspired me to release this without [overthinking](https://x.com/iamdavidhill/status/1993648326450020746?s=20).
-- My wife, who created a beautiful firework animation for the app while testing it for the first time.
+- [OpenCode](https://opencode.ai) — For the excellent API and extensible architecture.
+- [Flexoki](https://github.com/kepano/flexoki) — Beautiful color scheme by [Steph Ango](https://stephango.com/flexoki).
+- [Pierre](https://pierrejs-docs.vercel.app/) — Fast, beautiful diff viewer with syntax highlighting.
+- [Tauri](https://github.com/tauri-apps/tauri) — Desktop application framework.
+- [Ghostty-web](https://github.com/coder/ghostty-web) — Great implementation of a Ghostty web renderer.
+- [David Hill](https://x.com/iamdavidhill) — Who inspired me to release this without [overthinking](https://x.com/iamdavidhill/status/1993648326450020746).
+- [My wife](https://github.com/yulia-ivashko), who — with zero AI background — sat down with the app for the first time and built the firework celebration that plays on every successful push.
+- Every contributor who shaped this project with their PRs, ideas, and attention to detail.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
## License
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000..3c129b6b
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,32 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in OpenChamber, please report it responsibly.
+
+**Email:** [artmore@protonmail.com](mailto:artmore@protonmail.com)
+
+Please include:
+- Description of the vulnerability
+- Steps to reproduce
+- Affected version(s)
+- Potential impact
+
+I'll acknowledge receipt within 48 hours and aim to provide a fix or mitigation as quickly as possible.
+
+**Please do not open public GitHub issues for security vulnerabilities.**
+
+## Scope
+
+OpenChamber handles sensitive context including:
+- UI authentication (password-protected sessions, JWT tokens)
+- Cloudflare tunnel access (remote connectivity)
+- Terminal access (PTY sessions)
+- Git credentials and SSH keys
+- File system operations
+
+Security reports related to any of these areas are especially appreciated.
+
+## Supported Versions
+
+Security fixes are applied to the latest release. There is no LTS or backport policy at this time.
diff --git a/docs/references/chat_example.png b/docs/references/chat_example.png
index 19b45ad1..20b22a10 100644
Binary files a/docs/references/chat_example.png and b/docs/references/chat_example.png differ
diff --git a/docs/references/diff_example.png b/docs/references/diff_example.png
index d6563e37..e3d0eac4 100644
Binary files a/docs/references/diff_example.png and b/docs/references/diff_example.png differ
diff --git a/docs/references/pwa_chat_example.png b/docs/references/pwa_chat_example.png
index c56e0b23..f85868ee 100644
Binary files a/docs/references/pwa_chat_example.png and b/docs/references/pwa_chat_example.png differ
diff --git a/docs/references/pwa_diff_example.png b/docs/references/pwa_diff_example.png
new file mode 100644
index 00000000..f7a8f374
Binary files /dev/null and b/docs/references/pwa_diff_example.png differ
diff --git a/docs/references/pwa_terminal_example.png b/docs/references/pwa_terminal_example.png
deleted file mode 100644
index 38b18d5e..00000000
Binary files a/docs/references/pwa_terminal_example.png and /dev/null differ
diff --git a/docs/references/settings_example.png b/docs/references/settings_example.png
index e015008b..45dfe599 100644
Binary files a/docs/references/settings_example.png and b/docs/references/settings_example.png differ
diff --git a/docs/references/tool_output_example.png b/docs/references/tool_output_example.png
index d37c381d..fb93131b 100644
Binary files a/docs/references/tool_output_example.png and b/docs/references/tool_output_example.png differ
diff --git a/docs/references/web_version_example.png b/docs/references/web_version_example.png
index 0d244aee..c4307e87 100644
Binary files a/docs/references/web_version_example.png and b/docs/references/web_version_example.png differ
diff --git a/packages/desktop/README.md b/packages/desktop/README.md
index db0d1e73..d95f8cf9 100644
--- a/packages/desktop/README.md
+++ b/packages/desktop/README.md
@@ -1,49 +1,32 @@
-# @openchamber/desktop
+# OpenChamber Desktop
[](https://github.com/btriapitsyn/openchamber/stargazers)
-[](https://github.com/btriapitsyn/openchamber/network/members)
[](https://github.com/btriapitsyn/openchamber/releases/latest)
-[](https://opencode.ai)
-[](https://zread.ai/btriapitsyn/openchamber)
[](https://discord.gg/ZYRSdnwwKA)
-[](https://ko-fi.com/G2G41SAWNS)
-Desktop application for the [OpenCode](https://opencode.ai) AI coding agent. Built with Tauri.
+A native macOS app for [OpenCode](https://opencode.ai). Feels like home — multiple windows, SSH remotes, project actions, and everything running locally.
-For the full project overview and screenshots, see the main repo:
+Full project overview, screenshots, and all features: [github.com/btriapitsyn/openchamber](https://github.com/btriapitsyn/openchamber)
-https://github.com/btriapitsyn/openchamber
+## Install
-## Installation
+Download from [Releases](https://github.com/btriapitsyn/openchamber/releases). Available for macOS (Apple Silicon and Intel).
-Download from [Releases](https://github.com/btriapitsyn/openchamber/releases).
+> **Prerequisite:** [OpenCode CLI](https://opencode.ai) installed.
-Currently available for macOS (Apple Silicon).
+## What makes the desktop app special
-## Prerequisites
+- **Remote instances over SSH** — connect to remote OpenChamber servers with dedicated lifecycle and UX flows
+- **Project Actions** — run dev servers, configure SSH port forwarding, open remote URLs locally
+- **Multi-window** — work on several projects in parallel, each in its own window
+- **"Open In" shortcuts** — open workspace in Finder, Terminal, or your editor of choice
+- **Local + remote switching** — jump between local and remote OpenChamber instances
+- **Native macOS integration** — menus, deep-links, auto-update, and polished window management
-- [OpenCode CLI](https://opencode.ai) installed (`opencode`)
+Plus everything from the shared OpenChamber UI: branchable timeline, Git sidebar, terminal, voice mode, and more.
-## Features
-
-### Core UI
-
-- Branchable chat timeline with `/undo`, `/redo`, and one-click forks from earlier turns
-- Smart tool UIs for diffs, file operations, permissions, and long-running task progress
-- Multi-agent runs from one prompt with isolated worktrees for safe comparisons
-- Git workflows in-app: identities, commits, PR creation, checks, and merge actions
-- Context visibility tools (token/cost breakdowns, raw message inspection, and activity summaries)
-- Integrated terminal with per-directory sessions and stable performance on heavy output
-
-### Desktop (macOS)
-
-- Native macOS menu integration with polished app actions and deep-link handling
-- Multi-window support for parallel project/session workflows
-- "Open In" shortcuts for Finder, Terminal, and your preferred editor
-- Fast switching between local and remote instances
-- Workspace-first startup flow with directory picker and steadier window restore behavior
-
-## Development
+
+Development
```bash
git clone https://github.com/btriapitsyn/openchamber.git
@@ -52,6 +35,8 @@ bun install
bun run desktop:dev
```
+
+
## License
MIT
diff --git a/packages/vscode/README.md b/packages/vscode/README.md
index 2beb662f..74219653 100644
--- a/packages/vscode/README.md
+++ b/packages/vscode/README.md
@@ -1,66 +1,75 @@
# OpenChamber VS Code Extension
[](https://github.com/btriapitsyn/openchamber/stargazers)
-[](https://github.com/btriapitsyn/openchamber/network/members)
-[](https://github.com/btriapitsyn/openchamber/releases/latest)
+[](https://github.com/btriapitsyn/openchamber/releases/latest)
[](https://discord.gg/ZYRSdnwwKA)
[](https://ko-fi.com/G2G41SAWNS)
-OpenChamber inside VS Code: embeds the OpenChamber chat UI in the activity bar and connects it to the [OpenCode](https://opencode.ai) API.
+[OpenCode](https://opencode.ai) AI coding agent, right inside your editor. No tab-switching, no context loss.
-- Project overview + screenshots: https://github.com/btriapitsyn/openchamber
+**Like the extension? There's also a [desktop app and web version](https://github.com/btriapitsyn/openchamber) with even more features.**
-## Features
+## What you get
-### OpenChamber UI
+- **Chat beside your code** — responsive layout that adapts to narrow and wide panels
+- **Agent Manager** — run the same prompt across multiple models in parallel, compare results side by side
+- **Right-click actions** — add context, explain selections, and improve code in-place
+- **Click-to-open** — file paths in tool output open directly in your editor; edit-style results land in a focused diff view
+- **Session editor panel** — keep chat sessions open alongside files
+- **Theme-aware** — adapts to your VS Code light, dark, and high-contrast themes
-- Branchable chat timeline with `/undo`, `/redo`, and one-click forks from earlier turns
-- Smart tool UIs for diffs, file operations, permissions, and long-running task progress
-- Live streaming updates with smoother auto-follow for long assistant responses
-- Mermaid diagrams rendered inline in chat with quick copy/download actions
-- Context visibility tools (token/cost breakdowns and raw message inspection)
-- Model selection UX (favorites, recents, and configurable tool output density)
-
-### VS Code Integration
-
-- Chat UI embedded in VS Code with responsive layouts for narrow/wide panels
-- Agent Manager for parallel multi-model runs from one prompt
-- Session editor panel to keep chats open beside your code
-- Right-click actions to add context, explain selections, and improve code in-place
-- Click-to-open files and native file attachments from within the extension
-- Managed runtime startup with hardened health checks and secure auth forwarding
-- Adapts to VS Code light/dark/high-contrast themes
+Plus everything from the shared OpenChamber UI: branchable timeline, smart tool UIs, voice mode, Git workflows, and more.
## Commands
| Command | Description |
|---------|-------------|
-| `OpenChamber: Focus on Chat View` | Focus chat panel |
-| `OpenChamber: Restart API Connection` | Restart OpenCode API process |
-| `OpenChamber: Show OpenCode Status` | Provide debug info useful for development or bug report |
+| `OpenChamber: Focus Chat` | Focus the chat panel |
+| `OpenChamber: New Session` | Start a new chat session |
+| `OpenChamber: Open Sidebar` | Open the OpenChamber sidebar |
+| `OpenChamber: Open Agent Manager` | Launch parallel multi-model runs |
+| `OpenChamber: Open Session in Editor` | Open current or new session in an editor tab |
+| `OpenChamber: Settings` | Open extension settings |
+| `OpenChamber: Restart API Connection` | Restart the OpenCode API process |
+| `OpenChamber: Show OpenCode Status` | Debug info for development or bug reports |
+
+### Right-click menu
+
+Select code in the editor, right-click, and find the **OpenChamber** submenu:
+
+| Action | Description |
+|--------|-------------|
+| Add to Context | Attach selection to your next prompt |
+| Explain | Ask the agent to explain the selected code |
+| Improve Code | Ask the agent to improve the selection in-place |
## Configuration
| Setting | Default | Description |
|---------|---------|-------------|
-| `openchamber.apiUrl` | `http://localhost:47339` | OpenCode API server URL. Not required by default. Spawns its own process when not set. |
+| `openchamber.apiUrl` | _(empty)_ | URL of an external OpenCode API server. Leave empty to auto-start a local instance. |
+| `openchamber.opencodeBinary` | _(empty)_ | Absolute path to the `opencode` CLI binary. Useful when PATH lookup fails. Requires window reload to apply. |
## Requirements
-- OpenCode CLI installed and available in PATH (or set via `OPENCODE_BINARY` env var)
-- VS Code 1.85.0+
+- [OpenCode CLI](https://opencode.ai) installed and available in PATH (or set `OPENCODE_BINARY` env var)
+- VS Code 1.85+
-## Development
+
+Development
```bash
bun install
-bun run --cwd packages/vscode build # build extension + webview
+bun run --cwd packages/vscode build
cd packages/vscode && bunx vsce package --no-dependencies
```
-## Local Install
+Install locally: `code --install-extension packages/vscode/openchamber-*.vsix`
-- After packaging: `code --install-extension packages/vscode/openchamber-*.vsix`
-- Or in VS Code: Extensions panel → "Install from VSIX…" and select the file
+
+
+## License
+
+MIT
diff --git a/packages/web/README.md b/packages/web/README.md
index 77c70435..df8749db 100644
--- a/packages/web/README.md
+++ b/packages/web/README.md
@@ -1,76 +1,103 @@
# @openchamber/web
[](https://github.com/btriapitsyn/openchamber/stargazers)
-[](https://github.com/btriapitsyn/openchamber/network/members)
[](https://github.com/btriapitsyn/openchamber/releases/latest)
-[](https://opencode.ai)
-[](https://zread.ai/btriapitsyn/openchamber)
[](https://discord.gg/ZYRSdnwwKA)
-[](https://ko-fi.com/G2G41SAWNS)
-Web/PWA interface for the [OpenCode](https://opencode.ai) AI coding agent.
+Run [OpenCode](https://opencode.ai) in your browser. Install the CLI, open `localhost:3000`, done. Works on desktop browsers, tablets, and phones as a PWA.
-This package installs the `openchamber` CLI that runs a local web server. For the full project overview and screenshots, see the main repo:
+Full project overview, screenshots, and all features: [github.com/btriapitsyn/openchamber](https://github.com/btriapitsyn/openchamber)
-https://github.com/btriapitsyn/openchamber
-
-## Installation
+## Install
```bash
-# Quick install (auto-detects your package manager)
curl -fsSL https://raw.githubusercontent.com/btriapitsyn/openchamber/main/scripts/install.sh | bash
-
-# Or install manually
-bun add -g @openchamber/web # or npm, pnpm, yarn
```
+Or install manually: `bun add -g @openchamber/web` (or npm, pnpm, yarn).
+
+> **Prerequisites:** [OpenCode CLI](https://opencode.ai) installed, Node.js 20+.
+
## Usage
```bash
-openchamber # Start on port 3000
-openchamber --port 8080 # Custom port
-openchamber --daemon # Background mode
-openchamber --ui-password secret # Password-protect UI
-openchamber --try-cf-tunnel # Create a Cloudflare Quick Tunnel for remote access
-openchamber --try-cf-tunnel --tunnel-qr # Show QR code for easy mobile access
-openchamber --try-cf-tunnel --tunnel-password-url # Include password in URL for auto-login
-OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber # Connect to external OpenCode server
-OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber # Connect via custom host/HTTPS
-openchamber stop # Stop server
-openchamber update # Update to latest version
+openchamber # Start on port 3000
+openchamber --port 8080 # Custom port
+openchamber --ui-password secret # Password-protect
+openchamber stop # Stop server
+openchamber update # Update to latest
```
-Named Tunnel mode is configured in-app (Settings -> OpenChamber -> Tunnel). The CLI currently supports Quick Tunnel flags only. `--tunnel ` is not supported yet.
+
+Remote access & tunnels
-### Environment Variables
+```bash
+openchamber --try-cf-tunnel # Cloudflare Quick Tunnel
+openchamber --try-cf-tunnel --tunnel-qr # + QR code for mobile
+openchamber --try-cf-tunnel --tunnel-password-url # + password in URL
+```
-- `OPENCODE_HOST` - Full base URL of external OpenCode server, e.g. `http://hostname:4096` or `https://hostname:4096` (overrides `OPENCODE_PORT`)
-- `OPENCODE_PORT` - Port of external OpenCode server to connect to (instead of starting embedded server)
-- `OPENCODE_SKIP_START` - Skip starting embedded OpenCode server (use with `OPENCODE_HOST` or `OPENCODE_PORT` to connect to external instance)
+Named Tunnel mode is configured in-app at **Settings > OpenChamber > Tunnel**. Requires [cloudflared](https://github.com/cloudflare/cloudflared/releases).
-## Prerequisites
+
-- [OpenCode CLI](https://opencode.ai) installed (`opencode`)
-- Node.js 20+
+
+Connect to external OpenCode server
-## Features
+```bash
+OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber
+OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber
+```
-### Core UI
+| Variable | Description |
+|----------|-------------|
+| `OPENCODE_HOST` | Full base URL of external server (overrides `OPENCODE_PORT`) |
+| `OPENCODE_PORT` | Port of external server |
+| `OPENCODE_SKIP_START` | Skip starting embedded OpenCode server |
-- Branchable chat timeline with `/undo`, `/redo`, and one-click forks from earlier turns
-- Smart tool UIs for diffs, file operations, permissions, and long-running task progress
-- Multi-agent runs from one prompt with isolated worktrees for safe comparisons
-- Git workflows in-app: identities, commits, PR creation, checks, and merge actions
-- Context visibility tools (token/cost breakdowns, raw message inspection, and activity summaries)
-- Integrated terminal with per-directory sessions and stable performance on heavy output
+
-### Web / PWA
+
+Docker
-- Cloudflare tunnel access with two modes: Quick Tunnel (CLI) and Named Tunnel (in-app settings)
-- One-scan onboarding with tunnel QR + password URL helpers
-- Mobile-first experience: optimized chat controls, keyboard-safe layouts, and attachment-friendly UI
-- Background notifications plus reliable cross-tab session activity tracking
-- Built-in self-update + restart flow that keeps your server settings intact
+```bash
+docker compose up -d # Available at http://localhost:3000
+```
+
+**Optional env vars:**
+```yaml
+environment:
+ UI_PASSWORD: your_secure_password
+ CF_TUNNEL: "true" # Options: true, qr, password
+```
+
+**Data directory:** mount `data/` for persistent storage. Ensure permissions:
+```bash
+mkdir -p data/openchamber data/opencode/share data/opencode/config data/ssh
+chown -R 1000:1000 data/
+```
+
+
+
+
+Background & daemon mode
+
+```bash
+openchamber --daemon # Run in background
+openchamber stop # Stop background server
+```
+
+
+
+## What makes the web version special
+
+- **Remote access** — Cloudflare tunnel with QR onboarding. Scan from your phone, start coding.
+- **Mobile-first PWA** — optimized chat controls, keyboard-safe layouts, drag-to-reorder projects
+- **Background notifications** — know when your agent finishes, even from another tab
+- **Self-update** — update and restart from the UI, server settings stay intact
+- **Cross-tab tracking** — session activity stays in sync across browser tabs
+
+Plus everything from the shared OpenChamber UI: branchable timeline, Git sidebar, terminal, voice mode, and more.
## License
-
+
