Using Claude Code With Unity: Setup, CLAUDE.md and a Safe Workflow

An AI agent that can read your whole Unity project, edit scripts and run commands is a big step up from pasting snippets into a chat window. It is also a fast way to break a project if you let it loose without rules. This guide shows how to set up Claude Code with Unity: installing it, writing a CLAUDE.md that knows Unity’s conventions, protecting .meta files, and a git-based workflow that makes every change easy to review or throw away. Most of the workflow advice also applies to other agentic tools like Cursor or Copilot’s agent mode.

What Claude Code Does Differently

A chat assistant only sees what you paste. Claude Code runs in a terminal, an IDE extension or the desktop app, inside your project folder. That changes what it can do:

• It can search and read your scripts itself, so it sees how your PlayerController actually talks to your HealthSystem instead of guessing.
• It can edit several files in one task, for example renaming an event and updating every subscriber.
• It can run commands: git, search tools, or Unity in batch mode to run tests.
• It reads a CLAUDE.md file at the project root as standing instructions every session.
• It asks for permission before editing files or running commands, depending on the permission mode you choose.

What it can’t do on its own is see the Unity Editor. It doesn’t know what’s in your scene, what the Console says, or whether the project compiled, unless you tell it or connect it to Unity through an MCP server. We cover that connection in our Unity MCP AI assistant setup guide, so this post focuses on the file-level workflow that works with or without MCP.

Prepare the Unity Project First

Agents work on text files. Unity projects need two settings so that scenes, prefabs and meta data are readable text and tracked properly. Check them in Edit > Project Settings > Editor:

• Version Control > Mode: Visible Meta Files.
• Asset Serialization > Mode: Force Text.

Both are Unity’s defaults for new projects, but older or imported projects sometimes have binary serialization. Then put the project under git if it isn’t already, with a proper Unity .gitignore that excludes Library/, Temp/, Obj/, Logs/, UserSettings/ and Build/. Our git setup guide for Unity walks through it, including Git LFS for big binary assets.

Git is not optional here. It’s the undo button for everything the agent does. Commit a clean state before every session.

Install and Start a Session

Install Claude Code using the official instructions for your OS (there’s a native installer and an npm package). Then open a terminal in the Unity project root, the folder that contains Assets, Packages and ProjectSettings, and start it:

cd "C:\Projects\MyGame"
git status        # should be clean before you start
claude

Starting in the project root matters. If you start one level up, it treats your other projects as context. If you start inside Assets, it can’t see Packages/manifest.json and doesn’t know which packages you have.

On the first run, type /init. Claude Code scans the project and writes a starter CLAUDE.md. The generated file is a reasonable start, but it won’t know Unity’s rules about meta files or which folders are off-limits. Edit it using the template below.

Write a CLAUDE.md for Unity

CLAUDE.md is plain Markdown. Keep it short and specific: a list of facts and rules beats an essay. Here’s a template that works well for a Unity 6 project:

# Project: MyGame (Unity 6, URP)

## Facts
- Unity 6 (6000.x), Universal Render Pipeline 17.
- Input: Input System package only. Active Input Handling = Input System.
  Never use UnityEngine.Input (Input.GetKey, Input.GetAxis).
- Cinemachine 3 (namespace Unity.Cinemachine), TextMeshPro for all text.
- Physics: Rigidbody uses linearVelocity / linearDamping (Unity 6 names).
- Code lives in Assets/_Project/Scripts, split into assemblies:
  Game.Runtime, Game.Editor (editor only), Game.Tests.

## Conventions
- PascalCase public members, camelCase private fields, no "m_" prefix.
- [SerializeField] private fields instead of public fields.
- One MonoBehaviour per file; file name must match class name.
- No FindObjectOfType / GameObject.Find in Update. Cache references.

## Rules
- Never edit anything in Library/, Temp/, Logs/, UserSettings/.
- Never create, delete or edit .meta files. Unity generates them.
- Don't move or rename assets. If a rename is needed, tell me and I'll do it in the Unity Editor.
- Don't edit .unity, .prefab or .asset YAML files unless I ask.
- Editor-only code goes in an Editor folder or the Game.Editor assembly.
- Keep changes small. Explain what you changed and why at the end.

## Checking work
- Run EditMode tests (only when the Editor is closed):
  "C:\Program Files\Unity\Hub\Editor\6000.0.XXf1\Editor\Unity.exe" -batchmode -projectPath . -runTests -testPlatform EditMode -testResults TestResults.xml

Replace the Unity path and version with yours. The Facts section is the most valuable part. Most wrong AI code in Unity comes from the model assuming an older Unity, the old Input Manager or the Built-in Render Pipeline. Stating the real versions up front fixes most of that before it starts.

If you already have a style guide, point to it or paste its key rules. If you use assembly definitions, list them: the agent needs to know that code in Game.Runtime can’t reference UnityEditor. See our assembly definitions guide for how that split works.

The .meta File and Asset Rules

Every file and folder under Assets has a .meta file next to it. The meta holds the asset’s GUID, and every reference in your scenes and prefabs points to that GUID, not the file name. That’s why these rules matter:

• Deleting a .meta makes Unity generate a new GUID. Every scene and prefab that used the asset now has a broken reference, and every component using that script shows “The referenced script on this Behaviour is missing!”
• Renaming or moving a .cs file without its .meta does the same. Unity sees a deleted asset and a brand-new one.
• Renaming a MonoBehaviour class without renaming the file breaks the script link. The class name and file name must match.

The safest rule for agents: they create and edit .cs files, and you do any moving or renaming in the Unity Editor’s Project window, which keeps meta files in sync. A new script created by the agent is fine. Unity generates its meta when the Editor next imports it. If you do let the agent move a file, it must move the matching .meta in the same step, and you should check git status afterwards for a deleted meta and a new untracked one.

Scene and prefab files are text YAML, and agents can edit them, but it’s fragile. A small mistake in a fileID gives you a scene that won’t open. Leave scenes to the Editor, or to MCP tools that work through Unity’s own API.

A Safe Session Workflow

This loop keeps you in control and makes mistakes cheap:

1. Checkpoint. git status is clean, or commit what you have. Optionally work on a branch: git switch -c ai/inventory-refactor.
2. Ask for a plan first. For anything bigger than one file, ask it to read the relevant code and describe the change before editing. You catch wrong assumptions here, when they’re free to fix.
3. One task per request. “Add a pickup sound to Coin.cs” is a task. “Improve the player” is not.
4. Review the diff. When it’s done, read git diff yourself, or in your IDE’s git view. Look for touched files you didn’t expect.
5. Compile and test in Unity. Switch to the Editor, let it recompile, check the Console, press Play.
6. Commit or roll back. Good: commit with a clear message. Bad: git restore . for edited files and git clean -n to preview new untracked files before removing them with git clean -f.

A good first prompt for a session looks like this:

Read Assets/_Project/Scripts/Player/PlayerHealth.cs and everything that calls TakeDamage. I want damage to go through a single IDamageable interface so enemies and destructible crates can share it. Don’t edit anything yet. List the files you’d change and the new interface, then wait for my OK.

Asking it to wait is the key. You review the plan, correct it (“crates don’t need health, just a hit count”), then let it work.

About permission modes: while you’re learning how the agent behaves, keep it in a mode that asks before edits and commands. Once you trust a type of task, you can loosen it. Never turn off permission prompts on a project that isn’t committed.

Letting It Check Its Own Work

The weak spot of a file-only agent is that it can’t see compile errors in the Editor. You have three options.

Paste the Console. Copy the error from the Unity Console, including the file and line, and paste it back. Simple and works with any tool.

Point it at the Editor log. Unity writes compile errors to the Editor log. On Windows that’s %LOCALAPPDATA%\Unity\Editor\Editor.log, on macOS ~/Library/Logs/Unity/Editor.log. You can tell the agent to read the end of that file after Unity recompiles. Add the path to CLAUDE.md so you don’t repeat it.

Run tests in batch mode. With the Unity Editor closed (batch mode can’t open a project that’s already open), the agent can run your EditMode tests from the command line, as in the template above, and read TestResults.xml. A compile error fails the run, so this checks both. If you don’t have tests yet, our Unity Test Framework guide gets you started, and a handful of tests makes agent work far safer.

The fourth option is MCP, which lets the agent read the Console and inspect the scene directly through the running Editor. Set that up once with the MCP guide linked above and the loop gets much tighter.

Troubleshooting

“The referenced script on this Behaviour (Game Object ‘…’) is missing!”

A script’s .meta was deleted or regenerated, or the class name no longer matches the file. Check git status for a deleted meta, restore it with git restore path/to/Script.cs.meta, and make sure the class and file names match.

Claude Code uses Input.GetAxis even though I use the Input System

Your CLAUDE.md doesn’t say so clearly, or it’s not in the project root. Add an explicit “never use UnityEngine.Input” rule and restart the session.

“It looks like another Unity instance is running with this project open”

You ran a batch-mode command while the Editor had the project open. Close the Editor first, or have the agent skip batch-mode runs while you work.

The agent edited files in Library or Packages

Library is regenerated by Unity, so revert and let Unity rebuild it. For Packages/manifest.json, review the diff: adding or removing a package should be your decision. Add both to the rules section.

Scene won’t open after the agent edited it

Restore the scene with git restore Assets/Scenes/YourScene.unity and add a “don’t edit .unity files” rule.

Changes look right but Unity doesn’t pick them up

Unity only recompiles when it notices file changes. Click into the Editor window, or use Assets > Refresh (Ctrl+R) if Auto Refresh is turned off in Preferences.

FAQ