adom-vscode

@@ -1,10 +1,10 @@ # adom-vscode -A CLI + VS Code extension that lets AI assistants drive VS Code from inside an Adom Docker container — open files, switch modes, paste screenshots, and run any VS Code command via a local HTTP API on port 8821.+A CLI + VS Code extension that lets AI assistants and the Hydrogen Desktop / Hydrogen Web frontend drive VS Code from inside an Adom Docker container: open files, change settings live, run container commands, pass events to the frontend, switch modes, paste screenshots, and run any VS Code command via a local HTTP API on port 8821.  ## The Adom panel — your AI's cockpit inside VS Code -Click the Adom icon in the activity bar to open a side panel with the Overview, Modes, Commands, AI Prompts, and the live **Claude Context** viewer — every active Claude Code session in the container with token cost and last activity at a glance.+Click the Adom icon in the activity bar to open a side panel with the Overview, Modes, Commands, AI Prompts, Settings & Theme, Exec & Queue, Container & Keys, Extensions, and the live **Claude Context** viewer — every active Claude Code session in the container with token cost and last activity at a glance.  ![adom-vscode panel — activity bar sidebar with Overview, Modes, Commands, AI Prompts, and the Claude Context viewer listing live sessions](screenshots/panel.png) @@ -12,14 +12,19 @@ Click the Adom icon in the activity bar to open a side panel with the Overview,  Installed in every Adom container. Open the Extensions sidebar and search for `adom-vscode` — the details pane renders the full quick-start guide, mode reference, and version metadata. -![adom-vscode in the Extensions sidebar with the detail tab open, showing description, version 1.0.6, and the in-editor README](screenshots/extension-about.png)+![adom-vscode in the Extensions sidebar with the detail tab open, showing description, version, and the in-editor README](screenshots/extension-about.png)  ## What it does  - **Open files** in VS Code tabs (images, text, anything) - **Reveal** files/folders in the Explorer sidebar - **Preview** Markdown files in rendered view-- **Search/install** VS Code extensions+- **Settings, live**: get/set any VS Code setting, theme, fonts, font sizes. Changes apply immediately via the native VS Code API (no reload, active AI sessions survive)+- **Exec**: run shell commands in the container as the workspace user, streamed (SSE) or buffered — no host-side `wsl.exe` needed+- **Event queue**: any container process pushes events; the HD/HW frontend pulls them when it wants (login-refresh needed, long-job progress, anything)+- **Container identity**: query whether this is an `hd` (local Hydrogen Desktop) or `hw` (Adom cloud) container, OS, kernel, key env vars+- **API key**: check the health of `/var/run/adom/api-key` and inject a fresh key after a frontend login refresh+- **Extensions**: list installed extensions (with Claude/Codex/Kimi summary), query version + running state + pending update, update one or all, search, install - **Start** new Claude Code conversations - **Modes** — switch VS Code into different full-screen experiences:   - `claudecode` — Claude Code panel UI (graphical AI chat)@@ -27,14 +32,13 @@ Installed in every Adom container. Open the Extensions sidebar and search for `a   - `tty` — generic full-screen terminal with optional auto-command - **Control layout** — sidebar, panel, terminal, activity bar (show/hide/toggle) - **Run** any VS Code command (generic escape hatch)-- **Activity bar icon** — Adom icon with accordion sidebar showing commands, AI prompts, and modes - **Paste image into terminal** — Ctrl+V an image while focused in a code-server terminal uploads to `/tmp/shots/` and pastes the file path (so the CLI Claude Code can ingest it)  ## Already installed  Adom VS Code ships with every Adom container — you have it on day one. Try it now: ask Claude in any terminal: -> *"open `ne555-timer.kicad_sch`"* &nbsp;·&nbsp; *"switch to Claude Code mode"* &nbsp;·&nbsp; *"reveal the molecules folder"*+> *"open `ne555-timer.kicad_sch`"* &nbsp;·&nbsp; *"set my editor font size to 14"* &nbsp;·&nbsp; *"switch to Claude Code mode"* &nbsp;·&nbsp; *"is my api key still good?"*  To upgrade after a new release lands on the wiki, ask Claude: @@ -42,24 +46,113 @@ To upgrade after a new release lands on the wiki, ask Claude:  Or run it yourself: `adom-wiki pkg update adom-vscode`. -## Quick start+## Port discovery++The extension serves its HTTP API on **127.0.0.1:8821**. If 8821 is already taken it walks 8822..8831, then takes an ephemeral port, and writes the truth to:++```+~/.local/share/adom-vscode/port.json    # { "port": N, "preferredPort": 8821, "pid": ..., "version": ..., "startedAt": ... }+```++External services that expect the well-known port should read that file when 8821 does not answer. The CLI already does (resolution order: `ADOM_VSCODE_PORT` env var, then `port.json`, then 8821). `GET /health` reports both `port` (actual) and `preferredPort`.++## HTTP API (the verb surface)++Everything the CLI does is a plain HTTP call, so HD, HW, and any script can hit the API directly. `GET /health` returns `{version, port, preferredPort, portFile, verbs: [...]}` so callers can feature-detect instead of gating on versions.++| Verb | Method + route | What it does |+|------|----------------|--------------|+| health | `GET /health` | Liveness, version, actual port, full verb roster |+| open | `POST /open` `{path}` | Open a file in a tab |+| reveal | `POST /reveal` `{path}` | Reveal in Explorer sidebar |+| preview-markdown | `POST /preview-markdown` `{path}` | Rendered Markdown preview |+| config.get | `GET /config?key=<dotted.key>` | Effective value + default/global/workspace layers |+| config.set | `POST /config` `{key, value}` | Set in User (Global) settings, applies live, no reload |+| theme.get | `GET /theme` | Active theme, preferred dark/light, all installed themes |+| theme.set | `POST /theme` `{theme}` | Switch color theme live |+| fonts.get | `GET /fonts` | All font settings (editor, terminal, chat prose `chat.fontFamily`, chat code `chat.editor.fontFamily`) plus the RESOLVED families the renderer actually shows (via `document.fonts.check`) |+| fonts.set | `POST /fonts` `{editorFamily?, proseFamily?, proseCodeFamily?, editorSize?, terminalSize?, proseSize?, proseCodeSize?}` | Set any subset live |+| exec | `POST /exec` `{command, cwd?, timeoutSec?}` | Buffered: run `bash -lc` as the workspace user, return `{exitCode, stdout, stderr, timedOut}` |+| exec.stream | `POST /exec/stream` `{command, cwd?, timeoutSec?}` | Streaming: SSE events `start`, `stdout`, `stderr`, `exit {exitCode, timedOut}` |+| queue.push | `POST /queue/push` `{topic?, type?, payload?, ttlSec?}` | Push an event for the frontend; returns `{id, depth}` |+| queue.pull | `GET/POST /queue/pull` `{topic?, max?, peek?}` | Pull (consume) events; `peek` reads without consuming |+| queue.status | `GET /queue/status` | Depth + per-topic counts |+| queue.clear | `POST /queue/clear` `{topic?}` | Drop all events, or one topic |+| container.info | `GET /container` | `kind: hd\|hw\|unknown`, cloud flag, OS, kernel, hostname, carbon URL, VS Code proxy URI, detection markers |+| apikey.status | `GET /apikey` | `/var/run/adom/api-key`: exists, readable, size, age, sha256 fingerprint |+| apikey.set | `POST /apikey` `{value}` | Write a fresh key (root-owned path, goes through passwordless sudo) |+| extensions.list | `GET /extensions` (`?all=1` incl. builtins, `?id=x&latest=1` for one + gallery check) | Installed extensions + `ai` summary for claude/codex/kimi |+| extensions.update | `POST /extensions/update` `{id?}` | Update one extension, or all when `id` omitted |+| extensions.search | `POST /extensions/search` `{query}` | Open Extensions sidebar with a query |+| extensions.install | `POST /extensions/install` `{id}` | Install by marketplace id |+| claude.new | `POST /claude/new` | New Claude Code conversation |+| claude.context | `GET /claude/context` | Live AI session stats (context %, cache, tools, compactions) |+| command | `POST /command` `{command, args?}` | Any VS Code command (escape hatch) |+| notify | `POST /notify` `{message, level?}` | Toast notification |+| mode.* | `POST /mode/claudecode\|claudetty\|tty\|reset` | Full-screen mode switching |+| paste-screenshot | `POST /paste-screenshot` (raw image body) | Save clipboard image to `/tmp/shots/` |++The event queue survives window reloads (persisted to `~/.local/share/adom-vscode/queue.json`, capped at 1000 items, optional per-item TTL).++### Why the settings verbs matter++`POST /config` uses `vscode.workspace.getConfiguration().update(key, value, ConfigurationTarget.Global)`, which applies **immediately** with no window reload. That fixes two long-standing frontend bugs at once: font-size changes that silently never landed when a host-side settings.json merge hung, and theme changes that needed a full workbench reload (which dropped the user's Claude sessions).++For fonts, `GET /fonts` reports the **resolved** family the renderer actually shows (checked with `document.fonts.check` in the workbench), not just the configured stack. The configured chain often names a font that is not installed on the rendering side; the frontend needs the true value for its readout.++## CLI quick start  ```bash-adom-vscode health                        # Check extension is running+adom-vscode health                        # Liveness + version + verb roster adom-vscode open /path/to/file.png        # Open file in VS Code tab adom-vscode reveal /path/to/folder/       # Reveal in Explorer sidebar adom-vscode preview /path/to/README.md    # Markdown preview-adom-vscode claude new                    # New Claude Code chat-adom-vscode sidebar toggle                # Toggle sidebar-adom-vscode panel toggle                  # Toggle bottom panel-adom-vscode terminal new                  # New terminal-adom-vscode activity-bar toggle           # Toggle activity bar-adom-vscode extensions search "python"    # Search extensions-adom-vscode extensions install ms-python.python  # Install by ID-adom-vscode notify "Build complete"       # Toast notification-adom-vscode reload                        # Reload VS Code window-adom-vscode command <any-vscode-command>  # Generic escape hatch-adom-vscode --help                        # All commands++# Settings (all apply live, no reload)+adom-vscode config get workbench.colorTheme+adom-vscode config set editor.fontSize 14+adom-vscode theme get+adom-vscode theme set "Adom Dark"+adom-vscode font get+adom-vscode font set --editor-size 14 --prose-family Inter+adom-vscode font-size get+adom-vscode font-size set --editor 14 --terminal 13 --prose 15++# Exec (streams live by default; --json for buffered)+adom-vscode exec "ls -la" --cwd /home/adom/project+adom-vscode exec "npm test" --timeout 600+adom-vscode exec "uname -a" --json++# Event queue (container process -> HD/HW frontend)+adom-vscode queue push login --type refresh-needed --payload '{"expiresInHours":24}'+adom-vscode queue pull --topic login+adom-vscode queue pull --peek+adom-vscode queue status+adom-vscode queue clear --topic progress++# Container identity + API key+adom-vscode container+adom-vscode apikey status+adom-vscode apikey set --stdin < new-key.txt++# Extensions+adom-vscode extensions list+adom-vscode extensions status anthropic.claude-code --latest+adom-vscode extensions update anthropic.claude-code+adom-vscode extensions update+adom-vscode extensions search "python"+adom-vscode extensions install ms-python.python++# Layout, modes, misc+adom-vscode claude new+adom-vscode sidebar toggle+adom-vscode panel toggle+adom-vscode terminal new+adom-vscode activity-bar toggle+adom-vscode notify "Build complete"+adom-vscode reload                        # Reload VS Code window (drops AI sessions!)+adom-vscode command <any-vscode-command>+adom-vscode --help ```  ## Modes@@ -91,50 +184,23 @@ Example: `https://<slug>.adom.cloud/?mode=claudecode&folder=/home/adom/project`  When you press Ctrl+V with an image on the clipboard while focused in a code-server terminal (e.g. running CLI Claude Code), the interceptor uploads the image to the extension at `POST /paste-screenshot`, which saves it to `/tmp/shots/` (deduplicated via SHA-256) and writes the file path back to the terminal so the CLI can ingest it. Without this, code-server returns an empty string for clipboard.readText() when the clipboard holds only an image, so the paste does nothing. -## Activity bar--The extension adds an Adom icon to the VS Code activity bar. Click it to open a sidebar with accordion sections:--- **Overview** — what the extension does-- **Modes** — Claude Code, TTY modes with "open in new window" and "copy URL" buttons-- **Commands** — all CLI commands with hover tooltips-- **AI Prompts** — sample prompts to paste into Claude Code chat- ## Architecture  ```-Claude Code / scripts / shotlog-    ↓  runs CLI+Claude Code / scripts / HD frontend+    ↓  runs CLI or hits HTTP directly adom-vscode open /foo/bar.png-    ↓  HTTP POST to localhost:8821+    ↓  HTTP POST to localhost:8821 (see Port discovery) Adom VS Code Extension (inside code-server)-    ↓  vscode.* API-VS Code UI+    ↓  vscode.* API / child_process+VS Code UI + container shell ```  See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design document. See [COMMANDS.md](COMMANDS.md) for all VS Code commands usable with `adom-vscode command <id>`. -## Development--```bash-# Build everything locally-bash build.sh--# Release (single binary ships everything)-VERSION=$(cat VERSION | tr -d '[:space:]')-gh release create v${VERSION} \-  cli/target/release/adom-vscode \-  --repo adom-inc/adom-vscode \-  --title "v${VERSION}"-```- ## Version -The version lives in `VERSION` (single source of truth) and flows to:-- `extension/package.json`-- `cli/Cargo.toml`-- VSIX manifest (via `build.sh`)-- Activity bar sidebar footer-- Health endpoint response-- CLI `--version` flag+The wrapped tool version lives in `VERSION`; the wiki package version is in `package.json`.++Tool v1.1.0 added: live config/theme/font verbs, streamed exec, the frontend event queue, container identity (hd/hw), api-key status/inject, extension query/update (incl. Claude/Codex/Kimi), port fallback + `port.json` discovery, and verb-roster feature detection on `/health`.

@@ -1,6 +1,6 @@ --- name: adom-vscode-description: "Control VS Code Server (code-server) from inside the Docker container. THIS is the wrapper for the VS Code FILE EXPLORER sidebar, editor tabs, markdown preview, etc. — when the user says 'reveal in file explorer' or 'open in vscode' they mean this CLI, NOT adom-desktop (which controls Chrome browser windows). Open files, reveal in Explorer sidebar, preview markdown, search/install extensions, start Claude Code chats, switch UI modes (claudecode, claudetty, tty), show notifications, run any VS Code command. Trigger words: adom-vscode, open in vscode, reveal in explorer, file explorer, sidebar reveal, preview markdown, install extension, search extensions, claude new chat, vscode command, vscode mode, vscode notify."+description: "Control VS Code Server (code-server) from inside the Docker container. THIS is the wrapper for the VS Code FILE EXPLORER sidebar, editor tabs, markdown preview, etc. — when the user says 'reveal in file explorer' or 'open in vscode' they mean this CLI, NOT adom-desktop (which controls Chrome browser windows). Open files, reveal in Explorer sidebar, preview markdown, get/set any VS Code setting LIVE (config, theme, fonts, font sizes — no reload), run container shell commands (exec, streamed), push/pull events on the HD frontend queue, query container identity (hd vs hw), check/inject the Adom api key, list/query/update extensions (incl. Claude/Codex/Kimi), start Claude Code chats, switch UI modes (claudecode, claudetty, tty), show notifications, run any VS Code command. Trigger words: adom-vscode, open in vscode, reveal in explorer, file explorer, sidebar reveal, preview markdown, install extension, update extension, extension version, search extensions, claude new chat, vscode command, vscode mode, vscode notify, vscode setting, change theme, set font, font size, chat font, exec in container, event queue, queue push, queue pull, container type, hd or hw, api key status, refresh api key, port 8821." ---  # adom-vscode — VS Code Control@@ -61,12 +61,12 @@ This applies equally to relative-path Markdown links surfaced in chat absolute paths under `/home/adom/project/...` always click through; relative paths must be relative to that root. -## File operations+## About -CLI + VS Code extension for controlling code-server from Docker processes. The extension runs an HTTP server on port 8821; the CLI wraps those calls with AI-oriented colored output.+CLI + VS Code extension for controlling code-server from Docker processes. The extension runs an HTTP server on port 8821; the CLI wraps those calls with AI-oriented colored output. Everything is also plain HTTP, so scripts and the HD/HW frontend can hit the verbs directly; `GET /health` lists the full verb roster for feature detection.  Binary: `/usr/local/bin/adom-vscode`-Extension port: **8821** (127.0.0.1 only)+Extension port: **8821** (127.0.0.1 only). If 8821 is taken the extension falls back to 8822..8831 (then an ephemeral port) and writes the real port to `~/.local/share/adom-vscode/port.json`. The CLI resolves the port automatically (`ADOM_VSCODE_PORT` env var, then port.json, then 8821); other callers should read that file when 8821 does not answer.  ## File operations ```bash@@ -85,11 +85,61 @@ adom-vscode terminal show|hide|toggle|new  # Terminal adom-vscode activity-bar show|hide|toggle  # Left icon strip ``` +## Settings: config, theme, fonts (all apply LIVE, no reload)++These use the native VS Code API (`ConfigurationTarget.Global`), so changes land immediately and active Claude/AI sessions survive. Prefer these over editing settings.json.++```bash+adom-vscode config get workbench.colorTheme      # Any setting: effective + default/global/workspace layers+adom-vscode config set editor.fontSize 14        # Any setting, live+adom-vscode theme get                            # Active theme + every installed theme+adom-vscode theme set "Adom Dark"                # Switch live+adom-vscode font get                             # All font settings + RESOLVED (truly rendered) families+adom-vscode font set --editor-family "Fira Code" --prose-family Inter+adom-vscode font-size get+adom-vscode font-size set --editor 14 --terminal 13 --prose 15 --prose-code 13+```++Font keys: editor `editor.fontFamily/fontSize`, terminal `terminal.integrated.fontSize`, chat prose `chat.fontFamily/fontSize`, chat code blocks `chat.editor.fontFamily/fontSize`. `font get` reports the resolved family the renderer actually shows (checked via `document.fonts.check` in the workbench); the configured stack often names fonts that aren't installed on the rendering side.++## Exec (run shell commands in the container)+```bash+adom-vscode exec "ls -la" --cwd /home/adom/project   # Streams stdout/stderr live, exits with the command's code+adom-vscode exec "npm test" --timeout 600+adom-vscode exec "uname -a" --json                   # Buffered JSON result instead of streaming+```+Runs `bash -lc` as the workspace user inside the container (native, no wsl.exe). HTTP: `POST /exec` (buffered) or `POST /exec/stream` (SSE).++## Event queue (container process -> HD/HW frontend)++Any process can push events; the frontend pulls when it wants. Examples: a watcher noticing the api key expires soon pushes a login-refresh event; a long job pushes progress for a dialog. Queue survives window reloads.++```bash+adom-vscode queue push login --type refresh-needed --payload '{"expiresInHours":24}'+adom-vscode queue pull --topic login             # Consume matching events+adom-vscode queue pull --peek                    # Read without consuming+adom-vscode queue status                         # Depth + per-topic counts+adom-vscode queue clear --topic progress+```++## Container identity + API key+```bash+adom-vscode container            # kind: hd (local Hydrogen Desktop) or hw (Adom cloud), OS, kernel, carbon URL, proxy URI+adom-vscode apikey status        # /var/run/adom/api-key: exists, size, age, sha256 fingerprint+adom-vscode apikey set --stdin   # Inject a fresh key after a frontend login refresh (also: apikey set <value>)+```+ ## Extensions ```bash-adom-vscode extensions search "python"           # Open Extensions sidebar with search-adom-vscode extensions install ms-python.python   # Install by ID+adom-vscode extensions list                          # Installed extensions + claude/codex/kimi AI summary+adom-vscode extensions list --all                    # Include builtins+adom-vscode extensions status anthropic.claude-code --latest  # Version, running state, pending update+adom-vscode extensions update anthropic.claude-code  # Update one (activates on reload)+adom-vscode extensions update                        # Update all+adom-vscode extensions search "python"               # Open Extensions sidebar with search+adom-vscode extensions install ms-python.python      # Install by ID ```+AI assistant ids: claude `anthropic.claude-code`, codex `openai.chatgpt`, kimi `moonshot-ai.kimi-code`.  ## Claude Code ```bash@@ -122,7 +172,7 @@ adom-vscode notify "Failed" --level error  ## Management ```bash-adom-vscode health              # Check extension is running (shows version + port)+adom-vscode health              # Check extension is running (version + actual port + verb roster) adom-vscode install             # Install everything: extension, skill, completions adom-vscode reload              # Reload VS Code window (warning: kills active Claude Code sessions) ```