# Add a Getting Started Walkthrough to a VS Code Extension

Yes. An agent reads your extension's commands and settings, contributes a walkthrough with steps that complete on real actions, packages the media, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-walkthrough/vscode-extension/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts from the manifest. In an extension like usernamehw/vscode-error-lens, `package.json` declares version 3.30.0 for publisher `usernamehw`, requires `vscode` 1.107.0 or later, activates on `onStartupFinished`, and ships `dist/extension.js` as both `main` and `browser`, built by webpack through the `vscode:prepublish` script. Its `contributes` block has three keys: 17 `commands` in the `Error Lens` category, a `configuration` with 76 `errorLens.*` settings, and `colors`. There is no `walkthroughs` key. The README documents every command and setting in generated tables between `COMMANDS_START` and `SETTINGS_START` markers, and `docs/docs.md` opens by saying the inline message is the most annoying part of the extension and shows how to tame it, with screenshots under `docs/img/` for `followCursor`, `messageBackgroundMode`, `gutterIconsEnabled` and the rest. `.vscodeignore` excludes `docs`, `src` and `img/demo.png` from the package, and the `CHANGELOG.md` entries carry release dates. A new user installs the extension, sees every line in red, and either finds `docs/docs.md` or uninstalls.

It writes the walkthrough into `contributes.walkthroughs` with one entry, id `gettingStarted`, a title and a short description, and five steps that follow the order `docs/docs.md` already uses. The first step shows what the extension does, with a packaged screenshot as `media.image` and alt text. The second, calming it down, links `command:errorLens.toggleInlineMessage` and the `errorLens.followCursor` setting and completes on `onCommand:errorLens.toggleInlineMessage` or `onSettingChanged:errorLens.followCursor`. The third picks severities with the four toggle commands and completes on `onSettingChanged:errorLens.enabledDiagnosticLevels`. The fourth covers the gutter and status bar settings. The fifth, for the two commands added in 3.30.0, `errorLens.nextProblem` and `errorLens.prevProblem`, suggests a keybinding and completes on `onCommand:errorLens.nextProblem`. Each step's description uses the `command:` link form VS Code renders as a button, so a step is done by doing the thing, not by reading about it.

Media has to be inside the package, and `.vscodeignore` currently drops `docs` entirely. The agent copies the screenshots the steps use into `media/walkthrough/`, keeps that directory out of the ignore list, and adds `media/walkthrough/**` nowhere else so `npx @vscode/vsce ls` shows exactly those files beside `dist/extension.js`, `img/icon.png`, `README.md` and `CHANGELOG.md`. Settings referenced in step text use the `#errorLens.followCursor#` form the existing configuration descriptions already use, which VS Code turns into a link to the setting. The README gets one line under Features pointing at the walkthrough through the `Help: Welcome` page, and the CHANGELOG is left for the maintainer, since its entries are dated at release.

The repository has no test script, so the agent proves the contribution two ways. `npm ci` and `npm run vscode:prepublish` show webpack still builds the bundle in production mode. Then it installs `@vscode/test-electron` as a dev dependency for the run only, downloads VS Code, and runs a small script that activates the extension and executes `workbench.action.openWalkthrough` with `usernamehw.errorlens#gettingStarted`, failing if the command rejects, which it does for an unknown walkthrough id or a malformed step. `npx @vscode/vsce package --no-dependencies` builds the `.vsix` and confirms the media paths resolve. The pull request keeps the test script in `scripts/` as an optional check rather than wiring it into `package.json`, so the maintainer's build stays the same.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a Getting Started walkthrough to this VS Code extension. Read package.json in full, README.md, CHANGELOG.md, docs/docs.md, .vscodeignore, .vscode/launch.json, src/extension.ts and src/commands.ts first. Contribute one walkthrough under contributes.walkthroughs with five steps that follow the order docs/docs.md uses: what the extension shows, calming the inline message with the toggle command and followCursor, choosing severities with the toggle commands, gutter and status bar settings, and the next and previous problem commands with a suggested keybinding. Use command: links in step descriptions and completionEvents on the real commands and settings. Copy the screenshots each step needs into media/walkthrough and make sure .vscodeignore keeps them in the package. Add one README line pointing at the walkthrough and leave the CHANGELOG alone. Run npm ci and npm run vscode:prepublish, package with vsce and list the packaged files, and run a script with @vscode/test-electron that activates the extension and opens the walkthrough by id so a bad id or step fails. Open a pull request that lists each step and its completion event.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds a `walkthroughs` contribution to `package.json`, a `media/walkthrough/` directory with the screenshots the steps use, one line in `README.md`, and a `scripts/` check that opens the walkthrough in a downloaded VS Code. The description lists the five steps, the command or setting each one completes on, and the files `vsce ls` reports in the package.

The run's record keeps the webpack output from `vscode:prepublish`, the `vsce ls` listing, and the output of the test-electron script with the walkthrough id it opened, so a reviewer sees the contribution is well formed without installing the `.vsix` first.

Before merging, a reviewer installs the packaged `.vsix`, opens `Help: Welcome`, picks the walkthrough, and clicks through each step, checking that the toggle step ticks itself when the inline message is toggled and that every image loads from the package rather than from the repository.

## Run it on every Linear issue labelled onboarding

In the console, an automation with a `linear` trigger on `linear.issue.labeled` and the label `onboarding` starts one run per labelled issue in the Project's repository. The trigger adds the issue's text after the saved prompt, so an issue that asks for a step about a new setting or a shorter walkthrough carries that request itself and the prompt stays fixed. Changes made by an app integration never fire it, and the automation's `max_runs_per_hour` bounds a burst of labelling.

From your own server, the same job is one `POST /o/{org}/sessions` per issue, with the repository in `resources` and the issue's `https://linear.app/<workspace>/issue/<ID>` URL beside it so Rush reads the issue through your Linear connection. A `webhook_url` on the API key receives `run.completed` or `run.failed` for every run that key starts, with the `session_url` to read the pull request link from.

## Why run it on Rush?

A walkthrough is JSON that VS Code validates only when it loads the extension, and the usual mistakes, an image path the package does not contain, a `completionEvents` entry naming a command that does not exist, a settings link in the wrong form, show up as a blank step in the Welcome page rather than as a build error. The agent downloads VS Code into its own sandbox, loads the extension and opens the walkthrough by id, which a review of the diff cannot do.

The packaging check matters as much as the manifest: `.vscodeignore` in this extension excludes the whole docs tree, so a step that pointed at `docs/img/` would render in the development host and break in the Marketplace build. The `vsce ls` output in the run's record shows the media files present, with the command that produced it.

## Frequently asked questions

### Will the walkthrough open on its own after install?

VS Code shows a new extension's walkthrough on the Welcome page after installation; it does not interrupt the editor. The agent does not call `workbench.action.openWalkthrough` from `activate`, because an extension that activates on `onStartupFinished` would then open the page on every start.

### Can a step complete when the user changes a setting rather than runs a command?

Yes, through `onSettingChanged:` in `completionEvents`, which the calming and severity steps use for `errorLens.followCursor` and `errorLens.enabledDiagnosticLevels`. A step with no completion event completes when the user clicks it, which the first, descriptive step relies on.

### Does this change the webpack build or the published bundle?

No. The contribution lives in `package.json` and the media directory; `dist/extension.js` is unchanged and `vscode:prepublish` runs exactly as before. The only packaging difference is the handful of images under `media/walkthrough/` that `vsce ls` now lists.

### What if a step references a command that is later renamed?

The step's button stops working and its completion never fires, with no build error. The test-electron script in `scripts/` opens the walkthrough and can be extended to execute each `command:` link it finds, which is the regression check the pull request suggests adding to CI.

## More VS Code Extension jobs

- [Make a VS Code Extension Run in the Browser as a Web Extension](https://getrush.ai/run/add-web-extension-support/vscode-extension/)
- [Turn Sentry Errors Into Fix Pull Requests for a VS Code Extension](https://getrush.ai/run/fix-sentry-errors/vscode-extension/)
- [Migrate a VS Code Extension to ESLint Flat Config](https://getrush.ai/run/migrate-eslint-flat-config/vscode-extension/)

## More jobs like this: Turn a Linear label into a PR

- [Add a Watchlist Page to a Nuxt App from a Linear Issue](https://getrush.ai/run/add-watchlist/nuxt/)
- [Add Webmentions to an Eleventy Blog](https://getrush.ai/run/add-webmentions/eleventy/)
- [Add WebSockets to a Leptos App](https://getrush.ai/run/add-websockets/leptos/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
