Unity's Official Codex and Claude Code Plugin: Setup and Safe Workflows

The hardest problem when using a coding agent on a Unity project is rarely a complete lack of code. It is code that looks plausible while mixing current APIs with habits from older Unity releases. Unity's new official plugins for Claude Code and Codex try to reduce that problem by giving agents first-party, task-specific skills maintained by the Unity teams that own those features.

This guide explains where the plugin is installed, how to verify it, how the Codex and Claude Code editions differ, how to write useful requests, and what still needs human review. It is based on Unity's public documentation and announcements checked on September 23, 2026. It does not claim results from running the plugin on a production project.

Short version
The Unity plugin is not an Asset Store package. It is a collection of agent skills for Unity 6.0 and later. The Codex release starts with 31 skills and Unity CLI workflows; Unity's official forum explicitly says it is not an MCP server. The Claude Code release starts with 29 skills and includes Unity CLI workflows that can work with a live Editor. In both cases, you still need source control, clear permissions, and your own verification criteria.

What changed: official work instructions sit in front of general model knowledge

A general coding agent has encountered many generations of Unity tutorials, forum answers, and sample projects. That breadth is useful, but it can also produce a renderer feature that compiles and never runs, choose the wrong UI system, or reproduce an asset workflow that no longer matches Unity 6.

The official plugin does not solve this by introducing a new model. It supplies focused instructions for recurring Unity jobs: UI Toolkit and uGUI, 2D and tilemaps, URP and Shader Graph, audio, physics, multiplayer, in-app purchases, LevelPlay, web optimization, and localization. When a request matches one of those jobs, the agent can load the relevant skill rather than relying only on broad prior knowledge.

Unity also recommends asking the agent to read a skill's references/ files when a result looks wrong. The useful mental model is not “the agent now knows all of Unity.” It is “the agent can open a current Unity playbook before it plans a specific change.”

A safer workflow separates the request, official skills, execution tools, and verification.

Codex and Claude Code do not have identical operating boundaries

Item	Codex	Claude Code
Announcement	September 16, 2026	September 9, 2026
Initial skills	31	29
Install surface	Codex CLI or plugin directory	Claude Code session/CLI or Claude desktop
Editor connection	Skills package; Unity says it is not an MCP server	Unity CLI skill supports live Editor workflows
Shared requirement	Unity 6.0 or later, plus project-specific review

Do not choose between them by counting skills alone. The Codex version includes tasks such as planning a Built-in Render Pipeline to URP migration. Claude Code lets you choose user, project, or local installation scope, which matters when a team wants to share one standard through a repository. Your existing agent, collaboration model, and need for live Editor operations are more important than the raw number.

Prepare the project before installing anything

1. Confirm the Unity version. The plugin requires Unity 6.0 or later. For an older LTS project, an upgrade plan and package compatibility review come first.
2. Isolate changes. Create a branch or a disposable project copy. Make sure you can distinguish generated folders from source assets, scenes, prefabs, settings, and code that must be reviewed.
3. Update the agent. Verify that your Codex build supports plugin commands or that Claude Code recognizes /plugin.
4. Write completion criteria. Compilation is not enough. Decide which play-mode behavior, tests, console messages, scenes, prefabs, platforms, or builds determine success.
5. Separate secrets. Identify payment keys, signing material, service accounts, ad credentials, and analytics tokens. Define which paths the agent may read and which must stay out of scope.

Install and verify the Unity plugin in Codex

Add Unity's marketplace, then add the plugin from a terminal:

codex plugin marketplace add Unity-Technologies/unity-agent-plugin
codex plugin add unity@unity-agent-plugin

Start a new Codex session after installation. Enter /unity: and confirm that Unity skills appear in the slash menu. Then check the installed and enabled state from the terminal:

codex plugin list

Use codex plugin marketplace upgrade unity-agent-plugin to update and codex plugin remove unity@unity-agent-plugin to remove it. Unity's official forum describes the Codex edition as a skills package rather than an MCP server, so do not assume that it can directly control a running Editor. Keep file and CLI operations separate from checks that you perform in the Editor.

The installation and verification commands in Unity Docs, checked September 23, 2026.

Choose the right scope when installing in Claude Code

Inside a Claude Code session, enter these as slash commands:

/plugin marketplace add Unity-Technologies/unity-agent-plugin
/plugin install unity@unity-agent-plugin

Choose user scope if you work across several Unity projects, project scope if the repository should share the plugin as a team standard, or local scope if you are testing it privately in the current repository. A terminal installation limited to the current repository looks like this:

claude plugin install unity@unity-agent-plugin --scope local

Use /unity: to check the skills and /plugin to confirm that unity is enabled. If marketplace auto-update is disabled, refresh it with /plugin marketplace update unity-agent-plugin. When skills do not appear, Unity's troubleshooting sequence is to check the Claude Code version, restart the terminal, and, if necessary, clear the plugin cache before reinstalling.

Three practical jobs to delegate

1. Build a settings screen without letting the agent guess the UI system

“Build a settings screen” leaves an important architectural choice open. For a new Unity 6 project, name UI Toolkit, the desired controls, and the point where the agent must stop:

Add a UI Toolkit settings screen to this Unity 6 project.
Include audio volume and subtitle size only.
Inspect the existing scene structure first.
Read the relevant Unity skill references and show the change plan.
List every UXML, USS, and C# file you will touch, then stop before play-mode verification.

Review more than whether the screen is visible. Check the UIDocument and PanelSettings connections, persistence, keyboard or controller navigation, and compatibility with any existing UI system.

2. Fix missing Korean, Chinese, or Japanese glyphs with project constraints

When TextMeshPro renders boxes, include the current font asset, target languages, memory limits, platform, and whether dynamic fallback atlases are allowed. Explicitly invoke /optimize-text-mesh-pro if automatic skill selection fails. Ask the agent to inventory the existing assets before proposing fallback fonts, padding, sampling ratios, or atlas changes. Verify the result with representative strings and the target build, not only in an Editor preview.

3. Migrate from BIRP to URP in checkpoints

The Codex skill covers materials and shaders, pink-material failures, 2D URP, lighting, baked lightmaps, reflection probes, and post-migration visual issues. That checklist is useful, but it is not a reason to convert a large project in one turn. Prepare packages and renderer assets, migrate one representative scene, classify custom shaders, compare visuals, and expand only after the first checkpoint passes. Commit between stages so regressions remain traceable.

Use a four-part request: task, constraints, verification, stop points

• Task: State the one change you want.
• Constraints: Name the Unity version, UI system, render pipeline, target platform, and protected paths.
• Verification: Specify compilation, tests, console logs, visual comparison, or build output.
• Stop points: Require approval before package installation, mass file edits, project upgrades, payment configuration, or deployment changes.

If the agent does not select the right skill, name it explicitly. If the plan looks outdated, tell the agent to read that skill's references/ files and rebuild the plan from those instructions. Unity also warns that clarification questions can block unattended pipelines. For automation, provide defaults, platforms, allowed changes, and decision rules in the initial request.

Permissions, pricing, and security are still separate decisions

Unity describes the plugin as first-party, maintained by its feature teams, and security reviewed. Codex and Claude Code remain third-party products, however. Installing Unity's plugin does not replace their terms, subscription or API costs, data-handling rules, or your Unity license. Unity's documentation does not promise that all related usage is free, so check the plan and account you already use.

In-app purchases, LevelPlay advertising, multiplayer, and live services are especially sensitive. Product IDs, receipt validation, consent flows, ATT, server permissions, and production credentials cannot be reduced to generated code. Give the agent the minimum access it needs. Keep irreversible actions such as creating live products, rotating deployment keys, or changing production consoles behind human review.

Troubleshooting in a useful order

1. The plugin command is unknown: update Codex or Claude Code, restart the terminal, and open a fresh session.
2. The plugin is installed but no skills appear: check both /unity: and the plugin list. Claude Code may require a cache reset and reinstall.
3. The agent chooses the wrong UI approach: name UI Toolkit or uGUI in the first sentence.
4. The answer resembles an older Unity workflow: ask it to read the relevant skill and reference files before replanning.
5. An automated run stops for questions: add the target platform, defaults, change limits, and actions that may proceed without approval.
6. A simple uGUI task shows little benefit: Unity's own documentation says the plugin may make little difference for simple uGUI work. Start with rendering, localization, monetization, or migration jobs where current guidance and a checklist matter more.

Who should use it now?

The plugin is most useful for Unity 6 teams that already use an agent and repeatedly encounter mixed-version APIs, ambiguous UI choices, or complex setup checklists. New-project setup, URP review, multilingual fonts, package management, IAP, and service integration are good candidates.

Adoption is less straightforward for pre-Unity 6 projects, tightly isolated networks, organizations that cannot expose project files to a third-party agent, or teams that already maintain rigorous internal skills and validation pipelines. In those cases, the official repository can still be a useful reference, but installation should follow the organization's security and change-management review.

Our earlier Diagram Design guide covered adding a visualization capability to Claude Code or Codex. The Unity plugin is a different pattern: it adds first-party domain instructions. Both are most effective when the desired output and verification method are defined before the agent starts changing files.

Official sources

• Unity Docs: About Unity's plugin
• Unity Docs: Unity's plugin for Codex
• Unity Docs: Unity's plugin for Claude Code
• Unity Blog: The Official Unity Plugin for Codex

Sources checked September 23, 2026. Plugin and beta documentation can change, so verify the latest commands and supported scope before installation.

Read in another language
한국어로 읽기