{"id":49560490,"url":"https://github.com/yhc509/unity-cli-bridge","last_synced_at":"2026-05-07T00:03:05.879Z","repository":{"id":345287901,"uuid":"1184883382","full_name":"yhc509/unity-cli-bridge","owner":"yhc509","description":"Drive the Unity Editor from your terminal over local IPC — no port wiring, no manual server startup.","archived":false,"fork":false,"pushed_at":"2026-05-03T07:12:16.000Z","size":916,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T07:27:28.278Z","etag":null,"topics":["ai-agents","automation","claude-code","codex","developer-tools","dotnet","unity","unity-editor"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yhc509.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-18T02:51:08.000Z","updated_at":"2026-05-03T07:12:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yhc509/unity-cli-bridge","commit_stats":null,"previous_names":["yhc509/puc","yhc509/kinkeep-unity-cli","yhc509/unity-cli-bridge"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/yhc509/unity-cli-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhc509%2Funity-cli-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhc509%2Funity-cli-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhc509%2Funity-cli-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhc509%2Funity-cli-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yhc509","download_url":"https://codeload.github.com/yhc509/unity-cli-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhc509%2Funity-cli-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32716960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T19:35:05.142Z","status":"ssl_error","status_checked_at":"2026-05-06T19:35:03.996Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","claude-code","codex","developer-tools","dotnet","unity","unity-editor"],"created_at":"2026-05-03T08:02:20.475Z","updated_at":"2026-05-07T00:03:05.859Z","avatar_url":"https://github.com/yhc509.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# unity-cli-bridge\n\nControl the Unity Editor from the command line. No manual server startup, no port management — the bridge starts when the Editor opens, and the CLI finds the right project automatically.\n\n## Design Philosophy\n\nMost Unity automation tools fall into two camps:\n\n**MCP mega-tools** wrap dozens of actions behind a Python/Node intermediary. Every call hops through AI → MCP server → HTTP → Unity plugin. More moving parts, more latency, more failure modes.\n\n**Dynamic code execution** sends raw C# to Unity and reads results from Debug.Log. Infinitely flexible, but the LLM must generate correct C# every time, and reading results requires a second call.\n\n**unity-cli-bridge takes a third path: declarative commands over direct IPC.**\n\n```\nCLI ──── local IPC ──── Unity Editor (bridge)\n         (Named Pipe on Windows, Unix socket on macOS/Linux)\n```\n\n- **One hop, no intermediary.** CLI talks directly to the Editor over local IPC. Average response: 265 ms.\n- **Declarative, not imperative.** `scene add-object --primitive Cube --position 3,0,0` instead of writing C# code. The LLM picks options, not APIs.\n- **Token-aware responses.** `--output compact` strips envelope metadata. `--omit-defaults` cuts material info by 71% and scene inspect by 41%.\n- **Structured results in stdout.** No polling, no log scraping, no file reads. Every command returns JSON immediately.\n- **Fail fast, fail loud.** Invalid options get a clear error. Unrecognized patch keys return warnings instead of silent success.\n\n\u003e See [Benchmark: 3-Way Comparison](https://github.com/yhc509/unity-cli-bridge/wiki/Benchmark-Unity-Editor-CLI-Tool-Comparison) for measured results against two other approaches on the same scenario.\n\n## Quick Start\n\n### 1. Add the Unity Package\n\n**Option A: Unity Package Manager**\n\nIn Unity, open Package Manager and choose **Add package from git URL**. Paste:\n\n```\nhttps://github.com/yhc509/unity-cli-bridge.git?path=/unity-package/com.yhc509.unity-cli-bridge#main\n```\n\n**Option B: Edit `Packages/manifest.json` manually**\n\nAdd the following to your `Packages/manifest.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"com.yhc509.unity-cli-bridge\": \"https://github.com/yhc509/unity-cli-bridge.git?path=/unity-package/com.yhc509.unity-cli-bridge#main\"\n  }\n}\n```\n\nThe bridge starts automatically when the Editor opens. No configuration needed.\n\n### 2. Install the CLI\n\n**Option A: From Unity Editor** (recommended)\n\nOpen `Window \u003e Unity CLI Manager` in the Editor menu. Click **Install CLI** — the correct binary is downloaded automatically to `~/.unity-cli-bridge/unity-cli/`.\n\n**Option B: Manual download**\n\nDownload from [GitHub Releases](https://github.com/yhc509/unity-cli-bridge/releases):\n\n| Platform | File |\n|----------|------|\n| macOS (Apple Silicon) | `unity-cli-osx-arm64.tar.gz` |\n| Windows (x64) | `unity-cli-win-x64.zip` |\n\nExtract and add the binary to your PATH.\n\n\u003e **Tip:** A short, fixed install path (`~/.unity-cli-bridge/unity-cli/`) saves tokens when AI agents invoke the CLI repeatedly — every character in the path is repeated on each call.\n\n### 3. Install AI Agent Skill\n\nIn the Unity Editor, open `Window \u003e Unity CLI Manager`. Select your AI tool (Claude Code or Codex) from the dropdown and click **Install Skill**.\n\n| Tool | Install Path |\n|------|-------------|\n| Claude Code | `~/.claude/skills/unity-cli-bridge/` |\n| Codex | `~/.codex/skills/unity-cli-bridge/` |\n\nThe skill teaches AI agents how to pick the right commands, run them safely, and verify results with `read-console`.\n\n### 4. Verify\n\nCheck that the CLI can reach the running Editor:\n\n```bash\nunity-cli status --project /path/to/your-project --json\n```\n\n## What You Can Do\n\n### Editor Control\n\n```bash\nunity-cli status --project MyGame          # Editor state, Unity version, current scene\nunity-cli play / pause / stop              # Play Mode control\nunity-cli compile                          # Trigger recompile\nunity-cli screenshot --path /tmp/shot.png  # Game View capture (default), or --view scene\nunity-cli read-console --type error        # Check for errors after any operation\nunity-cli execute-menu --list \"GameObject\" # Browse Unity menus\nunity-cli execute --code \"Debug.Log(1);\" --force  # Run arbitrary C# (escape hatch)\nunity-cli execute --code \"Debug.Log(__pucArgsJson);\" --args '{\"k\":\"v\"}' --force\n```\n\n`execute --args` exposes the supplied JSON as `__pucArgsJson`; do not declare variables with the reserved `__puc_internal_*` prefix in user code. Avoid putting secrets or credentials in `--args`, because CodeDOM compilation can briefly create temporary `.cs` files under the OS temp directory.\n\n### Assets\n\n```bash\nunity-cli asset find --type Material                    # Find by type\nunity-cli asset find --name Player --type Prefab        # Find by name + type\nunity-cli asset info --path Assets/Scenes/Main.unity    # Asset metadata\nunity-cli asset create --type material --path Assets/Materials/Red  # Create\nunity-cli asset mkdir --path Assets/NewFolder            # Create folder\nunity-cli asset move --from ... --to ... --force         # Move/rename\nunity-cli asset delete --path ... --force                # Delete\n```\n\n### Scenes\n\n```bash\n# Open and inspect\nunity-cli scene open --path Assets/Scenes/Main.unity\nunity-cli scene inspect --path ... --with-values --omit-defaults\n\n# Build scenes with convenience commands\nunity-cli scene add-object --name Cube --primitive Cube \\\n  --parent \"/Environment[0]\" --position 3,0,0\n# → Response includes createdPath — no follow-up inspect needed\n\nunity-cli scene set-transform --node \"/Cube[0]\" --position 0,1,0 --scale 2,2,2\nunity-cli scene assign-material --node \"/Cube[0]\" --material Assets/Materials/Red.mat\n\n# Component operations\nunity-cli scene list-components --node \"/Cube[0]\"\nunity-cli scene add-component --path Assets/Scenes/Main.unity --node \"/Player[0]\" --type Rigidbody --values '{\"mass\":5}'\nunity-cli scene remove-component --path Assets/Scenes/Main.unity --node \"/Player[0]\" --type BoxCollider --index 0 --force\n\n# Or use spec-based patching for complex edits\nunity-cli scene patch --path ... --spec-file patch.json\n```\n\n### Prefabs\n\n```bash\nunity-cli prefab create --path Assets/Prefabs/Enemy.prefab \\\n  --spec-json '{\"root\":{\"name\":\"Enemy\",\"children\":[...]}}'\nunity-cli prefab inspect --path ... --with-values\nunity-cli prefab patch --path ... --spec-json '{\"operations\":[...]}'\nunity-cli prefab patch --path ... --spec-file destructive-patch.json --force\n\n# Component operations\nunity-cli prefab list-components --path Assets/Prefabs/Player.prefab --node \"/Root[0]\"\nunity-cli prefab add-component --path Assets/Prefabs/Player.prefab --node \"/Root[0]\" --type Rigidbody --values '{\"mass\":5}'\nunity-cli prefab remove-component --path Assets/Prefabs/Player.prefab --node \"/Root[0]\" --type BoxCollider --force\n```\n\nPatch ops: `add-child`, `remove-node`, `set-node`, `add-component`, `remove-component`, `set-component-values`\n\nFriendly component keys are available in scene/prefab value patches for common Unity components:\n- Rigidbody: `mass`, `damping`, `angularDamping`, `useGravity`, `isKinematic`, `constraints`\n- Collider family: `isTrigger`, `material`, `contactOffset`, plus `size`, `radius`, `height`, `mesh`, `convex`\n- Renderer family: `materials`, `materials[0]`, `receiveShadows`, `shadowCastingMode`, `lightProbeUsage`\n- Light: `color`, `intensity`, `range`, `type`, `shadows`, `shadowStrength`\n- Camera: `fieldOfView`, `nearClipPlane`, `farClipPlane`, `backgroundColor`, `orthographicSize`\n\n### Materials\n\n```bash\nunity-cli material info --path Assets/Materials/Red.mat --omit-defaults\nunity-cli material set --path ... --property _BaseColor --value 1,0,0,1\nunity-cli material set --path ... --texture _MainTex --asset Assets/Textures/wood.png\n```\n\n### Packages\n\n```bash\nunity-cli package list\nunity-cli package add --name com.unity.inputsystem\nunity-cli package remove --name ... --force\nunity-cli package search --query \"input\"\n```\n\nPackage Manager commands use a 360-second CLI live timeout so the bridge can return its 300-second `PACKAGE_TIMEOUT` response. They are single-flight inside the Editor; a second package command returns `PACKAGE_BUSY` until the active request completes.\n\n### Play Mode QA\n\n```bash\nunity-cli qa click --qa-id StartButton\nunity-cli screenshot --view game --path /tmp/qa-reference.png\nunity-cli qa tap --x 400 --y 300\nunity-cli qa swipe --from 100,200 --to 300,400\nunity-cli qa swipe --target ... --from 0,0 --to 100,0 --duration 500\nunity-cli qa key --key space\nunity-cli qa wait-until --scene GameScene --timeout 5000\n```\n\n`screenshot` responses include both image size (`width`/`height`) and live input metadata (`screenWidth`/`screenHeight`, `imageOrigin=top-left`, `coordinateOrigin=bottom-left`). `qa tap` takes screenshot image coordinates as-is, reuses the last successful `screenshot` dimensions when `--screenshot-width`/`--screenshot-height` are omitted, and lets the bridge handle Y-flip plus resolution scaling into Unity screen space. See [qa-testing.md](tools/skills/unity-cli-operator/references/qa-testing.md) for the coordinate workflow.\n\n## Token Optimization\n\nFor AI agent workflows, minimize token consumption:\n\n```bash\n# --output compact: strip envelope metadata, return data payload only\nunity-cli asset info --path ... --output compact\n\n# --omit-defaults: strip default/identity values from inspect and material responses\nunity-cli scene inspect --path ... --with-values --omit-defaults    # 41% smaller\nunity-cli material info --path ... --omit-defaults                  # 71% smaller\n\n# --max-depth: limit hierarchy traversal depth\nunity-cli scene inspect --path ... --max-depth 2\n```\n\n## Repository Structure\n\n```\ncli/UnityCli.Cli/              CLI executable (.NET 9, macOS arm64 + Windows x64)\ncli/UnityCli.Protocol/         Shared protocol (linked from Unity package)\nunity-package/                 com.yhc509.unity-cli-bridge (UPM package)\ntools/skills/unity-cli-operator/   AI agent skill (dev copy; end-users install via CLI Manager)\ntests/                         xUnit CLI tests + live IPC test scenarios\ndocs/                          Generated CLI reference, specs\n```\n\n## Safety Rules\n\n- **Destructive or dangerous ops require `--force`:** `asset delete`, `execute`, `package remove`, `scene remove-component`, `prefab remove-component` (always); `asset move` / `asset rename` / `asset create` when overwriting an existing path; destructive operations inside `scene patch` (`delete-gameobject`, `remove-component`) and `prefab patch` (`remove-node`, `remove-component`).\n- **Raw force payloads are explicit:** `raw --force` only injects `force=true` when the payload omits `force` or already sets it to `true`; conflicting payload values fail fast.\n- **Patch and overwrite rollback:** Scene/prefab patch and asset overwrite flows create backups for the asset body and `.meta` under `Library/com.yhc509.unity-cli-bridge/backups/`, keeping rollback files outside `Assets/` and normal git tracking.\n- **Dirty scene patch refusal:** `scene patch` refuses a target scene that is already loaded with unsaved changes, even with `--force`; save or discard the scene first.\n- **Asset paths:** Write operations are `Assets/...` only. Reads allow `Packages/...` too.\n- **Package Manager requests:** `package list`, `package add`, `package remove`, and `package search` use a longer live timeout and return `PACKAGE_BUSY` if another package command is already running.\n- **Scene paths:** `/Root[0]/Child[0]` format with sibling indices. `/` is the virtual scene root.\n- **Inspect before patch:** Always `scene inspect --with-values` or `prefab inspect --with-values` before writing patch specs.\n- **Friendly component keys:** Common Rigidbody, Collider, Renderer, Light, and Camera patch keys are resolved to Unity `SerializedProperty.propertyPath` values.\n- **set-node warnings:** Unrecognized keys now return warnings instead of silent success.\n\n## Documentation\n\n- [CLI Reference (generated)](docs/cli-reference.md)\n- [Architecture](docs/architecture.md)\n- [Scene Spec](docs/scene-spec.md)\n- [Prefab Spec](docs/prefab-spec.md)\n- [Benchmark](https://github.com/yhc509/unity-cli-bridge/wiki/Benchmark-Unity-Editor-CLI-Tool-Comparison)\n- [Unity Package](unity-package/com.yhc509.unity-cli-bridge/README.md)\n\n## AI Agent Skill\n\nThe `unity-cli-bridge` skill teaches AI agents how to use the CLI safely: pick the right command, verify with `read-console`, follow inspect-before-patch patterns.\n\nInstall from **Window \u003e Unity CLI Manager** in the Unity Editor — select your AI tool and click **Install Skill**. Supports Claude Code and Codex.\n\n## Development\n\n```bash\ndotnet build UnityCliBridge.sln -c Debug\ndotnet test UnityCliBridge.sln\ndotnet run --project cli/UnityCli.DocGen -- --check   # Verify docs match code\n```\n\n## Current Limits\n\n- macOS arm64 and Windows x64 supported\n- Live IPC required — commands fail fast when no Editor is running\n- Scene patching targets saved `Assets/...unity` scenes; multi-scene orchestration is out of scope\n- Prefab-internal object references and nested variants are not yet supported\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhc509%2Funity-cli-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyhc509%2Funity-cli-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhc509%2Funity-cli-bridge/lists"}