adom-vscode

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

The Extension: About page

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.

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
• 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 (HD-local only): run shell commands in the container as the workspace user, streamed (SSE) or buffered, no host-side wsl.exe needed. Disabled on cloud (hw) containers by security policy
• 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)
  • claudetty: full-screen terminal running the claude CLI
  • 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)
• 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"  ·  "set my editor font size to 14"  ·  "switch to Claude Code mode"  ·  "is my api key still good?"

To upgrade after a new release lands on the wiki, ask Claude:

"update adom-vscode"

Or run it yourself: adom-wiki pkg update adom-vscode.

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.

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

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

# 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

Modes take over VS Code's full screen for a focused experience. Use mode reset to return to normal.

adom-vscode mode claudecode               # Claude Code panel UI
adom-vscode mode claudetty                # Full-screen terminal + claude CLI
adom-vscode mode tty                      # Blank full-screen terminal
adom-vscode mode tty -c "echo hello" -n "Demo"  # TTY with auto-command
adom-vscode mode reset                    # Exit any mode

URL auto-trigger

Add ?mode=X to any VS Code URL to auto-enter a mode on page load. Perfect for sharing onboarding links with new users.

Example: https://<slug>.adom.cloud/?mode=claudecode&folder=/home/adom/project

Paste-screenshot interceptor

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.

The skill pack

The page ships a parent skill plus six sub-skills so any AI in the Adom ecosystem can discover and drive every verb. adom-wiki pkg install (and adom-vscode install) deploys all of them to ~/.claude/skills/:

Architecture

Claude Code / scripts / HD frontend
    ↓  runs CLI or hits HTTP directly
adom-vscode open /foo/bar.png
    ↓  HTTP POST to localhost:8821 (see Port discovery)
Adom VS Code Extension (inside code-server)
    ↓  vscode.* API / child_process
VS Code UI + container shell

See ARCHITECTURE.md for the full design document. See COMMANDS.md for all VS Code commands usable with adom-vscode command <id>.

Version

One version number everywhere: the VERSION file, the extension, the CLI --version, and the wiki package all carry the same value (1.1.10 as of this release).

v1.1.10 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.

v1.1.11 added: the skill pack (parent + 6 sub-skills) installed by both the wiki package and adom-vscode install.

v1.1.12: exec verbs are HD-local only (disabled on cloud hw containers with errorCode exec_disabled_on_cloud); /health reports execAllowed and omits exec verbs where disabled.

v1.1.13: extension-dir GC on every install (prunes stale version dirs VS Code's startup GC never reaps on long-lived windows; keeps current, live-process, and running-server versions), and install now pushes a system/update-pending queue event so the frontend can reload at a safe moment.

v1.1.15: version realignment (1.1.14 shipped a dependency-only bump with a 1.1.13 binary; now tarball, binary, VERSION and page all match) and the issue #642 fix: extensions --latest is platform-scoped via the VS Code-compat gallery, returns the allPlatforms matrix with an explanatory _hint, accepts --platform, and extensions update says 'already current' instead of firing a no-op install. \nv1.1.16: extensions install --vsix <path|url> installs a VSIX directly via code-server's CLI with the extension-host env stripped (absorbs the CODE_SERVER_PARENT_PID / not-spawned-with-IPC trap from issue #642).

v1.1.17: named TUI terminals as editor tabs with real handles (POST /terminal/tui, /terminal/tui/dispose, GET /terminal/tui/list; CLI terminal tui / tui-list / tui-dispose), built for the Hydrogen AI Threads panel; /command now passes a non-array args value as a single argument instead of silently dropping it, and reports argsShape.

v1.1.18: terminal.tui accepts optional icon (codicon name -> ThemeIcon) and color (theme color id -> ThemeColor) so AI TUI tabs match the AI Threads panel identities; tui-list echoes them; /health roster gains the terminal.tui.icon capability marker.

v1.1.19: terminal.tui accepts shellPath/shellArgs/env (createTerminal semantics): the CLI runs AS the terminal process, no shell underneath, no echoed launch line pinned atop the TUI, no quoting constraints, and the tab closes when the process exits. shellPath wins over command; a missing or non-executable shellPath fails explicitly (errorCode shell_path_not_executable) instead of falling back to a bare prompt. Capability marker terminal.tui.shell in the /health roster.

v1.1.20: /command returns errorCode command_not_found (HTTP 400) with did-you-mean suggestions when a command id is unknown (args-taking commands often use the bare id, e.g. moveActiveEditor); terminal.tui injects ADOM_VSCODE_TUI_ID into the terminal env and tui-list reports processId, giving callers a DOM-free identity chain (pid -> /proc environ -> registry id).

v1.1.21: event-driven tab census + Claude session identity (John 2026-09-03: never poll the iframes again). GET /tabs and the SSE stream GET /tabs/events publish the extension host's own tabGroups census on every change; POST /claude/session-start ingests the Claude SessionStart hook (id + transcript path, before the jsonl is flushed) and GET /claude/sessions lists it; POST /claude/open-session opens an existing conversation by id and confirms the bind (retagging sdk-cli transcripts, which the Claude extension otherwise declines). Capability markers in /health: tabs.list, tabs.events, claude.open-session, claude.session-start, claude.sessions.

v1.1.22: /command maps a JSON null argument to undefined when spreading an args array (JSON has no undefined; the Claude extension's editor.open crashes on a literal null session id, which broke every send-to-AI new tab).

v1.1.23: the paste-screenshot interceptor is retired (the Claude CLI handles image paste itself). It was the only thing this tool wrote into code-server's workbench.html, and that write was the only reason it ever needed sudo, so installs are now entirely user-level and a code-server upgrade can no longer wipe a patch of ours. An already-injected block is stripped on the next install. The /paste-screenshot endpoint goes with it.