---
name: Locus Unity Bridge
slug: locus-unity-bridge
category: AI Engineering
description: "Locus Unity Bridge probes a Unity project for a Locus connection and then sends commands, executes C# in the Editor, or triggers recompilation. Use it when an agent needs direct Unity Editor access through Locus."
github: "https://github.com/Misaka-Mikoto-Tech/agent-skills/tree/main/skills/locus-unity-bridge"
language: PowerShell
stars: 243
forks: 10
install: "npx degit https://github.com/Misaka-Mikoto-Tech/agent-skills/tree/main/skills/locus-unity-bridge ~/.claude/skills/locus-unity-bridge"
installs_to: ~/.claude/skills/locus-unity-bridge
source_path: skills/locus-unity-bridge/SKILL.md
collection_size: 3
category_size: 2631
collection_url: "https://dirskills.com/collections/Misaka-Mikoto-Tech/agent-skills"
added: 2026-09-02T05:21:47.964Z
last_synced: 2026-09-02T05:21:47.964Z
canonical_url: "https://dirskills.com/skills/locus-unity-bridge"
---

# Locus Unity Bridge

Locus Unity Bridge probes a Unity project for a Locus connection and then sends commands, executes C# in the Editor, or triggers recompilation. Use it when an agent needs direct Unity Editor access through Locus.

**Install:**

```bash
npx degit https://github.com/Misaka-Mikoto-Tech/agent-skills/tree/main/skills/locus-unity-bridge ~/.claude/skills/locus-unity-bridge
```

## README

# 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

1. Resolve the script relative to this skill:

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

2. Probe the target project before any Unity operation:

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

3. 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:

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

Example snippet:

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

Send a protocol message:

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

Request compilation and wait across domain reload:

```powershell
& 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`.