adom-vscode

@@ -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). START-HERE skill of the adom-vscode pack: file ops, workspace scoping, port discovery, and the map to the sub-skills covering live settings (adom-vscode-settings), container exec (adom-vscode-exec), the frontend event queue (adom-vscode-queue), container identity + api key (adom-vscode-container), extension management (adom-vscode-extensions), and modes/layout (adom-vscode-modes). Trigger words: adom-vscode, open in vscode, reveal in explorer, file explorer, sidebar reveal, preview markdown, vscode command, vscode api, port 8821, code-server control, drive vscode, vscode verbs."+description: "Control VS Code Server (code-server) from inside an Adom workspace (a cloud container, or the Hydrogen workspace machine on Windows/macOS). 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-bridge (which controls Chrome browser windows via pup_*). START-HERE skill of the adom-vscode pack: file ops, workspace scoping, port discovery, and the map to the sub-skills covering live settings (adom-vscode-settings), container exec (adom-vscode-exec), the frontend event queue (adom-vscode-queue), container identity + api key (adom-vscode-container), extension management (adom-vscode-extensions), and modes/layout (adom-vscode-modes). Trigger words: adom-vscode, open in vscode, reveal in explorer, file explorer, sidebar reveal, preview markdown, vscode command, vscode api, port 8821, port 8822, code-server control, drive vscode, vscode verbs." ---  # adom-vscode, VS Code Control (start here)@@ -9,20 +9,21 @@ description: "Control VS Code Server (code-server) from inside the Docker contai > file explorer" / "reveal" / "show me where this file is" / > "click to open in vscode" they almost always mean the > **VS Code Server's sidebar Explorer** (the panel inside this-> Docker container's running VS Code instance). That's THIS+> workspace's running VS Code instance). That's THIS > CLI: `adom-vscode reveal <path>`. >-> **Do NOT** reach for `adom-desktop` for that, `adom-desktop`-> controls puppeteer / Chrome browser windows, not VS Code.+> **Do NOT** reach for `adom-bridge` for that, `adom-bridge`+> (formerly `adom-desktop`) controls puppeteer / Chrome browser+> windows via the `pup_*` verbs, not VS Code. > > **Do NOT** use the desktop `code` CLI either, it is not on-> PATH in code-server containers (`which code` returns nothing).+> PATH in code-server workspaces (`which code` returns nothing). > The wrapper that talks to the running code-server's REST API-> on port 8821 is this binary.+> (port 8821, or whatever `port.json` says) is this binary. > > If the user mentions "vscode", "explorer", or wants to see a > file in the editor, default to `adom-vscode`. Save-> `adom-desktop` for cases where the trigger is clearly Chrome /+> `adom-bridge` for cases where the trigger is clearly Chrome / > browser / pup / shotlog tab.  ## The mental model@@ -45,11 +46,11 @@ Binary: `~/.local/bin/adom-vscode` (also `/usr/local/bin/adom-vscode`). |---|---| | **adom-vscode** (this file) | Mental model, file ops, workspace scoping, port discovery, management | | **adom-vscode-settings** | Get/set ANY setting, theme, fonts, font sizes, all LIVE with no reload; resolved (truly rendered) font families |-| **adom-vscode-exec** | Run shell commands in the container, streamed (SSE) or buffered; the no-wsl.exe rationale |+| **adom-vscode-exec** | Run shell commands in the workspace, streamed (SSE) or buffered; why it beats an out-of-band host spawn | | **adom-vscode-queue** | The container-to-frontend event queue: push/pull/status/clear, topics, TTL, persistence |-| **adom-vscode-container** | Container identity (hd vs hw), api-key status/inject, port discovery details, /health feature detection |-| **adom-vscode-extensions** | List/query/update extensions, incl. the Claude/Codex/Kimi AI assistants |-| **adom-vscode-modes** | Full-screen modes (claudecode/claudetty/tty), layout verbs, URL auto-triggers, paste-screenshot |+| **adom-vscode-container** | Workspace identity (hd = local Hydrogen workspace on Windows/macOS, hw = cloud), api-key status/inject, port discovery details, /health feature detection |+| **adom-vscode-extensions** | List/query/update extensions, the AI assistants (Claude/Codex/Kimi/Antigravity), the AI thread icons, `ai`/`tabs` verbs |+| **adom-vscode-modes** | Full-screen modes (claudecode/claudetty/tty), layout verbs, URL auto-triggers |  ## CRITICAL: workspace scope is `/home/adom/project` 

@@ -1 +1 @@-1.1.92+1.1.93

⋯ 1 unchanged line ⋯

@@ -1,6 +1,6 @@ {   "slug": "adom-vscode",-  "version": "1.1.92",+  "version": "1.1.93",   "type": "app",   "description": "CLI + VS Code extension that lets AI assistants and the Hydrogen Desktop frontend drive VS Code from inside an Adom container: open files, live get/set of any setting/theme/font (no reload), native streamed exec, a frontend event queue, container identity (hd/hw), api-key status/inject, extension query/update, modes, paste screenshots, and any VS Code command via a local HTTP API on port 8821 (with port-file fallback discovery).",   "license": "PROPRIETARY",

@@ -4,7 +4,7 @@   "slug": "adom-vscode",   "title": "adom-vscode",   "brief": "Let Claude, Codex and Kimi drive VS Code inside your Adom container",-  "version": "1.1.92",+  "version": "1.1.93",   "license": "PROPRIETARY",   "visibility": "public",   "hero": {@@ -141,4 +141,4 @@     "adom-vscode-extensions",     "adom-vscode-modes"   ]-}\ No newline at end of file+}

@@ -1,6 +1,6 @@ --- name: adom-vscode-container-description: "Identify the Adom container (hd = local Hydrogen Desktop WSL2 workspace, hw = Adom cloud container), check and inject the Adom api key at /var/run/adom/api-key, discover the extension's real port when 8821 is taken, and feature-detect verbs via GET /health. Trigger words: container type, hd or hw, what kind of container, am I in hydrogen desktop, cloud container, container identity, api key status, is the api key good, refresh api key, inject api key, /var/run/adom/api-key, session key expiring, port discovery, port.json, ADOM_VSCODE_PORT, health verbs, feature detect, carbon url, vscode proxy uri."+description: "Identify the Adom workspace (hd = local Hydrogen workspace — WSL2 on Windows, the systemd-nspawn workspace machine on macOS; hw = Adom cloud container), check and inject the Adom api key at /var/run/adom/api-key, discover the extension's real port when 8821 is taken, and feature-detect verbs via GET /health. Trigger words: container type, hd or hw, what kind of container, am I in hydrogen desktop, cloud container, container identity, api key status, is the api key good, refresh api key, inject api key, /var/run/adom/api-key, session key expiring, port discovery, port.json, ADOM_VSCODE_PORT, health verbs, feature detect, carbon url, vscode proxy uri." ---  Parent skill: **adom-vscode**@@ -15,14 +15,22 @@ adom-vscode container  Returns `kind` plus the raw evidence so callers can gate precisely: -- `kind: "hd"`: local Hydrogen Desktop workspace. Markers: `/etc/profile.d/hd-env.sh`-  exists, or a WSL kernel (`microsoft` in `uname -r`).-- `kind: "hw"`: Adom cloud container. Marker: `VSCODE_PROXY_URI` contains `.adom.cloud`.+- `kind: "hd"`: local Hydrogen workspace — the union of the per-platform markers:+  - **Windows** (WSL2): `/etc/profile.d/hd-env.sh` exists (`markers.hdEnvSh`), or a+    WSL kernel — `microsoft`/`wsl` in `uname -r` (`markers.wslKernel`).+  - **macOS** (Lima VM + systemd-nspawn machine): `/etc/profile.d/hydrogen-env.sh`+    exists (`markers.hydrogenEnvSh`), or `ADOM_HYDROGEN_MACHINE` is set in the+    extension-host env (`markers.hydrogenMachine`). Neither Windows marker is present+    there — the kernel is a plain generic Linux kernel — which is why the machine used+    to report `kind:"unknown"` and refuse exec (fixed 2026-09-17).+- `kind: "hw"`: Adom cloud container. Marker: `VSCODE_PROXY_URI` contains `.adom.cloud`+  (`markers.cloudProxy`). The two macOS markers are ignored when this one is set, so a+  cloud container can never be widened into `hd` by an env var. - `kind: "unknown"`: none of the markers matched (report the markers, don't guess).  Also included: `hostname`, `os` (from /etc/os-release), `kernel`, `arch`, `workspaceUser`, and `env.carbonUrl` (`ADOM_CARBON_URL`), `env.hydrogenUrl`,-`env.vscodeProxyUri`, plus the `markers` object itself and `execAllowed` (whether the exec verbs are enabled here; they are HD-local only). HTTP: `GET /container`.+`env.vscodeProxyUri`, plus `env.hydrogenMachine` (`ADOM_HYDROGEN_MACHINE`), the `markers` object itself and `execAllowed` (whether the exec verbs are enabled here; they are local-workspace only, `kind:hd`). HTTP: `GET /container`.  ## API key (/var/run/adom/api-key) @@ -59,6 +67,11 @@ ephemeral port, and writes the truth to:  - The CLI resolves automatically: `ADOM_VSCODE_PORT` env var > port.json > 8821. - External services expecting 8821 should read port.json when 8821 refuses.+- This is not hypothetical: on the macOS workspace machine the live extension has been+  on **8822** (`preferredPort: 8821`) since a detached host took 8821. Read `port.json`;+  never hard-code 8821. Anything that silences or forwards the port (a+  `remote.portsAttributes` entry, a port-hint registration) must cover the whole+  8821-8831 fallback range, not just 8821. - The extension also drops an `adom-ports claim` breadcrumb when that CLI exists.  ## Feature detection

@@ -1,27 +1,33 @@ --- name: adom-vscode-exec-description: "Run shell commands inside the Adom container through the adom-vscode extension, streamed live (SSE) or buffered, as the workspace user via a login shell. HD-LOCAL ONLY: cloud (hw) containers refuse exec (exec_disabled_on_cloud), check /health verbs first. THE native replacement for routing container commands through host-side wsl.exe (which wedges, serializes behind a global lock, and flakes with E_UNEXPECTED). Trigger words: exec disabled, exec_disabled_on_cloud, exec in container, run command in container, adom-vscode exec, stream exec, streamed output, exec stream, container shell, run npm test in container, long running command, exec timeout, exec cwd, no wsl.exe, wsl exec replacement, POST /exec, SSE exec."+description: "Run shell commands inside the Adom container through the adom-vscode extension, streamed live (SSE) or buffered, as the workspace user via a login shell. LOCAL-WORKSPACE ONLY (kind:hd — WSL2 on Windows, the Hydrogen workspace machine on macOS): cloud (hw) containers refuse exec (exec_disabled_on_cloud), check /health verbs first. THE native replacement for routing workspace commands through an out-of-band host spawn (wsl.exe on Windows, limactl/nsenter on macOS). Trigger words: exec disabled, exec_disabled_on_cloud, exec in container, run command in container, adom-vscode exec, stream exec, streamed output, exec stream, container shell, run npm test in container, long running command, exec timeout, exec cwd, no wsl.exe, wsl exec replacement, POST /exec, SSE exec." ---  Parent skill: **adom-vscode**  # adom-vscode-exec, run container commands natively -> **HD-LOCAL ONLY (security policy).** exec runs only on local Hydrogen Desktop-> workspaces (`container` reports `kind: hd`). Cloud (hw) containers refuse both-> exec verbs with `errorCode: exec_disabled_on_cloud` (HTTP 403), and /health-> omits `exec` / `exec.stream` from its verb roster there, so feature-detect-> before offering exec. Rationale: adom-vscode is a core install for every Adom-> user, and an arbitrary-shell verb on an internet-facing cloud container is an-> unnecessary exposure; HD workspaces sit behind the user's own firewall. On a-> cloud container, run commands in your own terminal/session instead. Debug-> escape hatch: `ADOM_VSCODE_ALLOW_EXEC=1` set in the EXTENSION HOST env by the-> platform (a remote caller cannot set it).+> **LOCAL-WORKSPACE ONLY (security policy).** exec runs only where `container`+> reports `kind: hd` — the WSL2 workspace on **Windows** and the systemd-nspawn+> workspace machine on **macOS**. Cloud (hw) containers refuse both exec verbs+> with `errorCode: exec_disabled_on_cloud` (HTTP 403), and /health omits `exec` /+> `exec.stream` from its verb roster there, so feature-detect before offering+> exec. Rationale: adom-vscode is a core install for every Adom user, and an+> arbitrary-shell verb on an internet-facing cloud container is an unnecessary+> exposure; local workspaces sit behind the user's own firewall. On a cloud+> container, run commands in your own terminal/session instead. Debug escape+> hatch: `ADOM_VSCODE_ALLOW_EXEC=1` set in the EXTENSION HOST env by the platform+> (a remote caller cannot set it).+>+> The 403 body carries its own `error`, `kind` and `hint` — read those. It does+> NOT mean the extension is missing, so do not answer a 403 by reinstalling and+> reloading the window (that kills live AI sessions and cannot fix a policy gate).  Commands run as the workspace user (`adom`) via `bash -lc` inside the container, spawned by the extension host itself. LOGIN shell matters: tools like-adom-desktop need the workspace env from `/etc/profile.d/`, and a bare `-c`-shell runs them env-less (they fail with nothing on stdout).+adom-bridge need the workspace env from `/etc/profile.d/` (`hd-env.sh` on+Windows, `hydrogen-env.sh` on macOS), and a bare `-c` shell runs them env-less+(they fail with nothing on stdout).  ## CLI @@ -49,14 +55,22 @@ adom-vscode exec "uname -a" --json                   # buffered: waits, prints o   then `exit {exitCode, timedOut}`. Closing the connection kills the child, so   a frontend that navigates away does not leak processes. -## Why not wsl.exe (the HD context)+## Why not an out-of-band host spawn -HD's legacy path spawned `wsl.exe -d Adom-Workspace -u adom -- bash -lc <cmd>`-on the Windows host behind a global serial lock. That path caused nearly every-"wsl.exe is flaky / it wedged" incident: E_UNEXPECTED, management-plane wedges,-and everything queued behind one lock, with no VS Code API access. Once the-editor is up, prefer :8821 exec for EVERYTHING; keep wsl.exe only for the-bootstrap phase (distro import, code-server start) before this API exists.+**Windows:** Hydrogen's legacy path spawned `wsl.exe -d Adom-Workspace -u adom --+bash -lc <cmd>` on the Windows host behind a global serial lock. That path caused+nearly every "wsl.exe is flaky / it wedged" incident: E_UNEXPECTED,+management-plane wedges, and everything queued behind one lock, with no VS Code+API access.++**macOS:** the equivalent is `limactl shell` / `nsenter` into the nspawn machine,+or Hydrogen control's `POST 127.0.0.1:47084/workspace/exec` — same story: another+process boundary, no VS Code API, and a per-call setup cost.++Either way: once the editor is up, prefer extension exec for EVERYTHING (on the+extension's real port — see `port.json`, not a hard-coded 8821). Keep the host+spawn only for the bootstrap phase (machine import, code-server start) before+this API exists.  ## Gotchas 

@@ -19,8 +19,10 @@ adom-vscode extensions status anthropic.claude-code --latest   # + gallery check - `list` returns `{count, ai, extensions}`. Each entry: `{id, displayName,   version, active, builtin, path}`. `active` is whether the extension host has   activated it (running), not merely installed.-- The `ai` object maps the three assistants directly, `null` when absent:-  claude `anthropic.claude-code`, codex `openai.chatgpt`, kimi `moonshot-ai.kimi-code`.+- The `ai` object maps the AI assistants directly, `null` when absent: claude+  `anthropic.claude-code`, codex `openai.chatgpt`, kimi `moonshot-ai.kimi-code`,+  antigravity `google.google-antigravity`. `GET /ai/providers` is the authoritative+  list (it also reports each provider's command, surfaces and CLI). - `--latest` queries the Open VSX gallery (code-server's registry) and returns   `latestVersion` + `updateAvailable`. Best-effort with a 3s cap: `latestVersion:   null` means the gallery was unreachable or the extension is not published

@@ -1,6 +1,6 @@ --- name: adom-vscode-modes-description: "Full-screen VS Code modes (claudecode = Claude panel UI, claudetty = terminal + claude CLI, tty = generic terminal with optional auto-command), layout control (sidebar, bottom panel, terminal, activity bar), URL auto-triggers (?mode=...), Claude Code chat verbs, and the Ctrl+V paste-screenshot interceptor. Trigger words: claude code mode, claudecode, claudetty, tty mode, full screen terminal, mode reset, vscode mode, toggle sidebar, toggle panel, new terminal, activity bar, hide sidebar, show terminal, new claude chat, claude context viewer, paste screenshot, ctrl+v image, mode url, ?mode=claudecode, onboarding link."+description: "Full-screen VS Code modes (claudecode = Claude panel UI, claudetty = terminal + claude CLI, tty = generic terminal with optional auto-command), layout control (sidebar, bottom panel, terminal, activity bar), URL auto-triggers (?mode=...), and Claude Code chat verbs. Trigger words: claude code mode, claudecode, claudetty, tty mode, full screen terminal, mode reset, vscode mode, toggle sidebar, toggle panel, new terminal, activity bar, hide sidebar, show terminal, new claude chat, claude context viewer, mode url, ?mode=claudecode, onboarding link." ---  Parent skill: **adom-vscode**@@ -27,7 +27,9 @@ onboarding links:  - `?mode=claudecode`, `?mode=claudetty`, `?mode=tty`, `?mode=tty&cmd=echo%20hello` -Example: `https://<slug>.adom.cloud/?mode=claudecode&folder=/home/adom/project`+Examples:+- Cloud: `https://<slug>.adom.cloud/?mode=claudecode&folder=/home/adom/project`+- Hydrogen workspace (Windows/macOS), where code-server is served locally: `http://127.0.0.1:7380/?mode=claudecode&folder=/home/adom/project`  ## Layout @@ -71,13 +73,13 @@ echoed launch line, tab closes on exit; marker terminal.tui.shell); command types into an interactive shell and stays echoed at the top, `GET /terminal/tui/list`, `POST /terminal/tui/dispose {id?|name?}`. -## Paste-screenshot interceptor+## Paste-screenshot interceptor — REMOVED (2026-09-03) -Ctrl+V with an image on the clipboard, while focused in a code-server terminal,-uploads the image to `POST /paste-screenshot`; it lands in `/tmp/shots/`-(sha256-deduplicated, pruned after 20 files / 1 hour) and the file path is-typed into the terminal so a CLI Claude session can read it. Without this,-code-server's clipboard.readText() returns empty for image-only clipboards.+Gone: the Claude CLI handles image paste itself, so there is no+`POST /paste-screenshot` route and nothing writes to `/tmp/shots/`. `adom-vscode+install` only *strips* the old injected block from `workbench.html` on machines+that were patched before. Do not tell a user to Ctrl+V an image into a terminal+expecting a file path; hand the CLI the path directly.  ## Gotchas 

@@ -11,7 +11,9 @@ Every verb here applies through `vscode.workspace.getConfiguration().update(key, value, ConfigurationTarget.Global)`, which lands **immediately**: no window reload, no settings.json file merge, and active Claude Code sessions survive. Prefer these over editing `~/.local/share/code-server/User/settings.json` by-hand, and NEVER route a settings change through host-side wsl.exe.+hand, and NEVER route a settings change through an out-of-band host spawn+(`wsl.exe` on Windows, `limactl`/`nsenter` or `POST 127.0.0.1:47084/workspace/exec`+on macOS).  ## Any setting @@ -27,7 +29,13 @@ HTTP: `GET /config?key=<dotted.key>`, `POST /config {key, value}`.  ```bash adom-vscode theme get                 # active + preferredDark/preferredLight + EVERY installed theme-adom-vscode theme set "Adom Dark"     # switches live+adom-vscode theme set "Adom Studio Dark"   # switches live. Installed Adom labels:+                                           # Adom Studio, Adom Studio Dark,+                                           # Adom Studio Dark (Brighter Text),+                                           # Adom Kickstand, Adom Slate.+                                           # An unknown label answers known:false and+                                           # leaves the editor on the default (white) theme —+                                           # always read `theme get` for the real list first. ```  `theme get` enumerates every theme contributed by installed extensions@@ -75,7 +83,7 @@ values are returned; the check works again once the Adom sidebar has been opened ## Gotchas  - Font/theme changes by these verbs need NO reload. If a user reports a settings-  change "didn't apply", suspect the old wsl.exe/settings.json path or a wrong+  change "didn't apply", suspect the old host-spawn/settings.json path or a wrong   key name, not these verbs. - `config set` writes the Global (User) layer. A workspace-layer override   (`.vscode/settings.json`) still wins; `config get` shows all layers so you can