From c33be50ae8d7d42bd609e9a5e03ef1b9e9093231 Mon Sep 17 00:00:00 2001 From: Mwright413 <93616921+Mwright413@users.noreply.github.com> Date: Thu, 7 May 2026 14:48:17 -0400 Subject: [PATCH] docs(cli): add Windows VS Code bootstrap note --- apps/cli/README.md | 4 + apps/cli/docs/WINDOWS_VSCODE_BOOTSTRAP.md | 229 ++++++++++++++++++++++ 2 files changed, 233 insertions(+) create mode 100644 apps/cli/docs/WINDOWS_VSCODE_BOOTSTRAP.md diff --git a/apps/cli/README.md b/apps/cli/README.md index 8dec1f3a1c6..80526453af5 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -21,6 +21,10 @@ curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/i - Node.js 20 or higher - macOS Apple Silicon (M1/M2/M3/M4) or Linux x64 +On Windows, use the Roo Code VS Code extension as the runtime. See +[Windows VS Code Bootstrap](docs/WINDOWS_VSCODE_BOOTSTRAP.md) for a repeatable +workspace launch pattern that keeps provider setup, auth, and approvals in Roo. + **Custom installation directory:** ```bash diff --git a/apps/cli/docs/WINDOWS_VSCODE_BOOTSTRAP.md b/apps/cli/docs/WINDOWS_VSCODE_BOOTSTRAP.md new file mode 100644 index 00000000000..9fc6e2f4518 --- /dev/null +++ b/apps/cli/docs/WINDOWS_VSCODE_BOOTSTRAP.md @@ -0,0 +1,229 @@ +# Windows VS Code Bootstrap + +The CLI quick installer currently targets macOS Apple Silicon and Linux x64. On +Windows, use the Roo Code VS Code extension as the runtime. A small workspace +launch config can make that extension flow repeatable without replacing Roo's +normal provider setup, authentication, approvals, or mode behavior. + +This pattern is useful when a team wants a local script to reopen a workspace, +load a prompt file, and optionally select a project mode or provider profile. +Keep the application itself standalone; VS Code and Roo are only the control +plane. + +## Roo Defaults To Preserve + +For first-time users, follow the extension's normal setup first: + +1. Install Roo Code in VS Code. +2. Open the target workspace folder. +3. Open the Roo panel. +4. Choose an API provider and model in Roo's settings. +5. Complete any provider-owned sign-in or API-key setup. +6. Start a small manual task to confirm the profile works. + +The bootstrapper should preserve these defaults: + +- If no provider profile is supplied, Roo uses the active or mode-sticky profile. +- If no mode is supplied, Roo starts in its default Code mode. +- Provider auth stays inside Roo and VS Code SecretStorage. +- User approval and auto-approval settings remain Roo settings. +- Model-specific defaults, such as reasoning effort, should be left alone unless + the launch config explicitly overrides them. + +## Minimal Launch Config + +This file is a local handoff format for a helper script or helper extension. It +is not a Roo Code API contract. + +`.roo-launch.json`: + +```json +{ + "requestId": "replace-with-a-new-id-per-launch", + "autostart": true, + "promptFile": ".roo/prompts/init.md", + "newTab": true +} +``` + +`.roo/prompts/init.md`: + +```markdown +You are Roo Code initializing this workspace. + +First read: + +- AGENTS.md +- the repo README, if present +- package, build, or project files that identify the stack + +Then produce a concise workspace orientation and wait for the next concrete +build task. +``` + +With this minimal config, the helper only opens Roo and starts the prompt. Roo +keeps using whichever provider profile and mode the user already configured. + +## Optional Project Mode + +Project modes are a normal Roo Code customization path through `.roomodes`. +Add a project mode only when the workspace needs scoped behavior that differs +from the built-in Code, Ask, Architect, Debug, or Orchestrator modes. + +`.roomodes`: + +```yaml +customModes: + - slug: app-builder + name: App Builder + roleDefinition: |- + You are Roo Code working as a focused builder for this repository. + Read the workspace instructions first, then implement the user's task. + whenToUse: Build, revise, or inspect this repository using local project instructions. + description: Focused builder mode for this workspace. + groups: + - read + - command + - edit + source: project +``` + +Then reference the mode in `.roo-launch.json`: + +```json +{ + "requestId": "replace-with-a-new-id-per-launch", + "autostart": true, + "promptFile": ".roo/prompts/init.md", + "mode": "app-builder", + "newTab": true +} +``` + +## Optional Provider Profile + +Use an explicit profile only when the workspace launcher should activate a +specific Roo provider profile. Otherwise, omit `profile` and let Roo use the +active or mode-sticky profile configured by the user. + +For ChatGPT Plus/Pro users, the OpenAI Codex provider can be configured like +this: + +```json +{ + "requestId": "replace-with-a-new-id-per-launch", + "autostart": true, + "promptFile": ".roo/prompts/init.md", + "mode": "app-builder", + "newTab": true, + "profile": { + "name": "App Builder Codex", + "apiProvider": "openai-codex", + "apiModelId": "gpt-5.5" + } +} +``` + +If a selected model supports reasoning effort and the workspace intentionally +wants to override the model default, include the provider fields Roo already +uses: + +```json +{ + "profile": { + "name": "App Builder Codex", + "apiProvider": "openai-codex", + "apiModelId": "gpt-5.5", + "enableReasoningEffort": true, + "reasoningEffort": "high" + } +} +``` + +Do not put provider secrets, OAuth tokens, or API keys in `.roo-launch.json`. +For `openai-codex`, Roo owns the OpenAI Codex OAuth flow. It does not use a +user-supplied `OPENAI_API_KEY`. + +## Helper Extension Shape + +A local helper extension can read `.roo-launch.json`, activate Roo Code, and +start the task: + +```ts +const roo = vscode.extensions.getExtension("RooVeterinaryInc.roo-cline") +const api = roo?.isActive ? roo.exports : await roo?.activate() + +if (config.profile) { + const { name = "Workspace Profile", ...profile } = config.profile + await api.upsertProfile(name, profile, true) +} + +const configuration: Record = {} +if (config.mode) { + configuration.mode = config.mode +} + +await api.startNewTask({ + text: promptText, + newTab: config.newTab !== false, + configuration, +}) +``` + +The helper should treat provider errors as Roo errors. If Roo reports that the +provider is not authenticated, ask the user to finish sign-in in the Roo panel +and rerun the launch command. + +## PowerShell Wrapper Shape + +The wrapper should stay project-neutral. It can write a launch config, open the +workspace in VS Code, and trigger a helper extension URI. + +```powershell +param( + [string]$Workspace = (Get-Location).Path, + [string]$PromptFile = ".roo\prompts\init.md", + [string]$Mode, + [switch]$NoLaunch +) + +$workspacePath = (Resolve-Path -LiteralPath $Workspace).Path +$promptPath = (Resolve-Path -LiteralPath (Join-Path $workspacePath $PromptFile)).Path + +$config = [ordered]@{ + requestId = [guid]::NewGuid().ToString() + autostart = -not $NoLaunch + promptFile = $promptPath + newTab = $true +} + +if ($Mode) { + $config.mode = $Mode +} + +$configPath = Join-Path $workspacePath ".roo-launch.json" +$config | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath $configPath -Encoding UTF8 + +code -n $workspacePath + +if (-not $NoLaunch) { + $escaped = [Uri]::EscapeDataString($configPath) + Start-Process "vscode://local.roo-workspace-launcher/launch?configPath=$escaped" +} +``` + +Provider-specific flags can be layered on top, but the default path should work +with any provider the user already configured in Roo. + +## Upstream Opportunity + +This pattern can remain a documented Windows workaround, or Roo Code could +absorb the core behavior as a first-class command: + +```text +Roo Code: Launch Task From Config +``` + +That command could read a workspace-local config, optionally activate a provider +profile, optionally select a mode, and start a task from a prompt file without a +separate helper extension.