Unity Bridge Skill

Control Unity Editor operations from Claude Code using a reliable file-based communication protocol.

Overview

The Unity Bridge enables Claude Code to trigger operations in a running Unity Editor instance without network configuration or port conflicts. It uses a simple file-based protocol where commands are written to .unity-bridge/command.json and responses are read from .unity-bridge/response-{id}.json.

Key Features:

• •Execute EditMode and PlayMode tests
• •Trigger script compilation
• •Refresh asset database
• •Check editor status (compilation, play mode, etc.)
• •Retrieve Unity console logs

Multi-Project Support: Each Unity project has its own .unity-bridge/ directory, allowing multiple projects to be worked on simultaneously.

Requirements

1. •

   Unity Package: Install com.managexr.claude-bridge in your Unity project

   • •Via Package Manager: https://github.com/ManageXR/claude-unity-bridge.git
   • •See main package README for installation instructions
2. •

   Unity Editor: Must be open with your project loaded

3. •

   Python 3: The skill uses a Python script for reliable command execution

How It Works

The skill uses a CLI tool (unity-bridge) that handles:

• •UUID generation for command tracking
• •Atomic file writes to prevent corruption
• •Exponential backoff polling for responses
• •File locking handling
• •Automatic cleanup of old response files
• •Formatted, human-readable output

This approach ensures deterministic, rock-solid execution - the script is tested once and behaves identically every time, handling all edge cases (timeouts, file locking, malformed responses, etc.) without requiring Claude to manage these details in-context.

Usage

Basic Pattern

When you need to interact with Unity, use the CLI directly:

unity-bridge [command] [options]

All commands automatically:

• •Generate a unique UUID for tracking
• •Write the command atomically
• •Poll for response with timeout
• •Format output for readability
• •Cleanup response files

Command Examples

Run Tests

Execute Unity tests in EditMode or PlayMode:

# Run all EditMode tests
unity-bridge run-tests --mode EditMode

# Run tests with filter
unity-bridge run-tests --mode EditMode --filter "MXR.Tests"

# Run all tests (both modes)
unity-bridge run-tests

Output:

✓ Tests Passed: 410
✗ Tests Failed: 2
○ Tests Skipped: 0
Duration: 1.25s

Failed Tests:
  - MXR.Tests.AuthTests.LoginWithInvalidCredentials
    Expected: success, Actual: failure
  - MXR.Tests.NetworkTests.TimeoutHandling
    NullReferenceException: Object reference not set

Parameters:

• •--mode - EditMode or PlayMode (optional, defaults to both)
• •--filter - Test name filter pattern (optional)
• •--timeout - Override default 30s timeout

Compile Scripts

Trigger Unity script compilation:

unity-bridge compile

Output (Success):

✓ Compilation Successful
Duration: 2.3s

Output (Failure):

✗ Compilation Failed

Assets/Scripts/Player.cs:25: error CS0103: The name 'invalidVar' does not exist
Assets/Scripts/Enemy.cs:67: error CS0246: Type 'MissingClass' could not be found

Get Console Logs

Retrieve Unity console output:

# Get last 20 logs
unity-bridge get-console-logs --limit 20

# Get only errors
unity-bridge get-console-logs --limit 10 --filter Error

# Get warnings
unity-bridge get-console-logs --filter Warning

Output:

Console Logs (last 10, filtered by Error):

[Error] NullReferenceException: Object reference not set
  at Player.Update() in Assets/Scripts/Player.cs:34

[Error] Failed to load asset: missing_texture.png

[Error] (x3) Shader compilation failed
  See Console for details

Parameters:

• •--limit - Maximum number of logs (default: 50)
• •--filter - Filter by type: Log, Warning, or Error

Get Editor Status

Check Unity Editor state:

unity-bridge get-status

Output:

Unity Editor Status:
  - Compilation: ✓ Ready
  - Play Mode: ✏ Editing
  - Updating: No

Possible States:

• •Compilation: ✓ Ready or ⏳ Compiling...
• •Play Mode: ✏ Editing, ▶ Playing, or ⏸ Paused
• •Updating: Yes or No

Refresh Asset Database

Force Unity to refresh assets:

unity-bridge refresh

Output:

✓ Asset Database Refreshed
Duration: 0.5s

Advanced Options

Timeout Configuration

Override the default 30-second timeout:

unity-bridge run-tests --timeout 60

Use longer timeouts for:

• •Large test suites
• •PlayMode tests (which start/stop Play Mode)
• •Full project compilation

Cleanup Old Responses

Automatically remove old response files before executing:

unity-bridge compile --cleanup

This removes response files older than 1 hour. Useful for maintaining a clean workspace.

Verbose Output

See detailed execution progress:

unity-bridge run-tests --verbose

Prints:

• •Command ID
• •Polling attempts
• •Response file detection
• •Cleanup operations

Error Handling

The script provides clear error messages for common issues:

Unity Not Running:

Error: Unity Editor not detected. Ensure Unity is open with the project loaded.

Command Timeout:

Error: Command timed out after 30s. Check Unity Console for errors.

Invalid Parameters:

Error: Failed to write command file: Invalid mode 'InvalidMode'

Exit Codes:

• •0 - Success
• •1 - Error (Unity not running, invalid params, etc.)
• •2 - Timeout

Integration with Claude Code

When you're working in a Unity project directory, you can ask Claude Code to perform Unity operations naturally:

• •"Run the Unity tests in EditMode"
• •"Check if there are any compilation errors"
• •"Show me the last 10 error logs from Unity"
• •"Refresh the Unity asset database"

Claude Code will automatically use this skill to execute the commands via the Python script.

File Protocol Details

Command Format

Written to .unity-bridge/command.json:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "action": "run-tests",
  "params": {
    "testMode": "EditMode",
    "filter": "MyTests"
  }
}

Response Format

Read from .unity-bridge/response-{id}.json:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success",
  "action": "run-tests",
  "duration_ms": 1250,
  "result": {
    "passed": 410,
    "failed": 0,
    "skipped": 0,
    "failures": []
  }
}

Status Values:

• •running - Command in progress (may see intermediate responses)
• •success - Command completed successfully
• •failure - Command completed with failures (e.g., failed tests)
• •error - Command execution error

Project Structure

skill/
├── SKILL.md                    # This file
├── pyproject.toml              # Package configuration
├── src/
│   └── claude_unity_bridge/
│       ├── __init__.py         # Package version
│       └── cli.py              # CLI implementation
├── tests/
│   └── test_cli.py             # Unit tests
└── references/
    ├── COMMANDS.md             # Detailed command specifications
    └── EXTENDING.md            # Guide for adding custom commands

Detailed Documentation

For more information, see:

• •COMMANDS.md - Complete command reference with all parameters, response formats, and edge cases
• •EXTENDING.md - Tutorial for adding custom commands to the Unity Bridge for project-specific workflows

Troubleshooting

Unity Not Responding

Symptoms: Commands timeout or "Unity not detected" error

Solutions:

1. •Ensure Unity Editor is open with the project loaded
2. •Check that the package is installed (Window > Package Manager)
3. •Verify .unity-bridge/ directory exists in project root
4. •Check Unity Console for errors from ClaudeBridge package

Response File Issues

Symptoms: "Failed to parse response JSON" error

Solutions:

1. •Check Unity Console for ClaudeBridge errors
2. •Manually inspect .unity-bridge/response-*.json files
3. •Try cleaning up old responses with --cleanup flag
4. •Restart Unity Editor if file system is in bad state

Performance Issues

Symptoms: Slow response times, frequent timeouts

Solutions:

1. •Increase timeout with --timeout 60 or higher
2. •Close unnecessary Unity Editor windows
3. •Reduce test scope with --filter parameter
4. •Check system resources (CPU, memory)

File Locking Errors

Symptoms: Intermittent errors reading/writing files

Solutions:

1. •The CLI handles file locking automatically with retries
2. •If persistent, check for antivirus interference
3. •Verify file permissions on .unity-bridge/ directory

Installation

Install the CLI

pip install claude-unity-bridge

Or for development:

cd claude-unity-bridge/skill
pip install -e ".[dev]"

Verify Setup

unity-bridge health-check

Install the Skill (Optional)

To use this skill in Claude Code:

1. •

   Symlink the skill directory:

   bash

   ln -s "$(pwd)/skill" ~/.claude/skills/unity
   

2. •

   Restart Claude Code to load the skill

3. •

   Navigate to your Unity project directory in Claude Code

4. •

   Ask Claude to perform Unity operations naturally

Why a CLI Tool?

The skill uses a CLI tool instead of implementing the protocol directly in Claude Code prompts for several critical reasons:

Consistency: UUID generation, polling logic, and error handling work identically every time. Without the CLI, Claude might implement these differently across sessions, leading to subtle bugs.

Reliability: All edge cases are handled once in tested code:

• •File locking when Unity writes responses
• •Exponential backoff for polling
• •Atomic command writes to prevent corruption
• •Graceful handling of malformed JSON
• •Proper cleanup of stale files

Error Messages: Clear, actionable error messages for all failure modes. Claude doesn't have to figure out what went wrong each time.

Token Efficiency: The CLI handles complexity, so Claude doesn't need to manage low-level details in-context. The SKILL.md stays concise while providing full functionality.

Deterministic Exit Codes: Shell integration works reliably with standard exit codes (0=success, 1=error, 2=timeout).

Rock Solid: Test the CLI once, it works forever. No variability between Claude sessions.

Support

For issues or questions:

• •Package Issues: https://github.com/ManageXR/claude-unity-bridge/issues
• •Skill Issues: Report in the same repository with [Skill] prefix