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

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

![adom-vscode panel — activity bar sidebar with Overview, Modes, Commands, AI Prompts, and the Claude Context viewer listing live sessions](screenshots/panel.png)

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

![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)

## 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
- **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)
- **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`"*  ·  *"switch to Claude Code mode"*  ·  *"reveal the molecules folder"*

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

## Quick start

```bash
adom-vscode health                        # Check extension is running
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
```

## Modes

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

```bash
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.

| URL param | Mode |
|-----------|------|
| `?mode=claudecode` | Claude Code panel UI |
| `?mode=claudetty` | Full-screen terminal + claude CLI |
| `?mode=tty` | Blank full-screen terminal |
| `?mode=tty&cmd=echo%20hello` | TTY with auto-command |

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.

## 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
adom-vscode open /foo/bar.png
    ↓  HTTP POST to localhost:8821
Adom VS Code Extension (inside code-server)
    ↓  vscode.* API
VS Code UI
```

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