Unity Cursor Toolkit

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).

Connection

TCP state machine with heartbeat, exponential backoff reconnect, and multi-port auto-select (55500-55504).

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, 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, 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.

See AI Agent Guide, 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.0.0"
}

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.

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.
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 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#)
│       └── Editor/
│           ├── ConsoleToCursor.cs       # Console log forwarding
│           ├── 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/)

Contributing

See CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for repository and extension changes. The Unity package changelog lives at Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md.

Security

See SECURITY.md for vulnerability reporting.

Name		Name	Last commit message	Last commit date
Latest commit History 54 Commits
.github		.github
.vscode		.vscode
CursorUnityTool		CursorUnityTool
Packages/com.rankupgames.unity-cursor-toolkit		Packages/com.rankupgames.unity-cursor-toolkit
docs		docs
unity-cursor-toolkit		unity-cursor-toolkit
zed		zed
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
SECURITY.md		SECURITY.md
llms.txt		llms.txt
unity-cursor-toolkit-workspace.code-workspace		unity-cursor-toolkit-workspace.code-workspace

Folders and files

Latest commit

History

Repository files navigation

Unity Cursor Toolkit

Disclaimer

Features

Hot Reload

Live Console

Connection

Status Bar

Play Mode Control

MCP Server

Mono Debugger

Meta File Management

Unity Package (C# side)

Quick Start

AI Agent Quick Start

Requirements

Unity Package Installation

Via OpenUPM (recommended)

Via Git URL

Via Scoped Registry

Configuration

Development and Validation

Security Hardening

Commands

Project Structure

Distribution

Contributing

Changelog

Security

License

About

Resources

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages