adom-vscode open /path/to/file.png       # Open any 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 command workbench.action.reloadWindow
adom-vscode command workbench.action.toggleSidebarVisibility

adom-vscode notify "Build complete" --level info
adom-vscode notify "Check this" --level warning
adom-vscode notify "Failed" --level error

adom-vscode health              # Version + actual port + full verb roster
adom-vscode install             # Install everything: extension, skills, completions
adom-vscode reload              # Reload VS Code window (warning: kills active Claude Code sessions)

adom-vscode install
adom-vscode reload

---
name: adom-vscode
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). 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."
---
> **macOS line.** This is `adom/adom-vscode-macos` (repo adom-inc/adom-vscode-macos), the build Hydrogen installs on a Mac: native arm64 for the Hydrogen workspace machine, same extension id, CLI and `:8821` API as `adom/adom-vscode`, **without the AI title bar** (Hydrogen's agent bar and AI accounts popup own the editor title bar there). Windows and cloud containers keep `adom/adom-vscode`. Upstream changes are merged in; the delta is `cli/src/main.rs` (no title-bar injection, strips upstream's, writes `~/.local/share/adom-vscode/flavor`) and `page-macos/`.



# adom-vscode, VS Code Control (start here)

> **Disambiguation, read first.** When the user says "open in
> 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
> workspace's running VS Code instance). That's THIS
> CLI: `adom-vscode reveal <path>`.
>
> **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 workspaces (`which code` returns nothing).
> The wrapper that talks to the running code-server's REST API
> (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-bridge` for cases where the trigger is clearly Chrome /
> browser / pup / shotlog tab.

## The mental model

A VS Code extension inside code-server runs an HTTP server on **127.0.0.1:8821**;
the `adom-vscode` CLI wraps those verbs with AI-oriented colored output. Everything
is plain HTTP too, so scripts and the HD/HW frontend hit the API directly.
`GET /health` returns the full verb roster (`verbs: [...]`) for feature detection.

If 8821 is taken the extension falls back to 8822..8831 (then an ephemeral port)
and writes the truth to `~/.local/share/adom-vscode/port.json`. The CLI resolves
the port automatically (`ADOM_VSCODE_PORT` env var, then port.json, then 8821);
any other caller should read that file when 8821 does not answer.

Binary: `~/.local/bin/adom-vscode` (also `/usr/local/bin/adom-vscode`).

## Skill map, the pack

| Skill | Read it for |
|---|---|
| **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 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** | 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 |

## CRITICAL: workspace scope is `/home/adom/project`

The Hydrogen panel boots code-server with `?folder=/home/adom/project`.
That is the workspace root, **VS Code can only see and operate on
paths inside that folder.** Anything outside it is invisible to the
Explorer sidebar and to most workspace-aware commands.

| Action                              | Outside `/home/adom/project` | Inside it |
|-------------------------------------|------------------------------|-----------|
| `adom-vscode open <file>`           | Opens a loose tab (no Explorer link); the CLI returns `OK` because `vscode.open` accepts any path, but the user can't navigate to it | Works fully, tab opens AND the Explorer entry is highlightable |
| `adom-vscode reveal <path>`         | Silently no-op; the extension's `revealInExplorer` accepts the call but the workspace doesn't contain the path so nothing visible happens. The CLI still returns `OK`. | Works, sidebar scrolls and selects the entry |
| `adom-vscode preview <file.md>`     | Loose preview tab with no nav back to the source | Full preview + Explorer integration |

**Rule for AI-generated artifacts (thumbnails, dumps, smoke outputs,
intermediate files the user is going to look at):** put them inside
`/home/adom/project/...`, not in `/tmp/...`. Good homes:

- `/home/adom/project/<tool>/...`: colocated with the tool the artifact relates to.
- `/home/adom/project/.smoke/<task>/`: temporary smoke outputs; `.smoke/` is gitignored.
- `/home/adom/project/.scratch/`: quick throwaway exploration files.

**Symptom to watch for:** if you call `adom-vscode reveal /tmp/...` and the user
reports "I can't see it" or "your link doesn't do anything," the cause is almost
always workspace scoping. Move the artifact under `/home/adom/project/`, then
re-issue the reveal. Relative-path Markdown links in chat resolve against the
workspace root too; absolute `/home/adom/project/...` paths always click through.

## File operations
```bash
adom-vscode open /path/to/file.png       # Open any file in VS Code tab
adom-vscode reveal /path/to/folder/      # Reveal in Explorer sidebar
adom-vscode preview /path/to/README.md   # Markdown preview
```

## Generic command (escape hatch)
```bash
adom-vscode command workbench.action.reloadWindow
adom-vscode command workbench.action.toggleSidebarVisibility
```
For the full VS Code command reference, read `COMMANDS.md` in the adom-vscode repo.

## Notifications
```bash
adom-vscode notify "Build complete" --level info
adom-vscode notify "Check this" --level warning
adom-vscode notify "Failed" --level error
```

## Management
```bash
adom-vscode health              # Version + actual port + full verb roster
adom-vscode install             # Install everything: extension, skills, completions
adom-vscode reload              # Reload VS Code window (warning: kills active Claude Code sessions)
```

## Output format
- Success: `OK: <what happened>` (green)
- Failure: `ERROR: <what went wrong>` (red) + `Hint: <next action>` (dim)
- Query verbs (`config get`, `theme get`, `font get`, `container`, `apikey status`,
  `queue pull/status`, `extensions list/status`) print pretty JSON.

## If extension not running
```bash
adom-vscode install
adom-vscode reload
```