Unity Cursor Toolkit

June 19, 2026 · View on GitHub

A VS Code / Cursor extension that bridges your editor and the Unity Editor -- hot reload, live console, MCP server for AI agents, Mono debugging, and stable TCP connectivity.

Disclaimer

This extension is not affiliated with, endorsed by, or an official product of Unity Technologies. Unity and the Unity logo are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere.

Features

Hot Reload

Save-to-refresh with debounced file watching and compilation feedback in the status bar. IL patching support for play-mode method body swapping without domain reload.

Live Console

Real-time streaming, severity filtering, text search across messages and stack traces, safe clickable Assets/... stack traces, copy/export, send-to-AI-chat, and a ring buffer (10k entries, configurable). Console snapshots can include the current Unity profiler session so agents get logs, frame trends, hot frames, and hot paths together.

Connection

TCP state machine with toolkit ping/pong validation, heartbeat, exponential backoff reconnect, and multi-port auto-select (55500-55504). Open ports that do not answer the Unity Cursor Toolkit handshake are ignored so the extension does not attach to unrelated Unity listeners.

Status Bar

Two-part layout: one-click connect toggle plus quick-access dropdown with play mode controls, console snapshot, and project info.

Play Mode Control

Enter, exit, pause, and single-frame step directly from VS Code / Cursor -- no need to switch to the Unity Editor.

MCP Server

AI agents (Cursor, Claude Code, Copilot, Zed, and other MCP clients) can read console output, inspect project state, control play mode, manage scenes/assets, query project info, capture screenshots, inspect profiler snapshots, query a compact Unity context index, run game-authored command sequences, and use read-only or dry-run safeguards before mutating Unity state.

Mono Debugger

Attach to the Unity Editor or a Development Player via the built-in Mono soft debugger (port 56000 default).

Meta File Management

Auto-hide .meta files from explorer and Cmd+P, with workspace-contained on-demand resolve for AI workflows.

Unity Package (C# side)

A companion UPM package (com.rankupgames.unity-cursor-toolkit) provides the Unity-side scripts: console forwarding, hot reload handler, MCP bridge, runtime command registry, debug bridge, and IL patcher. Installable via OpenUPM, Git URL, or scoped registry.

Quick Start

Install the extension from the VS Code Marketplace or OpenVSX.
Install the Unity package (see Unity Package Installation).
Open a Unity project folder in VS Code or Cursor.
Click Unity Attach in the status bar to connect.

AI Agent Quick Start

The extension now builds a standalone MCP stdio server for agents that do not run VS Code extensions directly.

cd unity-cursor-toolkit
npm ci
npm run compile
npm run mcp:serve

Use Unity Toolkit: Copy MCP Client Config in VS Code/Cursor to copy setup snippets, or read MCP Client Setup for Cursor, Claude Code, VS Code Copilot Agent mode, and Zed examples.

Agent safety defaults:

Set UNITY_CURSOR_TOOLKIT_MCP_READ_ONLY=1 to block mutating tools.
Pass dryRun: true to mutating tools to inspect the normalized Unity command without executing it.
Start with project_info, read_console, and manage_scene using action: "getHierarchy" before scene or asset edits.
Use unity_context with action: "scan" to refresh .umetacontext/index.json, then use summary, query, and read to inspect assets, GUIDs, serialized objects, components, and references without broad file reads.
Use game_command with action: "list" to discover project-authored runtime workflows before scheduling them.

See AI Agent Guide, Runtime Game Commands, Feature Roadmap, and llms.txt for agent-facing context.

Requirements

VS Code or Cursor 1.60+
Unity 2019.4+

Unity Package Installation

Via OpenUPM (recommended)

openupm add com.rankupgames.unity-cursor-toolkit

Via Git URL

In Unity: Window > Package Manager > + > Add package from git URL

https://github.com/rankupgames/unity-cursor-toolkit.git?path=Packages/com.rankupgames.unity-cursor-toolkit

Via Scoped Registry

Add to your project's Packages/manifest.json:

"scopedRegistries": [
  {
    "name": "OpenUPM",
    "url": "https://package.openupm.com",
    "scopes": ["com.rankupgames"]
  }
],
"dependencies": {
  "com.rankupgames.unity-cursor-toolkit": "1.1.0"
}

Runtime Game Commands

Unity projects can register runtime command sequences that agents can call through MCP without driving the UI. Commands are registered from game code through UnityCursorToolkit.AgentCommands.AgentCommandRegistry, run as coroutines during play mode, and are scheduled through the game_command MCP tool.

Typical flow:

{ "action": "list" }

{ "action": "run", "commandName": "auth.select_us_east", "args": {} }

Then poll with:

{ "action": "status", "runId": "<run id returned by run>" }

See Runtime Game Commands for registration patterns and project integration notes.

For non-rendering command discovery and execution in CI or headless automation, pass host: "editorBatchmode". The MCP server launches Unity with UnityCursorToolkit.AgentCommands.BatchCommandEntry.Run, writes structured arguments to a temp file, and returns the Unity log tail plus the command result JSON.

Configuration

Setting	Default	Description
`unityCursorToolkit.console.enabled`	`true`	Enable the Unity Console panel in the sidebar
`unityCursorToolkit.console.autoStream`	`true`	Auto-stream console output when connected
`unityCursorToolkit.console.maxEntries`	`10000`	Max entries in the console ring buffer
`unityCursorToolkit.hotReload.preferILPatch`	`true`	Prefer IL patching over full asset refresh in play mode
`unityCursorToolkit.hotReload.ilPatchTimeout`	`5000`	Timeout (ms) for IL patch before falling back to full refresh
`unityCursorToolkit.workspaceScanPaths`	`[]`	Additional paths to scan for `.code-workspace` files

Development and Validation

The extension package lives in unity-cursor-toolkit/.

cd unity-cursor-toolkit
npm ci
npm run validate

npm run validate is the canonical local and CI gate. It compiles the extension, runs a strict unused-code type check, executes the runtime test harness, and runs both production and full npm audits.

Dependency updates should use npm 11.14.1 or newer with the repository age gate, for example npm update <package> --package-lock-only --ignore-scripts --min-release-age=7. Prefer lockfile-scoped security fixes for transitive audit findings. If a fixed package is newer than 7 days, leave the advisory pending unless the update is explicitly approved as a security hotfix.

For packaging checks:

npx vsce package --no-dependencies

The VSIX package is intentionally limited to runtime extension assets: compiled out/ files, metadata, icon, and license. Tests, backups, lockfiles, source maps, and generated bundles are excluded through .vscodeignore.

Security Hardening

Dependency audits run through npm run validate and GitHub Actions.
Dependency updates follow a 7-day npm release-age gate unless an explicit security hotfix exception is documented.
TCP attach requires the current Unity package handshake; if Unity exposes an older package server, the extension reports that the package should be updated instead of treating the port as connected.
Console webviews use nonce-based CSP for scripts and styles.
Console payloads are normalized before rendering, filtering, copying, or forwarding to chat.
Clickable stack traces and .meta resolution reject paths that escape the current workspace.

Commands

Command	Description
`unity-cursor-toolkit.startConnection`	Start/Attach to a Unity project
`unity-cursor-toolkit.reloadConnection`	Reload the current connection
`unity-cursor-toolkit.stopConnection`	Stop the connection
`unity-cursor-toolkit.console.clear`	Clear the console panel
`unity-cursor-toolkit.console.sendToChat`	Send console output to AI chat
`unity-cursor-toolkit.console.copy`	Copy console output to clipboard
`unity-cursor-toolkit.console.snapshot`	Take a console/profiler snapshot
`unity-cursor-toolkit.console.export`	Export console logs to file
`unity-cursor-toolkit.resolveMeta`	Resolve `.meta` file for a path (for AI)
`unity-cursor-toolkit.openProject`	Open Unity project in the editor
`unity-cursor-toolkit.generateFolderStructure`	Generate folder structure for AI context
`unity-cursor-toolkit.quickAccess`	Quick Actions menu
`unity-cursor-toolkit.debug.attach`	Attach Mono debugger to Unity
`unity-cursor-toolkit.playMode.enter`	Enter Play Mode
`unity-cursor-toolkit.playMode.exit`	Exit Play Mode
`unity-cursor-toolkit.playMode.pause`	Pause Play Mode
`unity-cursor-toolkit.playMode.step`	Step one frame
`unity-cursor-toolkit.screenshot`	Capture a screenshot from Unity
`unity-cursor-toolkit.mcp.showServerPath`	Show the standalone MCP server path
`unity-cursor-toolkit.mcp.copyClientConfig`	Copy MCP client config snippets

Project Structure

unity-cursor-toolkit/
├── unity-cursor-toolkit/           # VS Code / Cursor extension (TypeScript)
│   └── src/
│       ├── extension.ts            # Entry point and composition root
│       ├── core/                   # Connection, transport, types, module loader
│       ├── console/                # Console bridge, panel, and MCP tools
│       ├── hot-reload/             # File watcher with debounce
│       ├── mcp/                    # MCP server, tool router, Unity tools
│       ├── debug/                  # Mono debug adapter
│       └── project/                # Project handler, meta manager, folder templates
├── Packages/
│   └── com.rankupgames.unity-cursor-toolkit/   # Unity UPM package (C#)
│       ├── Runtime/
│       │   └── AgentCommands/         # Runtime command registry and coroutine runner
│       └── Editor/
│           ├── ConsoleToCursor.cs       # Console log forwarding
│           ├── ProfilerSnapshot.cs      # Profiler session snapshots and MCP access
│           ├── HotReloadHandler.cs      # Asset refresh on code changes
│           ├── Core/                    # MCP tool attribute, interfaces
│           ├── Debug/                   # Mono debug bridge
│           ├── HotReload/              # IL patcher
│           └── MCP/                     # MCP bridge, scene/asset/editor tools
├── CursorUnityTool/                # Unity test project
├── zed/                            # Zed editor integration (MCP)
├── docs/                           # Agent and MCP setup docs
├── AGENTS.md                       # Coding-agent repo instructions
├── llms.txt                        # AI-readable documentation index
├── .github/workflows/              # CI and release pipelines
├── CONTRIBUTING.md
├── SECURITY.md
└── CODE_OF_CONDUCT.md

Distribution

VS Code Marketplace -- Primary distribution
OpenVSX -- Windsurf, VSCodium, Theia
Cursor -- Native support
Zed -- Via standalone MCP server (see zed/)

CI and release workflows publish separate VS Code Marketplace and OpenVSX VSIX artifacts. Publishing fails loudly when VSCE_PAT or OVSX_PAT repository secrets are missing, so a green release means both registry uploads were attempted with valid credentials.