Locus Unity Bridge Agent Skill

Locus Unity Bridge

Use the bundled PowerShell client instead of rewriting named-pipe code. Locus

uses UTF-8 JSON Lines and may emit events before a response; the client waits

for the envelope whose reply_to matches its request ID.

Safety boundary

execute_code has arbitrary Unity Editor authority. Use it only for the

project and task the user authorized.

Do not install/copy the Locus package, create its marker, launch/close Unity,

or modify a project merely to make the bridge connect. Diagnose first and ask

for authorization if setup changes are required.

Workflow

• Resolve the script relative to this skill:

   $locusBridge = Join-Path $env:USERPROFILE '.agents\skills\locus-unity-bridge\scripts\locus-unity.ps1'

• Probe the target project before any Unity operation:

   & pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
       -Command probe -ProjectPath 'E:\Source\SomeUnityProject'

• Read the returned Status:

| Status | Meaning and next action |

|---|---|

| connected | Use execute, send, or recompile. |

| package_missing | Locus is not installed. Report the expected package Packages/com.farlocus.locus; request permission before installation. |

| package_invalid | A candidate folder exists without Editor/Locus.Editor.asmdef; report the incomplete path. |

| bridge_not_enabled | Package exists, but no marker or reachable computed pipe exists. Ask the user to enable/connect Locus for this project. |

| editor_unreachable | A marker exists, but its pipe is unavailable. Verify that the matching project is open in Unity and Locus is active. |

The probe supports the canonical package plus legacy Assets/Locus and

Assets/Plugins/Locus layouts. It also handles

LOCUS_UNITY_NATIVE_BRIDGE=1, where no marker may exist but the computed pipe

is live.

Commands

Execute multi-line C# from a file. Use print(...) or printJson(...) to

return data:

& pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
    -Command execute -ProjectPath 'E:\Source\SomeUnityProject' `
    -CodeFile 'C:\Temp\inspect-scene.cs' -TimeoutSeconds 30

Example snippet:

print(UnityEngine.SceneManagement.SceneManager.GetActiveScene().path);

Send a protocol message:

& pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
    -Command send -ProjectPath 'E:\Source\SomeUnityProject' `
    -MessageType status -Message ''

Request compilation and wait across domain reload:

& pwsh.exe -NoLogo -NoProfile -NonInteractive -File $locusBridge `
    -Command recompile -ProjectPath 'E:\Source\SomeUnityProject' `
    -TimeoutSeconds 10 -RecompileTimeoutSeconds 120

All successful commands print JSON. A failed transport or Unity response exits

nonzero and preserves the useful error text.

Common mistakes

• Do not treat the first pipe line as the response; unsolicited

unity-editor-update events have no matching reply_to.

• Do not run against the Locus source checkout when the requested Unity project

is elsewhere.

• Do not assume Unity MCP is required; this skill talks directly to Locus.
• Do not infer package installation from a running Unity process; trust

probe.