Bohdan Triapitsyn 005b2e61b0 Composer: CodeMirror editor, unified prompt language, ChatInput decomposition (#2419)
* refactor(ui): unify composer @mention grammar

Extract the composer's @mention rule into composer/language/mentions.ts and
route highlighting, send-time extraction, backspace-deletes-the-mention and
the file-path check through it. The rule previously lived as four separate
regexes in ChatInput.tsx with divergent cleanup, so every new reference type
had to be taught to all four.

Bracket handling is now symmetric: [ and { were accepted before @ but ] and }
were not stripped from the tail, so [@plan] resolved to the name 'plan]'.

Add characterization tests for the markdown tokenizer, which had none, to
pin current behavior ahead of the editor migration.

* refactor(ui): unify composer slash, snippet and trigger grammar

Extract /skill, /command and #snippet scanning into
composer/language/prefixTokens.ts, and the rule deciding which autocomplete a
caret asks for into composer/language/triggers.ts.

Each sigil previously had three separate implementations: one for
highlighting, one for send-time collection, and one for opening the picker.
They disagreed on the valid character set — the send-time skill scanner
accepted only lowercase names, so a /My_Skill token was painted as a command
but never collected. Scanning is now generous and membership in the command,
skill or snippet registry is the authority.

resolveAutocompleteTrigger replaces the 90-line branch chain in
updateAutocompleteState with a pure function, keeping the previous
command > skill > snippet > mention precedence.

* refactor(ui): tokenize the composer in a single pass

Add composer/language/tokenize.ts as the one entry point producing every
highlight range from the text plus what the composer knows about the
workspace. It replaces six independent memos in ChatInput.tsx that each
re-scanned the same string for markdown, fenced code, mentions, slash tokens,
snippet tokens and attachment citations.

Mentions now distinguish the reference span from the raw token: 'see @a/b.ts,'
highlights @a/b.ts and leaves the comma as sentence punctuation, while
backspace still deletes the whole token so a wrapping bracket is not orphaned.

* feat(ui): add the CodeMirror composer editor

Add composer/editor: a CodeMirror view that renders the prompt language as
mark decorations, and a controlled React primitive around it.

The composer previously painted a transparent textarea over a mirror div,
which restricted highlighting to styles that do not change glyph advance
width -- so bold and italic were impossible and the overlay was disabled
outright on mobile, where wrapped text drifted from the caret anyway.
CodeMirror owns the text and the caret together, removing the second layer.
The document stays a plain string, so nothing downstream has to serialize a
rich model back into a prompt.

Split resolveHighlightSegments out of buildHighlightParts so the mirror
overlay and the editor decorations share one priority resolution.

Not yet wired into ChatInput. Editor rendering is unverified: the package has
no DOM test environment, so only the state-level extension is covered.

* refactor(ui): move the composer onto the CodeMirror editor

Replace the transparent-textarea-over-mirror-div composer with ComposerEditor.
The mirror is gone, and with it the constraint that highlighting may only use
styles which do not change glyph advance width, and the mobile carve-out that
disabled highlighting entirely because wrapped text drifted from the caret.

Removals the editor makes unnecessary:
- measureCaretInTextarea, 46 lines of hand-built text mirroring for popup
  placement, replaced by the editor reporting caret coordinates
- adjustTextareaHeight and its two layout effects, replaced by the editor
  sizing itself; the dictation transcript height is now an explicit floor
- getInsertedTextFromChange, which diffed old against new text to recover what
  a paste inserted; the editor reports the change directly
- the highlight mirror element, its scroll-sync and its parts memo
- a _commandMetadata property stashed on the textarea and never read

Caret placement no longer needs a requestAnimationFrame after a text edit:
text and selection travel in one transaction.

Runtime behavior is unverified -- the package has no DOM test environment.
Type-check, lint, the 295 chat tests and a production web build pass.

* refactor(ui): extract composer text and path helpers

Move the composer's text-splicing rules to composer/text.ts and its path
handling to composer/attachments/filePaths.ts, with tests. None of this logic
was covered before, despite handling VS Code drop payloads, percent-encoded
file URIs and Windows drive letters.

normalizeDroppedPath and toProjectRelativeMentionPath were useCallbacks that
closed over nothing but their argument and the search directory; they are now
plain functions taking the root explicitly.

* refactor(ui): make the composer's slash commands a table

Nine of the composer's local commands did the same thing -- render a visible
magic prompt plus synthetic instructions and send them as one message -- and
that shape was written out nine times as an else-if chain. Adding a command
meant copying twenty lines and remembering to change every string.

composer/submit/slashCommands.ts holds the commands as data and the shape as
one executor; ChatInput keeps only the five that manipulate session state or
open UI. The command names, prompts and failure toasts are now typed against
the magic-prompt and i18n key unions, so a mistyped key fails to compile
rather than failing at runtime.

Net: 257 lines of branching become 68.

* refactor(ui): move the composer's footer components out of ChatInput

RevertedMessageDock, ComposerAttachmentControls, PermissionAutoAcceptButton,
FocusModeButton and ComposerActionButtons each own a piece of the composer
chrome and were defined inline above the 4500-line component. They now live
under composer/ui with the imports they actually need.

Pure moves; getRevertedPreview travels with the dock, its only caller.

* refactor(ui): extract composer draft persistence

Move the draft lifecycle -- identity switching, debounced writes, external
deletion, and the flush-on-hide/freeze/pagehide edges -- into
composer/state/useComposerDraft.

It was seven interleaved effects and five refs sharing state through the
component body, which made the ordering constraints between them (skip the
next debounced write while restoring; record the empty signature before a
queued write can resurrect a deleted draft) invisible. They are now stated
where they apply.

* refactor(ui): extract drop payload inspection

hasDraggedFiles, collectDroppedFiles and collectDroppedFileUris were
useCallbacks with empty dependency arrays -- pure DataTransfer readers wearing
React clothing. They move to composer/attachments/dataTransfer.ts with tests
covering the host differences they exist for: browser File lists, VS Code's
proprietary tree types, OpenChamber's own internal-drag marker, and getData
throwing during dragover.

* refactor(ui): extract the mobile composer shell

Move the pill state machine into composer/state/useMobileComposerShell and
the visual-viewport pinning into composer/state/useMobileViewportPin.

Between them they held eight refs, four pieces of state and eleven effects
interleaved with the rest of the composer, which hid what they are: not one
state machine but a state machine plus a set of corrections for specific
platform behaviors -- mobile browsers dismissing the keyboard before a tap's
click lands, iOS refusing programmatic focus outside a gesture, WebKit leaving
the layout viewport panned after the keyboard hides, overlay chains handing
off through a frame where nothing is open.

Verbatim moves: every timeout, flushSync and guard keeps its value and its
reason, because none of them is verifiable outside a real device.

* refactor(ui): extract outgoing message assembly

A single send can carry queued messages, the composer text, inline review
comments, resolved @file attachments, a linked issue or PR, synthetic parts
from conflict resolution, and a skills instruction -- all flattened into
OpenCode's one-primary-plus-parts shape. The flattening rules were spread
through handleSubmit with no coverage, so the ordering they encode (oldest
queued message becomes primary; inline comments attach to the last authored
body, not a new part; PR instructions precede the diff) was trusted rather
than checked.

buildOutgoingMessage is a pure function over injected resolvers, with 25 tests
covering that ordering.

* refactor(ui): extract new-session draft targeting

Move project and worktree selection for the new-session draft into
composer/state/useDraftTarget.

The rule worth naming is that the draft can point at a directory that does not
exist yet -- a worktree still being created. It has to survive not appearing
in the branch list, or the selector snaps back to the project root mid-creation
and the session starts in the wrong place.

* refactor(ui): extract composer context chips and linked reference rows

The chips standing for attached-but-not-typed context (review comments, dev
server logs, preview annotations, terminal selections) were four near-identical
inline blocks; three of them collapse into one CountChip.

The linked issue and linked PR rows were 100 lines of duplicated markup
differing only in their number label, their branch line and which picker they
reopen. They are now one LinkedReferenceRow.

* refactor(ui): extract draft target selectors

Move the project and branch pickers into composer/ui/DraftTargetSelectors:
inline selects for desktop, trigger buttons and bottom sheets for mobile, all
rendering the same options from useDraftTarget.

The project label -- custom icon image, configured icon, or a folder fallback,
with the project name -- was a useCallback rendering JSX and used from four
places; it is now a ProjectLabel component.

* refactor(ui): extract the collapsed mobile pill composer

Move the pill into composer/ui/MobilePillComposer. Both places that ask
dictation to start now go through one toggleDictation callback rather than
dispatching the global event inline.

* refactor(ui): extract the composer footer

Move the footer row into composer/ui/ComposerFooter, which now owns the
desktop and mobile layouts and the components they place. ChatInput keeps only
the handlers it passes in.

* refactor(ui): collapse the composer's four autocomplete states into one

The composer tracked each picker with its own show flag and query string,
which encoded 'exactly one is open' as four booleans that had to be kept
mutually exclusive by hand. It is now one openAutocomplete kind plus one
query, which is what resolveAutocompleteTrigger already returns.

The four popup blocks -- identical apart from their component and caret width
-- become ComposerAutocompletePopups.

* refactor(ui): extract autocomplete positioning and message history

useAutocompletePosition owns caret-relative popup placement, which only
applies in focus mode.

useMessageHistory owns arrow-key recall. Its transitions are pure functions
with tests: entering history stashes the draft exactly once, so walking back
several messages and returning still restores what the user actually typed
rather than the last recalled message.

* docs: document the composer module

Record what each layer owns and the invariants that are not visible from the
code: that the prompt language is the single source of truth for syntax, which
ordering rules in the submit assembly and draft lifecycle are load-bearing,
that the mobile hooks are platform corrections rather than state machines, and
that rendering, focus, keyboard and WKWebView behavior are not covered by
tests and must be verified by hand.

* fix(ui): restore the composer caret colour and click-to-focus

Two regressions from the editor migration.

The caret rendered black in dark themes. CodeMirror's base theme hard-codes it
through '.cm-editor.cm-light .cm-content', one class more specific than the
plain '.cm-content' rule the composer theme used, so the base theme won.
Matching that specificity with '&.cm-editor' fixes both variants.

Clicking the composer's empty space no longer focused it. A textarea filled
its box, so the browser placed the caret for any click inside it; CodeMirror's
content element covers only the text. The content box now stretches to the
full editor height, and clicks landing outside it — in the composer's padding
— are forwarded to the nearest text position.

The theme moves to its own module with a test that installs it. EditorView.theme
compiles selectors at import and throws on scopes it was not given, including
'&light' and '&dark'; neither the build nor the type-check catches that, and
the failure takes the whole composer down at runtime.

* fix(ui): colour the composer caret where it is actually drawn

The previous fix styled caret-color, which drawSelection() overrides with
'transparent !important' at the highest precedence -- it hides the native
caret and draws its own .cm-cursor element, whose base style is a hard-coded
'border-left: 1.2px solid black'. So the caret stayed black on dark themes.

CodeMirror recolours that cursor only for editors that declare themselves
dark. OpenChamber themes are not merely light or dark, so the cursor takes the
surface foreground directly instead.

The theme spec is exported and asserted against: the caret rule must target
.cm-cursor, must not style caret-color, and must carry enough specificity to
beat CodeMirror's own &dark override.

* feat(ui): add emphasis, attention and path highlighting to the composer

The constructs the editor migration was for.

- **bold** and *italic* render as real weight and slant. They are additive
  styles: a segment carries one class string, so choosing between weight and
  colour would lose one of them -- bold inside a heading now keeps the heading
  colour and gains weight.
- '!!! ' marks an attention line. Three marks, so a sentence ending in '!!'
  is not swallowed.
- '~path' highlights a path without attaching it, unlike '@path'. Inert by
  design: it feeds neither the autocomplete nor the send path.

False positives are excluded positionally rather than by character, since
these delimiters are ordinary prose: '2 * 3' and 'foo_bar' are not emphasis,
'~approximately' and '~1.2 seconds' are not paths.

Also fix the expanded composer, which kept the collapsed composer's eight-line
height cap: the editor scrolled inside an invisible window while the rest of
the surface sat empty.

* fix(ui): style the composer's selection instead of leaving CodeMirror's

Selecting text rendered it in CodeMirror's stock lavender, which buried the
token colours. drawSelection() paints its own layer and CodeMirror styles the
focused case through a six-class selector; the composer's rule was three deep
and lost.

The tint is translucent rather than the flat selection token: an opaque
selection hides the colours the composer exists to show, and selecting text
here is for moving it, not for stopping reading it.

Same failure shape as the caret, so the theme test now covers both.

* fix(ui): mute the composer placeholder

The placeholder rendered at full text brightness. Its colour referenced
--surface-mutedForeground, but the theme emits --surface-muted-foreground:
an unknown custom property makes the declaration invalid rather than falling
back, and since color inherits, the placeholder simply took the editor's text
colour while the source looked correct.

The theme test now rejects camelCased tokens outright, since this failure is
invisible in every check that does not render.

* fix(ui): create the composer editor before the expand gesture ends

The mobile pill expands with flushSync and focuses the editor on the very next
line, still inside the tap's call stack, because that is the only way a mobile
browser raises the keyboard. The EditorView was created in a passive effect,
which flushSync makes no promise about — so at the moment focus() was called
there was no view to focus.

With a textarea the element existed as soon as flushSync returned, which is
why this worked before the migration.

Creating the view in a layout effect restores that ordering.

* perf(ui): keep the composer editor alive across the mobile pill swap

The pill and the full composer are different subtrees, so expanding or
collapsing unmounted and rebuilt the editor. With a textarea that was one DOM
node. A CodeMirror view is extensions, state, document, decorations and a
first measure — all inside the tap's flushSync, before the browser is allowed
to paint the swap. The shape change therefore landed late enough to look
driven by the keyboard rather than by the tap.

The view now lives in a store owned by ChatInput and is detached and
re-attached instead of destroyed and rebuilt. Its extensions read callbacks
through a ref held by the store, so a kept view always calls into the mounted
instance; compartments move to module scope, since per-instance ones would be
unknown to a reused view's configuration.

Also restore the caret hold: WKWebView draws the caret as a native layer that
ignores CSS transforms and visibly flies across the screen during the keyboard
slide. The rule hiding it targeted textarea and input, which the composer is
no longer — and its caret is now a drawn .cm-cursor element rather than the
native one.

* debug(ui): on-screen timeline for the mobile composer swap

TEMPORARY, Capacitor-only. Two plausible fixes for the swap lagging behind
the keyboard changed nothing, so the theory behind them was wrong. This
overlay draws the event timeline straight onto the screen -- the tap, the
committed swap, the first paints after it, the keyboard choreography, and
whether the editor was created or re-attached -- so one screenshot replaces
guessing. It doubles as an asset-freshness check: no overlay means the app
runs a bundle from before this commit.

* fix(ui): put the composer swap on glass before the keyboard moves

The overlay timelines settled it. The swap itself was never slow: commit in
12ms, editor re-attach in 3ms, focus immediate. What lagged was presentation:
WKWebView stops presenting web frames the moment focus starts the keyboard
transition and holds the last presented frame until it ends. Focusing in the
same task as the swap meant the last presented frame still showed the pill —
paint-1 fired at 29ms, the next frame at 190ms, exactly when the keyboard
was already moving.

On expand, Capacitor now waits two frames before focusing, so the swapped
composer is presented first and the keyboard rises under it. The Capacitor
WebView raises the keyboard for a focus() outside the gesture task; mobile
browsers do not, so they keep the synchronous path.

The collapse direction had a genuine race, caught on one screenshot: the
oc:keyboard-intent collapse arrives a few milliseconds after blur on a
setTimeout(0), and React's scheduling of setFocused(false) can lose to it —
busyRef stays stale, the intent handler skips the instant collapse, and the
pill appears via the 250ms fallback, 370ms after the keyboard has gone.
The Capacitor blur branch now commits the state with flushSync.

The diagnostic overlay stays in until this is confirmed on device.

* fix(ui): raise the keyboard from the swap's first frame

Two frames of delay before focusing made expand visibly sequential: swap,
then keyboard. Focusing inside the first frame after the commit puts the
swap's frame into the rendering pipeline before the keyboard transaction
starts, so the keyboard rises from the tap and the composer appears during
the rise rather than after it.

* fix(ui): restructure the draft screen in the same frame as the pill swap

The draft screen centers its title over the space the composer leaves, and
its starter chips leave when the keyboard is up. The chips were keyed on
oc-keyboard-open, which lands with the keyboardWillShow bridge event ~100ms
after the tap — so expanding the composer restructured the page twice: once
at the swap (composer grows, title re-centers) and again mid-keyboard-rise
(chips vanish, title re-centers again). Chat has no centered content, which
is why it was already smooth and the draft screen was not.

A root class now announces the expanded composer from a layout effect, in the
same frame as the swap, and the chips key on it: one restructure, fused with
the pill morph, before the keyboard moves. The keyboard classes remain as
fallbacks for keyboard-up states that do not go through the pill.

* debug(ui): remove the mobile swap timeline overlay

The diagnostic did its job: it identified WKWebView's presentation pause
during keyboard transitions, the React-scheduling race in the collapse path,
and the draft screen's double restructure — all fixed and confirmed on
device.

* feat(ui): grow the mobile composer with content, drop the fullscreen handle

The swipe-up handle promised a fullscreen composer but the normal eight-line
cap already reached within a line of the same height, so the gesture bought
almost nothing and cost a 28px bar above the editor.

The composer now just grows with what is typed: a generous line cap plus a
CSS ceiling of the space the keyboard actually leaves, whichever is smaller
(the editor cap accepts both and takes min()). The handle, its swipe
gestures and the shell's touch plumbing are gone.

* fix(ui): measure the mobile composer ceiling instead of estimating it

The 220px chrome constant guessed at what surrounds the editor. The old
fullscreen handle guessed at nothing — it let flex distribute real space (and
on Capacitor even that silently failed: its h-full resolved against a
shrink-wrap parent, which is why the gesture bought almost nothing).

The ceiling is now measured the way the handle meant to: the screen container
is marked data-composer-bound, and the editor may grow until the composer
fills it — chrome around the editor read live from the DOM, so attachment
chips, the model row and keyboard resizes all shift the cap by themselves.

* fix(ui): keep a 4px gap between the grown composer and the header

On the chat screen the fully grown composer's border landed exactly on the
header's bottom edge. The gap is a visual design choice, not another chrome
estimate: the ceiling itself stays measured.

* fix(ui): show iOS selection handles without giving up typing speed

iOS pins its selection drag handles to the visible native selection and
colours them from the caret, while drawSelection() hides both. Removing
drawSelection(), or leaving the native caret visible while typing, both
make iOS answer every keystroke with severe input lag. Touch devices now
keep drawSelection() and layer a theme over it that re-shows the native
selection, plus an .oc-native-range marker that enables the native caret
only while a range is selected — when there is no caret to lag on.

* feat(ui): make file mentions editable instead of atomic-delete

Deleting a character inside an @file mention edited nothing and erased the
whole token. Mentions now edit like /skill tokens: a deletion changes the
text and the caret position reopens the file picker on its own. findMentionAt
and MentionToken.rawEnd existed only for the atomic delete and are removed.

* fix(ui): composer selection visibility and external-insert caret

Selection was nearly invisible for two reasons: the tint was mixed down from
--interactive-selection, which themes define with its own alpha (often under
10%); and the painted selection layer sits behind the content, so tokens with
their own background (inline code, fences) covered it entirely. The native
selection now shows on every device, not only touch — it paints over token
backgrounds — and its tint comes from --primary at 25%, a full-strength
colour in every theme. drawSelection() and the range-scoped native caret stay
exactly as before, so typing keeps the lag-free path.

External rewrites (add-to-chat, draft restore, history, dictation) also left
the caret at its old position, so the next insertion landed inside the
previous one. They now put the caret at the end, as the old textarea did, and
pin the scroller to the bottom once the layout settles — a transaction-time
scrollIntoView fires before the max-height cap exists and scrolls nothing.

* fix(ui): render ***triple emphasis*** as bold italic

The emphasis tokenizer capped delimiter runs at two characters, so ***x***
parsed as a stray asterisk plus an italic span. Runs of three now emit both a
strong and an emphasis range over the same content; the two are additive
styles, so they compose into bold italic.

* fix: insert mentions through editor dispatch

Places the caret immediately after an inserted mention
Avoids rewriting the whole message and jumping the scroll to the bottom
Falls back to appending inline text when no editor is available
2026-07-27 22:21:38 +03:00
2025-12-07 19:32:53 +02:00
2026-06-10 12:00:10 +03:00
2025-12-07 19:32:53 +02:00
2025-12-07 19:32:53 +02:00
2025-12-07 19:32:53 +02:00
2025-12-07 19:32:53 +02:00
2026-06-16 23:40:00 +03:00
2025-12-07 19:32:53 +02:00

OpenChamber

GitHub stars GitHub release Created with OpenCode Discord Support the project

OpenCode, everywhere. Desktop. Browser. Phone.

A rich interface for OpenCode. Review diffs, manage agents, run dev servers, and keep the big picture while your AI codes.

OpenChamber Chat

More screenshots

Tool Output Settings Diff View VS Code Extension

PWA Chat PWA Diff

Why use OpenChamber?

  • 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

Features

Core (all app versions)

  • 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

Web / PWA

  • Provider-aware tunnel access model with Cloudflare quick, managed-remote, and managed-local modes
  • 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

Desktop (macOS + Windows + Linux)

  • Floating Mini Chat: keep a small always-on-top assistant beside your editor, browser, or terminal
  • Multiple native windows for separate projects or sessions
  • Native notifications for task alerts while OpenChamber is hidden
  • One-click open in VS Code, Cursor, Terminal, Finder, Explorer, and more
  • Desktop host switcher for local and remote OpenChamber instances
  • Convenient tunnel management without manual setup
  • Deep-link connections for joining remote OpenChamber from a link
  • SSH remote access with host import, connection management, and port forwarding

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

  • 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.

Quick Start

Prerequisite: Desktop bundles the matching OpenCode CLI. CLI/Web and VS Code use your installed OpenCode CLI.

Desktop (macOS + Windows + Linux)

Download the latest Desktop release from GitHub Releases.

On Linux, choose the AppImage for your system:

  • linux-x86_64.AppImage for 64-bit Intel or AMD systems
  • linux-arm64.AppImage for ARM64/aarch64 systems

Make the AppImage executable before launching it, for example with chmod +x <downloaded-appimage>. Keep the AppImage in a location your user can write to so OpenChamber can download and apply in-app updates.

Linux AppImages need FUSE (libfuse.so.2). On Ubuntu/Debian install libfuse2 (or fuse / libfuse2t64 on newer releases). If FUSE is unavailable, run with extraction instead:

APPIMAGE_EXTRACT_AND_RUN=1 ./OpenChamber-*-linux-*.AppImage

Linux Desktop ships as AppImage with in-app window controls and auto-update when running from a writable AppImage.

VS Code

Install from Marketplace or search "OpenChamber" in Extensions.

CLI (Web + PWA)

requires Node.js 22+

curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/scripts/install.sh | bash
openchamber --ui-password be-creative-here
Advanced CLI options
openchamber --port 8080              # Custom port
openchamber --lan --port 3000        # Listen on LAN (0.0.0.0)
openchamber --ui-password secret     # Password-protect UI
openchamber startup enable           # Start at login as a native service
OPENCHAMBER_UI_PASSWORD=secret openchamber startup enable # Save service password env
openchamber startup status           # Show startup service status
openchamber startup disable          # Remove startup service
openchamber tunnel help              # Tunnel lifecycle commands
openchamber tunnel providers         # Show provider capabilities
openchamber tunnel profile add --provider cloudflare --mode managed-remote --name prod-main --hostname app.example.com --token <token>
openchamber tunnel start --profile prod-main
openchamber tunnel start --provider cloudflare --mode quick --qr
openchamber tunnel start --provider cloudflare --mode managed-local --config ~/.cloudflared/config.yml
openchamber tunnel status --all      # Show tunnel state across instances
openchamber tunnel stop --port 3000  # Stop tunnel only (server stays running)
openchamber connect-url --port 3000  # Add this server to OpenChamber Desktop
openchamber connect-url --server http://host:3000 --qr
openchamber connect-url --port 3000 --qr
openchamber logs                     # Follow latest instance logs
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

startup enable snapshots your current environment into the native service so startup behaves like you launched openchamber from the same shell. This preserves provider tokens, PATH, SSH agent settings, and other CLI auth/config env vars. Use --no-env-snapshot if you want a minimal service env.

Connect to an existing OpenCode server:

OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber
OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber

Bind managed OpenCode server to all interfaces (use only on trusted networks):

OPENCHAMBER_OPENCODE_HOSTNAME=0.0.0.0 openchamber --port 3000

Expose OpenChamber itself on your LAN:

openchamber --lan --port 3000 --ui-password secret

Add this server to OpenChamber Desktop or another OpenChamber app:

openchamber connect-url --port 3000 --qr

If no OpenChamber server is running on that port, connect-url starts one before generating the link.

Headless/API-only setup for a remote machine:

openchamber connect-url --port 3000 --api-only --lan --server http://your-host-or-ip:3000 --qr --ui-password secret

This runs OpenChamber as an API-only server without the desktop app or browser UI assets on that machine, then creates a link for Desktop to import. --lan makes the server reachable from other machines. --server is the address Desktop should use.

When OpenChamber was started with --lan or --host 0.0.0.0, connect-url automatically uses a detected LAN IP instead of 127.0.0.1. Use --server http://host:3000 to override the advertised address, and include --lan when connect-url needs to start the server for LAN access.

Paste the printed openchamber://connect?... link in Desktop under Settings -> Remote Instances -> Direct Instances -> Import Link. The link contains the server URL and a client token. It does not enable browser UI password protection; use --ui-password when exposing a server beyond localhost.

systemd service (VPN / LAN access)

Run OpenChamber and OpenCode as separate persistent services — useful when you want to access your dev machine over a VPN (e.g. Tailscale) or LAN without a Cloudflare tunnel.

How it works:

  • OpenCode runs as its own service, binding only to localhost.
  • OpenChamber connects to it via OPENCODE_HOST and --lan makes it reachable on your VPN IP.
  • --foreground keeps the CLI process alive so systemd can track and restart it.

~/.config/systemd/user/opencode.service

[Unit]
Description=OpenCode Server

[Service]
Type=simple
ExecStart=opencode serve --port 4095
Environment="PATH=/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin:/home/YOU/.local/bin:/home/YOU/.npm-global/bin:/usr/local/bin:/usr/bin:/bin"
Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Why set PATH and SSH_AUTH_SOCK? systemd user services start with a minimal environment — no shell profile is sourced. Without an explicit PATH, OpenCode won't find tools installed via Homebrew, npm, or ~/.local/bin. Without SSH_AUTH_SOCK, git operations over SSH (push, pull, clone) will fail because the agent socket isn't inherited. Adjust the PATH to match your own tool installation paths. %t expands to $XDG_RUNTIME_DIR (e.g. /run/user/1000), where most SSH agents write their socket.

~/.config/systemd/user/openchamber.service

[Unit]
Description=OpenChamber Web Server
After=opencode.service

[Service]
Type=simple
ExecStart=openchamber serve --port 3000 --host 0.0.0.0 --ui-password your-password --foreground
Environment="OPENCODE_HOST=http://localhost:4095"
Environment="OPENCODE_SKIP_START=true"
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now opencode openchamber

OpenChamber will be reachable at http://<your-vpn-hostname>:3000 from any device on your VPN.

Note: --host 0.0.0.0 is required to listen on all interfaces. The default bind address is 127.0.0.1 (localhost only). Use --host <ip> or OPENCHAMBER_HOST=<ip> to bind to a specific interface instead.

Docker
docker compose up -d

Available at http://localhost:3000.

UI Password:

environment:
  UI_PASSWORD: your_secure_password

Cloudflare Tunnel (optional):

environment:
  OPENCHAMBER_TUNNEL_MODE: quick # quick | managed-remote | managed-local
  OPENCHAMBER_TUNNEL_PROVIDER: cloudflare

For managed-remote mode, provide:

environment:
  OPENCHAMBER_TUNNEL_MODE: managed-remote
  OPENCHAMBER_TUNNEL_HOSTNAME: app.example.com
  OPENCHAMBER_TUNNEL_TOKEN: <token>

For managed-local mode, optionally provide:

environment:
  OPENCHAMBER_TUNNEL_MODE: managed-local
  OPENCHAMBER_TUNNEL_CONFIG: /home/openchamber/.cloudflared/config.yml

Managed-local path note: OPENCHAMBER_TUNNEL_CONFIG must point to a path inside the container user home (/home/openchamber/...). If your Cloudflare config references a credentials JSON file, that file path must also be accessible inside the container (mount with volumes).

Reverse proxy notes

  • For a complete reverse proxy setup guide, see docs/REVERSE_PROXY.md.
  • Website docs source lives at packages/docs/content/docs/reverse-proxy.mdx.

Tunnel behavior notes

  • OpenChamber supports one active tunnel per running instance (port).
  • Starting a tunnel with a different mode/provider on the same instance replaces the current tunnel.
  • Replacing or stopping a tunnel revokes existing connect links and invalidates remote tunnel sessions for that instance.
  • Connect links are one-time tokens; generating a new link revokes the previous unused link.

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:

mkdir -p data/openchamber data/opencode/share data/opencode/config data/ssh
chown -R 1000:1000 data/

SSH/Git: If git push/pull fails, run ssh -T git@github.com in terminal.

Features

Chat & Interaction
  • 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
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, Vim mode, 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, managed-remote, and managed-local 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 + Windows + Linux)
  • Floating Mini Chat: keep a small always-on-top assistant beside your editor, browser, or terminal
  • Multiple native windows for separate projects or sessions
  • Native notifications for task alerts while OpenChamber is hidden
  • One-click open in VS Code, Cursor, Terminal, Finder, Explorer, and more
  • Desktop host switcher for local and remote OpenChamber instances
  • Convenient tunnel management without manual setup
  • Deep-link connections for joining remote OpenChamber from a link
  • SSH remote access with host import, connection management, and port forwarding
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

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:

  • 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 the OpenCode team.

Special thanks to:

  • OpenCode - For the excellent API and extensible architecture.
  • Flexoki - Beautiful color scheme by Steph Ango.
  • Pierre - Fast, beautiful diff viewer with syntax highlighting.
  • Ghostty-web - Great implementation of a Ghostty web renderer.
  • David Hill - Who inspired me to release this without overthinking.
  • My wife, 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 for development setup and guidelines.

Docs source lives in packages/docs.

License

MIT

S
Description
No description provided
Readme MIT
82 MiB
Languages
TypeScript 74.8%
JavaScript 19.8%
MDX 4.7%
CSS 0.4%
HTML 0.1%
Other 0.1%