Installation Guide

Install RoboClaw AI Studio
in Under 5 Minutes

From VSIX download to your first generated Robot Framework script — every step, every prerequisite, every fix for common setup errors. Works fully offline after install.

⏱️ ~5 minutes end-to-end 📦 v3.16.7 · 315 MB offline bundle 💻 macOS · Windows · Linux 🛜 Offline-capable after first install

1Prerequisites

RoboClaw ships its full Python dependency tree inside the VSIX, so you only need a small set of host tools.

ToolVersionRequired?Why
VS Code≥ 1.85.0✅ RequiredExtension host
Python≥ 3.10✅ RequiredLocator + healing engines, script generation
Robot Framework7.x⚙️ Auto-installedTarget test framework
Appium Server≥ 2.0📱 Mobile onlyiOS / Android automation
Selenium≥ 4.0🌐 Web onlyBrowser automation
Node.js≥ 18🔧 Dev onlyOnly required to build from source
💡
Quick check. Run python3 --version and code --version in a terminal. If both print a version, you're ready.

2Download the VSIX

RoboClaw is distributed as a single offline .vsix file containing the extension, all Python dependencies, and bundled reference assets.

  1. Go to the RoboClaw AI Studio landing page.
  2. Click Download RoboClaw AI Studio Extension.
  3. Enter your 10-character license code in the modal (contact the maintainer if you don't have one).
  4. The browser will download roboclaw-ai-studio-3.16.7.vsix (~315 MB).
ℹ️
Why so large? The VSIX bundles 40+ Python wheels and reference assets so first-run setup never hits the network. A slim "core-only" build is planned for future versions.

3Install in VS Code

Option A — One-liner (recommended)

Open a terminal in the folder containing the downloaded .vsix:

$code --install-extension roboclaw-ai-studio-3.16.7.vsix

Option B — From the VS Code UI

  1. Open VS Code.
  2. Press ⇧+⌘+X (mac) / Ctrl+Shift+X (win/linux) to open the Extensions panel.
  3. Click the ⋯ menu in the top-right of the panel → Install from VSIX…
  4. Select roboclaw-ai-studio-3.16.7.vsix and wait ~30 seconds.
  5. When prompted, click Reload Window.

Option C — From source (contributors)

$git clone <repo-url> && cd robogent-studio && npm install && npm run compile

Then press F5 in VS Code to launch the Extension Development Host.

4Run the Setup Wizard

On first launch, RoboClaw plays a splash screen followed by a one-time guided wizard. It collects only the data needed to wire up your project management system.

1 / 4 Your Name
Used to tag generated test cases and BugBuddy filings. Required.
2 / 4 License Code
The same 10-character code you used to download. Stored locally in globalState — never sent anywhere.
3 / 4 Project Management System
Choose Azure DevOps or Atlassian Jira — the entire UI adapts to your choice. You can switch later from Settings.
  • Azure DevOps: organisation, project, PAT (token)
  • Jira: domain, project key, email, API token
4 / 4 AI Provider (optional — BYOK)
Pick any AI provider: Anthropic Claude, OpenAI, Google Gemini, Azure OpenAI, Ollama / LM Studio / OpenRouter / Groq (custom OpenAI-compatible endpoint), or skip and use GitHub Copilot. Your key is live-validated with a single-token ping, then stored in VS Code SecretStorage — never logged, never sent anywhere except your chosen provider. You can change providers or models any time via RoboClaw: Configure your AI Provider API — BYOK and RoboClaw: Choose AI Model.
  • Routing order: your BYOK provider → GitHub Copilot → offline template.
  • Copilot always available — BYOK never blocks it.
✅
Need to re-run the wizard? Run RoboClaw: Reset Setup Prompt from the Command Palette, then reload.

5Provision the Python Environment

RoboClaw creates a workspace-local virtualenv (.robogent-venv/) and installs all 40+ Python dependencies offline from the bundled wheel cache.

  1. Open any Robot Framework workspace (a folder containing Resources/ or Tests/).
  2. Click the 🤖 RoboClaw AI Studio icon in the Activity Bar.
  3. In the sidebar, click Setup Python Environment.
  4. Watch the status bar for progress (~60–120 s on first run).
📦
What gets installed? Appium-Python-Client, Selenium, Robot Framework 7.x, DataDriver, RequestsLibrary, DatabaseLibrary, Pillow, lxml, anthropic, plus internal helpers — all from python-deps/.
⚠️
Custom Python interpreter? If you want RoboClaw to use a specific Python, set roboclaw.pythonPath in Settings before clicking Setup.

6Configure Your First Session

For Mobile (Appium)

  1. Start your Appium server: appium (default http://127.0.0.1:4723).
  2. Connect your iOS / Android device (or simulator).
  3. In the RoboClaw sidebar, click Configure Session.
  4. Pick Mobile (Appium), fill the capabilities, click Save & Connect.
platform         iOS             # or Android
automationName   XCUITest        # or UiAutomator2
deviceName       iPad Mini (6th Gen)
udid             00008101-0012345A6789ABCD
bundleId         com.acme.mfgpro
platformVersion  17.5           # auto-detected if empty

For Web (Selenium)

  1. In the sidebar, click Configure Session → Web (Selenium).
  2. Pick your browser (Chrome / Firefox / Safari / Edge).
  3. Choose headless / headed mode and click Save & Connect.
💾
Save device profiles with RoboClaw: Save Device Profile — reuse them across teammates with Export Session Config / Import Session Config.

7Verify Your Install

A quick smoke test to confirm everything is wired correctly:

  1. Click ▶ Live Device Mirror in the sidebar → you should see a real-time stream of your device.
  2. Run RoboClaw: Capture Current Screen (⇧+⌘+R S) → screenshot + XML saved to Robogent-Input/.
  3. Run RoboClaw: Generate Locators (⇧+⌘+R L) → locators.json appears next to the capture.
  4. Check the status bar — you should see RoboClaw · Connected · iOS in green.
🎉
All green? You're ready to generate test cases or jump straight into the Live Device Mirror.

8Troubleshooting

"Python interpreter not found"

Set roboclaw.pythonPath in Settings to an absolute path (e.g. /opt/homebrew/bin/python3), then re-run Setup Python Environment.

"Appium session failed: Could not detect device"

  • Confirm Appium server is running: curl http://127.0.0.1:4723/status
  • For iOS: xcrun xctrace list devices — confirm the UDID matches.
  • For Android: adb devices — make sure the device shows as device (not unauthorized).

"ADO 401 Unauthorized"

Your PAT scope is wrong. Re-create a PAT with at minimum Work Items: Read & Write and Test Plans: Read & Write, then run RoboClaw: Configure Session again.

"Setup wizard never appeared"

Run RoboClaw: Reset Setup Prompt from the Command Palette, then reload the window.

Need a clean slate?

⌘⇧PRoboClaw: Factory Reset

Wipes all stored credentials, settings, healing DB, and re-launches the Setup Wizard fresh.

⚠️
Factory Reset is irreversible. Export your config first with RoboClaw: Export Session Config if you want a backup.

9Upgrade or Uninstall

Upgrade to a newer version

RoboClaw does not auto-update. To install a newer release:

  1. Download the new .vsix from the landing page.
  2. Install over the existing extension — it'll replace in-place and preserve your config.
  3. Reload the window when prompted.

Uninstall

  1. VS Code → Extensions panel → search RoboClaw.
  2. Click the gear icon → Uninstall.
  3. (Optional) Delete .vscode/robogent.json and .robogent/ from your workspace to remove all state.

Next steps

Generate Test Cases
Import user stories from ADO/Jira and produce Functional, Regression & Smoke suites.
Live Device Mirror
Stream your iOS / Android / Web target in real time with element inspector.
File bugs with BugBuddy
One-click bug filing to Azure DevOps or Jira from any test failure.