launch

# Code OSS Dev - Launch + Debug You're working on VS Code itself and you want to: 1. Launch a Code OSS build from sources that is **already signed in** (Copilot, GitHub, etc.) so chat / agent flows work end-to-end. 2. Drive it with `@playwright/cli` over CDP (UI automation). 3. Optionally attach a debugger via **dap-cli** to set breakpoints in the renderer, extension host, or main process. 4. Run multiple instances at once without port conflicts. This skill provides a launcher that clones an authenticated user-data-dir to a throwaway temp folder, picks free ports for every debug surface, and prints them as JSON so you can pick them up programmatically. The clone is **slim**: workspace storage, browser caches, file history, cached VSIX backups, and old logs are excluded by default. On macOS, auth tokens live in the OS keychain plus small files inside `User/globalStorage` - both of which *are* preserved. On Windows the GitHub session lives in the **shared-data-dir** instead, which the launcher seeds separately (see [Windows authentication](#windows-authentication)). ## Prerequisites - macOS, Linux, or Windows. - **macOS / Linux**: the launcher is a bash script (`scripts/launch.sh`) and depends on `rsync`, `nohup`, and Node on `PATH`. The example caller snippets below also use `jq` (parse the JSON output) and `lsof` (kill-by-port fallback) — install those if you plan to use them, but the launcher itself does not require them. - **Windows**: use `scripts\launch.ps1` instead. It needs no extra tooling beyond Node on `PATH`, and works on both Windows PowerShell 5.1 and PowerShell 7+. `jq` is not needed — parse the JSON with `ConvertFrom-Json`. If Node is managed with [fnm](https://github.com/Schniz/fnm), put it on `PATH` first: ```powershell fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression fnm use # picks up the repo's .nvmrc ``` - A VS Code checkout with `node_modules/` installed (`npm install` if missing — do **not** symlink from a sibling worktree; that breaks builds in subtle ways). - A VS Code checkout with sources built. Run `npm run compile` once (one-shot) or `npm run watch` for incremental rebuilds. Both build the full client **and** all built-in extensions under `extensions/`. You must build the full product to run successfully, building just the client is not enough. - An **authenticated** Code OSS profile to seed from. By default the launcher uses `~/.vscode-oss-dev` on macOS/Linux or `$env:USERPROFILE\.vscode-oss-dev` on Windows, which is the user-data-dir the repo's `launch.json` configs use - if the user has ever signed in to Copilot in a dev build, this should work. Only pass `--source-user-data-dir <path>` (or set `$CODE_OSS_DEV_AUTHED_USER_DATA_DIR`) when you specifically want to seed from a different profile (e.g. your regular `~/Library/Application Support/Code` install). - If Code OSS launches and needs a sign-in, don't give up! Use the questions tool to ask the user to sign in. - `@playwright/cli` available (it's a devDependency in the vscode repo - `npm install` then use `npx @playwright/cli`). - For debugger work: `dap-cli` on `PATH`. If debugger support would be useful but the `dap-cli` skill is not present, prompt the user to install it from https://github.com/roblourens/dap-cli. - CSS selectors are internal implementation details. If a selector-based `eval` stops working, take a fresh `snapshot`, inspect the current DOM, and update the selector rather than assuming an old one still applies. > The launcher **copies** the source profile to a temp dir and never mutates the original. Each launch gets its own isolated `--user-data-dir` and `--extensions-dir`. > The launcher always sets `files.simpleDialog.enable: true` in the launched profile's `User/settings.json`. This is required for automation: VS Code's native OS file dialogs cannot be driven via `@playwright/cli` over CDP and are completely unreachable over SSH on headless macOS. The simple (quick-input) dialog can be navigated with `press` and clipboard paste. The override is per-launch and only affects throwaway profiles. > Before launching from an agent session, call `get_current_session` and pass its `title` as `--session-title`. For a regular editor window, the launcher writes that title into the throwaway profile's `window.title` setting. For an Agents window, it passes the title to the Command Center. This never modifies the source profile. > For unattended automation, pass `--disable-workspace-trust` so a trust dialog cannot block the flow or extension-host startup. The override is process-scoped and does not modify the source profile. Only use it with content you trust. ## Launch The launcher script lives next to this SKILL.md at `scripts/launch.sh` (macOS/Linux) or `scripts\launch.ps1` (Windows). Resolve it relative to wherever this skill file is installed - do not hardcode an absolute path. ```bash # LAUNCH=<dir-of-this-SKILL.md>/scripts/launch.sh SESSION_TITLE=<title-from-get_current_session> "$LAUNCH" --session-title "$SESSION_TITLE" # default: workbench "$LAUNCH" --agents --session-title "$SESSION_TITLE" "$LAUNCH" -- <workspace-path> # forward extra args to code.sh "$LAUNCH" --source-user-data-dir <path> # pick a specific authed profile "$LAUNCH" --repo <vscode-repo-root> # if not run from the repo "$LAUNCH" --clone-extensions # start with a copy of the source extensions/ (~few seconds) "$LAUNCH" --full # skip slim excludes; copy everything "$LAUNCH" --skip-prelaunch # reuse already-current build outputs "$LAUNCH" --disable-workspace-trust # avoid trust prompts for trusted automation inputs ``` On Windows, invoke the PowerShell launcher with the same flags: ```powershell $skillDir = '<dir-of-this-SKILL.md>' $launch = Join-Path $skillDir 'scripts\launch.ps1' $sessionTitle = '<title-from-get_current_session>' & $launch --session-title $sessionTitle # default: workbench & $launch --agents --session-title $sessionTitle & $launch -- --use-mock-keychain # forward extra args to code.bat & $launch --source-user-data-dir C:\path\to\profile & $launch --repo C:\path\to\vscode & $launch --clone-extensions & $launch --full & $launch --skip-prelaunch & $launch --disable-workspace-trust ``` If the local execution policy blocks scripts, invoke it with `powershell -ExecutionPolicy Bypass -File <path-to-launch.ps1>`. The Windows implementation has the same profile isolation, slim-copy excludes, settings merge, port allocation, foreground pre-launch, and CDP-ready contract as the bash launcher; only the shell commands and path syntax differ. ### What gets copied (slim mode, the default) The exclude list mirrors the one used by VS Code's own perf-test skill (`.github/skills/auto-perf-optimize`), which is known to keep Copilot auth and language-model availability working. Specifically `WebStorage/`, `Service Worker/`, `Local Storage/`, `Cookies`, `Network Persistent State`, `TransportSecurity`, `Trust Tokens`, `Preferences`, `machineid`, and the entire `User/globalStorage/` (which holds `state.vscdb`) are all preserved. #### Windows authentication Windows has no shared per-app keychain for these secrets, so they live in files on disk - but **not all in the user-data-dir**. The GitHub session is stored at `StorageScope.APPLICATION_SHARED` *only on Windows* (see `useSharedStorage` and `CROSS_APP_SHARED_SECRET_KEYS` in `src/vs/platform/secrets/common/secrets.ts`), which puts the two halves of the credential in **different directories**: | Piece | Location | |---|---| | Encrypted GitHub session blob | `<shared-data-dir>/sharedStorage/state.vscdb` | | DPAPI-wrapped decryption key (`os_crypt.encrypted_key`) | `<user-data-dir>/Local State` | The launcher therefore seeds **both**: it copies the source profile *and* copies the source shared-data-dir into the run's throwaway `shared-data` dir. The source resolves the same way `IEnvironmentService.appSharedDataHome` does - `$env:CODE_OSS_DEV_AUTHED_SHARED_DATA_DIR` if set, else `$env:VSCODE_PORTABLE\shared-data` when running portable, else `~/<product.sharedDataFolderName>` (i.e. `%USERPROFILE%\.vscode-oss-shared`). It also verifies `Local State`, `machineid`, and `Network` survived the profile copy, and warns on stderr if neither database holds a GitHub session. > This asymmetry is invisible on macOS/Linux, where the same token lands inside the profile. A Windows-only "always signed out" symptom is a shared-data-dir problem, **not** a profile problem: signing in against the source profile writes a perfectly good session, but before this seeding existed every launch handed Code OSS an empty shared dir and threw it away. To (re)establish the source session: run `.\scripts\code.bat --user-data-dir=$env:USERPROFILE\.vscode-oss-dev` directly, sign in once, and close it. That writes the blob to `%USERPROFILE%\.vscode-oss-shared` and the key to the profile's `Local State`; later launches copy both and inherit the session. > Profiles that predate the `APPLICATION_SHARED` migration can still hold the secret in `User/globalStorage/state.vscdb`. `ApplicationSharedStorageMain` registers application storage as a read fallback, so those profiles authenticate even with no shared-data-dir present - which is why a missing shared dir is reported as a fact rather than assumed fatal. Excluded (transient, regenerable, or known-not-needed): - `User/workspaceStorage/` - per-workspace state, **including stored chat sessions** (often multi-GB) - `User/History/` - local file edit history - `CachedExtensionVSIXs` - backup VSIXs (hundreds of MB) - `logs` - Chromium caches at the profile root: `Cache`, `Code Cache`, `CachedData`, `GPUCache`, `ShaderCache`, `Dawn*Cache`, `component_crx_cache`; and under the persistent integrated-browser partition: `Cache`, `Code Cache`, `GPUCache`, `Dawn*Cache` - `Backups`, `blob_storage`, `BrowserMetrics`, `Crashpad`, `Session Storage` - `Singleton*`, `*.lock`, `*.sock` (would conflict with the source instance) The persistent integrated-browser partition keeps website state such as cookies, local and session storage, IndexedDB, WebStorage, service workers, and preferences; only its regenerable caches are excluded. `extensions/` defaults to a **fresh empty directory** - fastest and conflict-free, but the launched instance starts with no third-party extensions installed. Pass `--clone-extensions` to copy the source extensions dir into the temp profile so the new instance is independent of the source. Pass `--full` to skip all excludes if you suspect the slim copy is missing something you need. > **Why never share the source `extensions/` dir directly?** The extension management service writes a shared `.obsolete` file; two concurrent writers crash each other's shared background process. The launcher always uses an isolated extensions dir for the same reason it uses `--shared-data-dir` (see below). > If the launched window says "language model unavailable" or otherwise looks unauthed, ask the user to sign in. The script runs pre-launch (electron download, compile-if-missing, built-in extensions) **in the foreground**, then starts Code OSS detached and **blocks until the renderer's CDP endpoint is responding** (up to ~90s) before printing the JSON line on stdout. If anything fails — preLaunch errors, code.sh exits early, CDP never opens — the script exits non-zero and dumps the relevant log tail to stderr. For repeated launches of the same prepared build, pass `--skip-prelaunch` after one successful normal launch. Only use it while a watch task keeps all output current or neither sources nor build outputs have changed; otherwise the new instance may run stale or incomplete code. ```json {"pid":12345,"cdpPort":53111,"extHostPort":53112,"mainPort":53113,"agentHostPort":53114,"userDataDir":".../user-data","extensionsDir":".../extensions","sharedDataDir":".../shared-data","runDir":"...","logFile":".../code.log","repo":"...","agents":false,"timings":{"profileMs":231,"preLaunchMs":251,"cdpReadyMs":459,"totalMs":941}} ``` The additive `timings` object uses monotonic elapsed time to identify time spent preparing the isolated profile, running pre-launch, and starting Code OSS through CDP readiness. `totalMs` covers the complete launcher operation through readiness. Capture it with `jq` — no retry loop needed, CDP is already up when the JSON is printed: ```bash INFO=$("$LAUNCH" | tail -n1) CDP=$(jq -r .cdpPort <<<"$INFO") EXT=$(jq -r .extHostPort <<<"$INFO") MAIN=$(jq -r .mainPort <<<"$INFO") AGENT=$(jq -r .agentHostPort <<<"$INFO") LOG=$(jq -r .logFile <<<"$INFO") PID=$(jq -r .pid <<<"$INFO") ``` On Windows, capture and parse the JSON without `jq`: ```powershell $info = & $launch | Select-Object -Last 1 | ConvertFrom-Json $cdp = $info.cdpPort $ext = $info.extHostPort $main = $info.mainPort $agent = $info.agentHostPort $log = $info.logFile $pid = $info.pid ``` ### What each port is for | Port | Process | Use with | |------|---------|----------| | `cdpPort` (`--remote-debugging-port`) | Renderer (the workbench window) | `@playwright/cli` over CDP, also Chrome DevTools | | `extHostPort` (`--inspect-extensions`) | Extension host (Node) | `dap-cli` (Node inspector protocol) | | `mainPort` (`--inspect`) | Electron main process (Node) | `dap-cli` (Node inspector protocol) | | `agentHostPort` (`--inspect-agenthost`) | Agent host process (Node) | `dap-cli` (Node inspector protocol) | ## Drive the UI with @playwright/cli Use the dynamic `cdpPort` from the launch JSON. The normal loop is: attach, confirm the target, snapshot, interact, then re-snapshot after meaningful UI changes. If you are unsure about Playwright CLI syntax, run `npx @playwright/cli --help` or `npx @playwright/cli <command> --help` instead of guessing option names. > **Always pick a unique `PW_SESSION` name and pass it as `-s=$PW_SESSION`** on every `npx @playwright/cli ...` call. The CLI is backed by a persistent daemon (`cliDaemon.js`) keyed by session name; if two shells both omit `-s=`, they share the implicit `"default"` session and the most-recently-attached CDP "wins" for every subsequent command from either shell. The launch skill is built around isolation (per-instance UDD, ports, shared-data-dir), and this pattern keeps that isolation intact at the Playwright-driving layer too. **A note on the alternative `PLAYWRIGHT_CLI_SESSION` env var:** it's documented in the package README and works correctly for `open`-style workflows, but it interacts poorly with `attach --cdp=...` (the daemon ends up with both `--cdp=...` and `--endpoint=<env-value>`, and the latter wins, causing a `connect ENOENT` failure). Confirmed against `@playwright/cli@0.1.13`. Explicit `-s=NAME` works in all modes. ```bash # At the top of your script / subagent prompt: PW_SESSION="my-uniq-$$" # any unique string; $$ is fine for one shell per agent # launch.sh blocks until CDP is ready, so a single attach is enough. npx @playwright/cli -s=$PW_SESSION attach --cdp=http://127.0.0.1:$CDP npx @playwright/cli -s=$PW_SESSION tab-list npx @playwright/cli -s=$PW_SESSION snapshot ``` After `attach`, later `@playwright/cli` commands keep using the connected app until you close or reattach — as long as you keep passing the same `-s=$PW_SESSION`. ### Selecting the right Electron target Electron apps can expose multiple windows or webviews. If `tab-list` shows `about:blank`, a webview, or otherwise the wrong target, switch targets before interacting: ```bash npx @playwright/cli -s=$PW_SESSION tab-list npx @playwright/cli -s=$PW_SESSION tab-select 2 npx @playwright/cli -s=$PW_SESSION snapshot ``` If a target looks stale after relaunching, run `npx @playwright/cli -s=$PW_SESSION close`, attach again with `$CDP`, and re-check `tab-list`. ### Focusing the chat input Use the `playwrightScripts/focus-chat-input.ts` script in both the regular workbench and the Agents window. It performs the complete focus flow in one Playwright call: 1. If a visible chat input is already focused, it does nothing.