codex-unity-bridge 0.3.0

Control Unity Editor from Codex

---

name: unity description: Execute Unity Editor commands through Codex Unity Bridge. Requires the com.prodfact.codex-bridge Unity package in the current project and a running Unity Editor.

Unity Bridge Skill

Use this skill when Codex needs to interact with a live Unity Editor from the project workspace.

Overview

Codex Unity Bridge uses a deterministic Python CLI instead of ad-hoc in-context file handling. The CLI owns:

• UUID generation
• atomic command writes
• polling and timeout handling
• response parsing
• cleanup of stale files
• skill installation

That keeps Unity interactions stable across sessions and avoids re-implementing the file protocol each time.

Requirements

1. The Unity project has com.prodfact.codex-bridge installed
2. Unity Editor is open with that project loaded
3. The project root contains .codex-unity-bridge/ after the package initializes
4. The CLI is installed: codex-unity-bridge

Runtime Files

• Command file: .codex-unity-bridge/command.json
• Response files: .codex-unity-bridge/response-{id}.json

This is intentionally separate from the original Claude bridge runtime directory so both bridges can coexist in the same Unity project.

Basic Usage

Run the CLI directly:

codex-unity-bridge [command] [options]

Common commands:

codex-unity-bridge run-tests --mode EditMode
codex-unity-bridge compile
codex-unity-bridge refresh
codex-unity-bridge get-status
codex-unity-bridge get-console-logs --limit 20 --filter Error
codex-unity-bridge play
codex-unity-bridge pause
codex-unity-bridge step
codex-unity-bridge health-check

Natural-Language Examples

Typical prompts that map well to this skill:

• Run the Unity tests in EditMode
• Check whether Unity is compiling
• Show the last 10 Unity errors
• Refresh the Unity asset database
• Pause play mode and step one frame

Guidance

• Prefer the CLI over manual edits to bridge files
• Use --timeout for long-running test or compile operations
• Use get-status or health-check before assuming Unity is unavailable
• Use get-console-logs --filter Error before asking for a broad log dump

Troubleshooting

If Codex cannot communicate with Unity:

1. Verify the Unity Editor is open with the intended project
2. Check that .codex-unity-bridge/ exists at the project root
3. Run codex-unity-bridge health-check
4. Inspect the Unity Console for [CodexBridge] messages

If the CLI is not on PATH, run:

python -m codex_unity_bridge.cli install-skill

References

• Command Reference
• Extending the Bridge