Develop

Getting Started with AI

Updated: Sep 4, 2026

This guide connects a supported AI coding tool to the IWSDK managed workspace and verifies that the runtime is ready for commands.

Prerequisites

You need:

An IWSDK project. See Project setup if you do not have one.

One supported AI coding tool: Claude Code, Cursor, GitHub Copilot, Codex, or OpenCode.

Project dependencies installed.

Run the commands in this guide from your project root.

Configure the project

Current IWSDK projects use a project manifest and the Vite development plugin:

import {defineConfig} from 'vite';
import {iwsdkDev} from '@iwsdk/vite-plugin-dev';

export default defineConfig({
  plugins: [iwsdkDev()],
});

Keep project settings such as the scene path, asset modules, component modules, World options, and emulator configuration in iwsdk.config.json. Select the development session at the command line.

Manifest-first configuration

Do not pass `ai`, `workspace`, or `emulator` options to `iwsdkDev()` in a project that has `iwsdk.config.json`. The plugin rejects those legacy options when the project manifest is present.

Configure your AI tool

Generate every supported adapter from the project root:

npx iwsdk adapter sync

To generate only selected adapters, pass a comma-separated list:

npx iwsdk adapter sync --tools claude,cursor

The adapter command manages these project-local files:

AI tool	MCP configuration	Additional behavior
Claude Code	`.mcp.json`	Creates a `CLAUDE.md` shim when no supported Claude instruction file exists.
Cursor	`.cursor/mcp.json`	Adds only IWSDK-managed server and permission entries.
GitHub Copilot	`.vscode/mcp.json`	Requires you to approve the MCP server in Visual Studio Code. A repository file cannot grant that approval.
Codex	`.codex/config.toml`	Sets approval mode for the managed IWSDK server entry.
OpenCode	`opencode.json`	Adds the managed MCP server and IWSDK skill permissions.

Adapter sync configures MCP servers and IWSDK-managed permission entries. It creates the top-level AGENTS.md only when that file is absent and can create the Claude shim, but it does not overwrite existing instruction files or install or refresh the generated skill directories. New projects receive their complete guidance and skills from the project generator.

The IWSDK project generator performs adapter sync after it successfully installs a new project’s dependencies. You can run sync again after upgrading IWSDK or changing AI tools.

Check the generated state at any time:

npx iwsdk adapter status

Use npx iwsdk adapter prune to remove only IWSDK-managed MCP and permission entries. For an unsupported MCP client, run npx iwsdk adapter prompt and follow the generated integration instructions.

Start the managed workspace

Start a headed workspace-only session:

npx iwsdk dev up --foreground

Start an explicit shared AI session:

npx iwsdk dev up --ai-mode collaborate --foreground

Start an explicit headless AI session:

npx iwsdk dev up --ai-mode agent --foreground

The managed browser opens by default. Use --no-open only when you deliberately want the development server without a managed browser. All iwsdk-runtime tool calls are unavailable in that state, including scene, UI, XR, browser, and ECS tools; schema inspection with iwsdk mcp inspect still works.

Many generated projects expose the same flow through npm run dev.

Verify readiness

In another terminal, inspect the registered session:

npx iwsdk dev status

Do not treat an HTTP response alone as browser readiness. Wait until both of these status fields are true:

state.browserCommandReady

state.session.browser.commandReady

Then inspect the MCP contract available to your AI tool:

npx iwsdk mcp inspect
npx iwsdk mcp inspect --tool scene_render_file

Your AI tool can now connect to the configured iwsdk-runtime server and use its reported schemas.

Make a first request

Ask your AI tool to inspect before it changes state. For example:

Use the IWSDK runtime tools to check the XR session, capture the application runtime, and report any console errors.

This request should use xr_get_session_status, browser_screenshot, and browser_get_console_logs. browser_screenshot always captures the application runtime, even when the Editor view is visible.

For native scene work, ask the agent to follow the file-authoring sequence:

Inspect the native scene capabilities, update the scene files, render every changed file, flatten the composed root, open the flattened file, and capture both editor and runtime evidence.

See Workflows for the exact render, flatten, and open sequence.

Set screenshot dimensions

Agent mode uses a fixed 800 by 800 pixel viewport by default. Set explicit dimensions when your task needs a different deterministic frame:

npx iwsdk dev up --ai-mode agent \
  --screenshot-width 1280 \
  --screenshot-height 720

In collaborate mode, the browser remains resizable. Screenshots are downscaled to fit within the configured screenshot bounds.

Troubleshoot the connection

Browser commands are not ready

Run:

npx iwsdk dev status
npx iwsdk dev logs --tail 100

If status reports that the browser was not launched, restart without --no-open. Wait for both browser command readiness fields before retrying the tool call.

The AI tool cannot see IWSDK tools

Run npx iwsdk adapter status, then run npx iwsdk adapter sync if the managed entry is missing or stale. Restart the AI tool if it does not reload project-local MCP configuration automatically.

A composed scene will not open

Render the root with scene_render_file, resolve every diagnostic, and then create an import-free file with scene_flatten_file. Pass the flattened path to scene_open.

A screenshot shows the wrong surface

Use scene_screenshot for a native Editor image and scene_get_state for structured validation, dirty, conflict, and runtime-readiness diagnostics. Use browser_screenshot for the running application. browser_screenshot does not accept an editor target.