How to use Codex with Unity

Short answer: open your Unity project folder in OpenAI Codex, keep the Unity Editor open, and let Codex edit C# scripts under Assets/. Unity recompiles, you read the Console, and you run tests. When you want more, Unity publishes an official plugin for Codex, and the free Unity CLI can connect Codex to the Editor with one command, unity mcp configure codex. Everything below comes from Unity and OpenAI docs, checked October 20, 2026.

What you are connecting

• OpenAI Codex. OpenAI's coding agent. It runs in the ChatGPT desktop app, a terminal CLI and an IDE extension, and it can read and edit the files in the folder you give it. Docs: Codex CLI.
• Unity's official plugin for Codex. Adds Unity's own skills to Codex so it follows Unity's current guidance instead of guessing. Unity says the skills cover areas like UI Toolkit and uGUI, 2D and sprites, URP and Shader Graph, audio, physics, multiplayer and more. Docs: Unity's plugin for Codex.
• The Unity CLI. A free command-line tool from Unity. With the Unity Pipeline package in your project it can drive a running Editor, and unity mcp runs an MCP server for agents. MCP (Model Context Protocol) is a standard way to give an agent tools inside another app. Docs: Use the Unity CLI.
• Community option: CoplayDev/unity-mcp (MCP for Unity, MIT license). Community software, not from Unity Technologies. Its README lists Codex among supported assistants and Unity 2021.3 LTS through 6.x.

Heads up if you read older tutorials: Unity has deprecated the MCP server that ships inside the in-editor AI assistant package (com.unity.ai.assistant). Unity's docs say the Unity CLI replaces it (Unity CLI as the replacement for the in-Editor MCP server). Third-party MCP packages from GitHub are not affected.

What you need

• Unity 6.0 or newer for the official plugin and for the CLI to drive a running Editor (Unity says 6.0 LTS or later). Get it from unity.com/download via Unity Hub. Older Editors still work with the plain file edit loop.
• Codex. ChatGPT Free and Go ($8/mo) include limited Codex in the desktop app, subject to rollout. The CLI and IDE extension start with Plus at $20/mo, per OpenAI's Codex pricing (checked October 20, 2026).
• Git, so you can undo a bad change with one command.
• For the Unity CLI: Windows 10 21H1 or newer, macOS 14 or newer, or Ubuntu 22.04 / RHEL 9 or newer, per Unity's CLI docs. The CLI itself is free and does not need a Unity AI subscription.

The realistic workflow (plugin and MCP optional)

1. Codex edits C# directly under Assets/, plus test folders when you ask.
2. The Unity Editor stays open on the same project, so scripts recompile and errors show up in the Console.
3. You read the Console and paste errors back to Codex. With the Unity CLI connected, Codex can check the Editor itself.
4. You run tests with the Unity Test Framework in batch mode, starting with Edit Mode tests.
5. You playtest. No agent can tell you if the jump feels good.

Setup, step by step

1. Create a Unity project and commit it

In Unity Hub, install a Unity 6 Editor and create a 2D or 3D project in its own folder. Open it once so Unity creates Assets/, ProjectSettings/ and the .meta files. Then, in a terminal inside that folder, run git init, add a .gitignore like this one (never ignore *.meta), and make a first commit:

# Unity generated
/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Bb]uild/
/[Bb]uilds/
/[Ll]ogs/
/[Uu]ser[Ss]ettings/
*.csproj
*.sln
*.user
*.pidb
*.pdb
*.mdb

OpenAI's own Codex docs recommend Git checkpoints before and after each task so you can revert changes. Do that every time.

2. Install Codex and sign in

Easiest: install the ChatGPT desktop app, sign in, pick Codex, and open your Unity project folder. Codex can read and change files in the folder you choose.

Terminal (CLI): from OpenAI's CLI page. On macOS or Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

On Windows, in a new PowerShell window:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Or with npm: npm install -g @openai/codex. Then:

cd /path/to/YourUnityProject
codex

Choose Sign in with ChatGPT the first time. Code editor: OpenAI also offers a Codex extension for VS Code, Cursor and Windsurf, and integrations for JetBrains IDEs and Xcode (Codex IDE extension).

3. Add an AGENTS.md

Codex reads AGENTS.md files before doing any work (OpenAI's AGENTS.md guide). In the CLI, /init drafts one for you. Keep it short. Here is a starting point you can paste and edit:

# Unity project notes for Codex

- Engine: Unity 6 (edit this to match your exact version, e.g. 6000.0).
- Scripts live under Assets/Scripts/. Prefer small MonoBehaviour components.
- Prefer editing .cs files. Do not hand edit .unity scene or .prefab YAML unless asked.
- After script edits, wait for the Editor to recompile, then check the Console for errors.
- Batch mode tests need the Editor closed on this project. Otherwise use the Test Runner window.
- Tests: Edit Mode tests live under Assets/Tests/EditMode/. Run with:
  Unity -batchmode -runTests -projectPath . -testPlatform EditMode -testResults TestResults.xml -logFile -
- Never delete or rename .meta files. Commit .meta files with new assets.
- Ask before changing Project Settings, Packages/manifest.json or Input System bindings.

OpenAI notes that Codex stops reading instruction files after 32 KiB by default, and that big files eat into your usage, so a dozen clear lines beats a long essay.

4. Keep Codex's safety settings on

OpenAI's lower-risk local setup is the workspace-write sandbox with on-request approvals: Codex can edit inside your project and run routine commands, and asks before anything outside that. In the CLI, /permissions shows and changes this. Avoid full access mode on your game folder. See Codex sandbox and approvals.

Your first tiny task

1. Ask Codex: Create Assets/Scripts/PlayerController.cs: a 2D Rigidbody2D player that moves with WASD or the arrow keys. Add a comment at the top explaining how to attach it.
2. Switch to the Unity Editor and wait for it to recompile. Create a Sprite or Capsule, add a Rigidbody2D, attach the script and press Play. If the Console shows errors, copy them into Codex and ask it to fix them.
3. Ask: Add an Edit Mode test assembly under Assets/Tests/EditMode with one test for a plain C# helper, for example clamping move speed.
4. Run the tests from a terminal. The Unity binary path differs by OS. These flags come from the Unity Test Framework command-line docs:

Unity -batchmode -runTests -projectPath /path/to/YourUnityProject -testPlatform EditMode -testResults TestResults.xml -logFile -

Per Unity's docs, -batchmode removes the need for manual input, -testPlatform EditMode runs Edit Mode tests (also the default), and results are saved as NUnit XML. One catch: Unity's command line manual says you can't open a project in batch mode while the Editor has the same project open. So close the Editor before a batch run, or run the same tests from the Test Runner window inside the Editor.

5. Commit, then add one more feature: a coin, a score, a simple enemy. Repeat edit, Console, test, play, commit.

Optional: Unity's official plugin for Codex

From Unity's Codex plugin docs, run these in a terminal with the Codex CLI installed:

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

Start a new Codex session, then type /unity: to see the Unity skills, or run codex plugin list to confirm unity is installed and enabled. Update later with codex plugin marketplace upgrade unity-agent-plugin. Note that OpenAI says plugins are not available in the IDE extension, so install them from the CLI or the ChatGPT desktop app.

If you already have the Unity CLI, its October 7, 2026 release notes (1.0.0-beta.13) add unity setup codex, which runs those plugin commands for you.

Unity's plugin troubleshooting docs say the skills that control the Editor run Unity CLI commands. For those to work you need the Unity CLI installed, the Pipeline package in your project, and the Editor open. That is the next section.

Optional: connect Codex to the Editor with the Unity CLI

1. Install the Unity CLI. Unity's recommended script for macOS or Linux is curl -fsSL https://unity.com/install.sh | bash (Windows PowerShell: irm https://unity.com/install.ps1 | iex). Then run unity --version. Unity Hub also updates the CLI automatically, so you may already have it.
2. Open your project in the Editor, then from the project folder run unity pipeline install to add the Pipeline package. Let the Editor recompile.
3. Check the connection with unity status. It should report the Editor as reachable for your project.
4. Register the MCP server in Codex: unity mcp configure codex. Add --dry-run first if you want to preview only the entry it adds or changes. unity mcp configure --list shows every supported client.
5. Restart Codex from your project folder and type /mcp to see connected servers. Try: Read the Unity Console and summarize any errors.

What that command changes: Unity's release notes say unity mcp configure codex edits Codex's config.toml and also relaxes Codex's sandbox network policy so unity mcp and direct unity command calls can reach the Editor through localhost. If it cannot safely match your existing file, it refuses and asks you to edit the file by hand. Codex runs MCP servers as stdio commands, and unity mcp is a stdio server, so a hand-written entry in ~/.codex/config.toml looks like this:

[mcp_servers.unity]
command = "unity"
args = ["mcp"]

The table name is up to you. Prefer what unity mcp configure codex --dry-run prints, since it also shows the sandbox settings it would change. OpenAI says the desktop app, CLI and IDE extension share this config, and a project .codex/config.toml only loads in trusted projects (Model Context Protocol in Codex).

Two Editors open? Unity's CLI release notes say unity mcp reads UNITY_PROJECT_PATH (or --project-path) to pick which project's Editor it talks to.

Optional: community CoplayDev unity-mcp

CoplayDev/unity-mcp is community-maintained (MIT) and not from Unity Technologies. Per its README it needs Python 3.10+ (via uv) and supports Unity 2021.3 LTS through 6.x. Install from Package Manager with Add package from git URL:

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

Then use Window, MCP for Unity, Configure All Detected Clients. On Unity 6, try Unity's own CLI first. Use Coplay when you are on an older Editor or want its tool set.

Common errors and fixes

• unity: command not found. Unity's docs say to reopen your terminal or add the install folder to your PATH. On Linux the script installs to ~/.local/bin/unity.
• unity status cannot reach the Editor. Open the project in the Editor, run unity pipeline install in that folder, and wait for the recompile to finish.
• Codex is blocked from reaching the Editor. That is the sandbox doing its job. Use unity mcp configure codex, which sets up localhost access for you, or approve the request when Codex asks.
• Codex ignores your project .codex/config.toml. Codex only loads project config in trusted projects. Trust your own project, or use ~/.codex/config.toml.
• /unity: skills do not show up. Start a new Codex session after installing the plugin, and check codex plugin list.
• "Missing script" or broken references. A .meta file was deleted or not committed. Restore it from git. Never let the agent "clean up" meta files.
• Batch mode tests will not start while the Editor is open. Unity's manual says a project can't open in batch mode while the Editor has it open. Close the Editor first, or use the Test Runner window instead.
• Usage runs out fast. OpenAI says every MCP server adds context and uses more of your limit. Turn servers off when you do not need them, and ask for one small change at a time.

Codex or Claude Code for Unity?

In Unity they are close. Unity publishes its official plugin for both, and the Unity CLI can configure either one. Pick the one you already pay for: Codex comes with ChatGPT Plus, Claude Code with Claude Pro. If you have neither, Codex's desktop app on the Free plan is the cheapest way to try, if it has rolled out to you. See How to use Claude Code with Unity and Claude Code vs Codex vs Cursor for game dev.

Sources (checked October 20, 2026)

• Unity's plugin for Codex (Unity docs)
• Unity's AI tools and FAQ (unity.com/features/ai)
• Use the Unity CLI (Unity docs)
• Unity CLI as the replacement for the in-Editor MCP server (Unity docs)
• Unity CLI release notes
• Unity's plugin troubleshooting (Claude Code page)
• Unity Test Framework command-line reference 1.4
• Unity Editor command line arguments (Unity 6.2 manual)
• Codex CLI (OpenAI), IDE extension, MCP, config basics, AGENTS.md, sandboxing
• Codex pricing (OpenAI)
• CoplayDev/unity-mcp README (community)

Related

Using Unreal instead? Follow How to use OpenAI Codex with Unreal Engine. Prefer Godot? See Build a Godot game with AI coding agents like Codex. Still choosing an engine? Read Godot vs Unity for beginners or browse coding and game logic tools.

FAQ

Does Codex work with Unity officially?

Yes. Unity publishes an official plugin for Codex (install it with codex plugin marketplace add Unity-Technologies/unity-agent-plugin, then codex plugin add unity@unity-agent-plugin), and the Unity CLI can register its MCP server in Codex with unity mcp configure codex. Unity's FAQ says the CLI, MCP server and official plugin are free to use. Checked October 20, 2026.

Can I do this on ChatGPT's free plan?

Partly. OpenAI says ChatGPT Free and Go include limited Codex in the desktop app, subject to rollout. The Codex CLI and IDE extension start with ChatGPT Plus at $20/mo. Unity's plugin install commands use the Codex CLI, so plan on Plus if you want the full setup. Check OpenAI's Codex pricing page before you pay.

Do I need MCP or the plugin?

No. The core loop is: Codex edits C# under Assets/, the Unity Editor recompiles, you read the Console, run tests, then fix and repeat. The plugin and MCP are optional extras that let Codex drive the Editor and follow Unity's own guidance.

Which Unity version do I need?

Unity 6.0 or later for Unity's official plugin, and Unity 6.0 LTS or later for the Unity CLI to drive a running Editor. Older Editors still work with the plain file edit loop, or with the community CoplayDev unity-mcp package, which supports Unity 2021.3 LTS through 6.x per its README.

Is Unity's in-Editor MCP server still the way to connect?

No. Unity's docs now say the MCP server inside the in-editor AI assistant package (com.unity.ai.assistant) is deprecated, and point you to the Unity CLI instead. Run unity mcp configure codex to use the CLI's MCP server.

Where does Codex keep MCP settings?

In ~/.codex/config.toml by default, or a project .codex/config.toml that Codex only loads when you trust the project. OpenAI says the ChatGPT desktop app, Codex CLI and IDE extension share this configuration, so you set it up once.