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

# adom-vscode — VS Code Control

> **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
> Docker container'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** use the desktop `code` CLI either — it is not on
> PATH in code-server containers (`which code` returns nothing).
> The wrapper that talks to the running code-server's REST API
> on port 8821 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 /
> browser / pup / shotlog tab.

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

Concrete consequences when generating files for the user to review:

| 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/...`. A few good homes:

- `/home/adom/project/<tool>/...` — colocated with the tool the
  artifact relates to (e.g. `chip-fetcher/library/<MPN>/<MPN>-thumb.png`).
- `/home/adom/project/.smoke/<task>/` — temporary smoke outputs the
  user is reviewing; `.smoke/` is gitignored at the repo root.
- `/home/adom/project/.scratch/` — quick throwaway exploration files.

**Symptom to watch for:** if you call `adom-vscode reveal /tmp/...` or
`adom-vscode open /tmp/foo.png` and the user reports "I can't see it"
or "your link doesn't do anything" or "show me the folder," the cause
is almost always workspace scoping. Move the artifact under
`/home/adom/project/`, then re-issue the reveal.

This applies equally to relative-path Markdown links surfaced in chat
(`[label](path)`) — those resolve relative to the workspace root, so
absolute paths under `/home/adom/project/...` always click through;
relative paths must be relative to that root.

## File operations

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.

Binary: `/usr/local/bin/adom-vscode`
Extension port: **8821** (127.0.0.1 only)

## 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
```

## Layout
```bash
adom-vscode sidebar show                 # Guaranteed show
adom-vscode sidebar hide                 # Guaranteed hide
adom-vscode sidebar toggle               # Flip current state
adom-vscode panel show|hide|toggle       # Bottom panel
adom-vscode terminal show|hide|toggle|new  # Terminal
adom-vscode activity-bar show|hide|toggle  # Left icon strip
```

## Extensions
```bash
adom-vscode extensions search "python"           # Open Extensions sidebar with search
adom-vscode extensions install ms-python.python   # Install by ID
```

## Claude Code
```bash
adom-vscode claude new                   # New Claude Code conversation
```

## Modes
Full-screen focused experiences. Use `mode reset` to exit.
```bash
adom-vscode mode claudecode              # Claude Code panel UI (graphical chat)
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, restore default layout
```

## 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              # Check extension is running (shows version + port)
adom-vscode install             # Install everything: extension, skill, completions
adom-vscode reload              # Reload VS Code window (warning: kills active Claude Code sessions)
```

## URL auto-trigger
Add `?mode=X` to the VS Code URL to auto-enter a mode on page load:
- `?mode=claudecode` — Claude Code panel UI
- `?mode=claudetty` — terminal + claude CLI
- `?mode=tty` — blank terminal
- `?mode=tty&cmd=COMMAND` — terminal with auto-command

## Output format
- Success: `OK: <what happened>` (green)
- Failure: `ERROR: <what went wrong>` (red) + `Hint: <next action>` (dim)

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