Hi everyone. I’ll tell you about my harness for AI programming in Unity. I’m currently using OpenAI Codex. You can also work with Claude. In that case, replace AGENTS.md with CLAUDE.md.
The first thing you need to do is set this base prompt(go to Codex personalization and set):
IMPORTANT: Before doing anything, you must read AGENTS.md from the project root.
Do not analyze, edit, create, delete, refactor, or suggest code until AGENTS.md has been fully read and applied.
AGENTS.md defines the project rules, architecture, coding style, naming, restrictions, and workflow. These instructions have priority over your default behavior.
IMPORTANT: Do not shorten, simplify, skip, or avoid the task.
Your goal is to complete the user request fully, not partially.
Do not replace the requested work with advice, summaries, or explanations.
Do not say that the task is too large if it can be done step by step.
Do not stop after analysis. Analysis is only useful if it leads to implementation.
Do not skip files that are relevant to the task.
If sub-agents are available and the task can be split into independent parts, use them. Do not avoid sub-agents when they would improve search, implementation, validation, or review quality.
The second step is to create an AGENTS.md file in the root of the project and add the tools for connecting to Unity.
AGENTS.md
Project Local Tools
The project should use local tools from the Tools/ directory. Prefer these tools over globally installed alternatives so every developer and automation agent uses the same versions.
Tool Sources
Expected Tool Layout
Tools/
ripgrep-15.1.0/
rg.exe
UnityCli/
unity-cli.cmd
unity-cli.sh
UCP/
ucp.cmd
ucp.sh
If a required tool folder is missing, report the missing tool and path. Do not silently replace it with an unrelated global installation.
Connecting the Tools
ripgrep
Download or vendor ripgrep from:
GitHub - BurntSushi/ripgrep: ripgrep recursively searches directories for a regex pattern while respecting your gitignore · GitHub
Place the executable under:
Tools/ripgrep-15.1.0/rg.exe
Use it for fast project search, file discovery, and code navigation.
Examples:
Tools/ripgrep-15.1.0/rg.exe "SearchText"
Tools/ripgrep-15.1.0/rg.exe -n "class Player"
Tools/ripgrep-15.1.0/rg.exe --files
Tools/ripgrep-15.1.0/rg.exe -n "TODO" Assets
Tools/ripgrep-15.1.0/rg.exe -n "PlayerPrefs" Assets -g "*.cs"
Rules:
- Use ripgrep before slower search tools.
- Run it from the project root when possible.
- Prefer targeted searches in
Assets, Packages, ProjectSettings, Tools, or documentation folders.
UnityCli
Download or vendor UnityCli from:
GitHub - youngwoocho02/unity-cli: Control Unity Editor from the command line. No MCP, no Python, no dependencies — just a single binary. · GitHub
Expected launcher paths:
Tools/UnityCli/unity-cli.cmd
Tools/UnityCli/unity-cli.sh
UnityCli is used for quick Unity Editor operations, small probes, logs, compile refresh, screenshots, menu calls, and custom [UnityCliTool] commands.
Requirements:
- Unity Editor must be open.
- The UnityCli connector package must be installed in the Unity project.
- If multiple Unity instances are open, select the target project with
--project <path> or the target bridge port with --port <number>.
Useful commands:
Tools/UnityCli/unity-cli.cmd status
Tools/UnityCli/unity-cli.cmd console --lines 50
Tools/UnityCli/unity-cli.cmd console --type error,warning --stacktrace full
Tools/UnityCli/unity-cli.cmd editor refresh --compile
Tools/UnityCli/unity-cli.cmd editor play --wait
Tools/UnityCli/unity-cli.cmd editor stop
Tools/UnityCli/unity-cli.cmd menu "File/Save Project"
Tools/UnityCli/unity-cli.cmd screenshot --view game --output_path Temp/game.png
Tools/UnityCli/unity-cli.cmd list
Tools/UnityCli/unity-cli.cmd exec "UnityEngine.Object.FindObjectsOfType<UnityEngine.Camera>().Length"
Use UnityCli when:
- You need a quick editor status check.
- You need to read or clear Unity console logs.
- You need to trigger script compilation or asset refresh.
- You need to run a short C# probe.
- You need to call a known Unity menu item.
- You need to invoke an existing custom
[UnityCliTool].
Do not use UnityCli for large multi-step scene, prefab, or asset workflows when UCP provides a safer structured command.
UCP
Download or vendor UCP from:
GitHub - mflRevan/unity-control-protocol: Rust-based Unity Control CLI + C# bridge layer. Exposes editor, debugging and lifecycle structured tool access outside of Unity. Highly recommended for heavy agentic development workflows. · GitHub
Expected launcher paths:
Tools/UCP/ucp.cmd
Tools/UCP/ucp.sh
UCP is used for structured Unity automation across scenes, GameObjects, components, prefabs, assets, packages, settings, builds, tests, profiler data, references, and version-control-aware workflows.
Common setup and health commands:
Tools/UCP/ucp.cmd doctor
Tools/UCP/ucp.cmd connect
Tools/UCP/ucp.cmd install
Tools/UCP/ucp.cmd bridge
Common usage examples:
Tools/UCP/ucp.cmd open
Tools/UCP/ucp.cmd compile
Tools/UCP/ucp.cmd logs
Tools/UCP/ucp.cmd run-tests
Tools/UCP/ucp.cmd screenshot
Tools/UCP/ucp.cmd scene --help
Tools/UCP/ucp.cmd object --help
Tools/UCP/ucp.cmd asset --help
Tools/UCP/ucp.cmd prefab --help
Tools/UCP/ucp.cmd build --help
Tools/UCP/ucp.cmd references --help
Useful global options:
Tools/UCP/ucp.cmd --project <project-path> doctor
Tools/UCP/ucp.cmd --json logs
Tools/UCP/ucp.cmd --timeout 120 compile
Use UCP when:
- The task touches scenes, prefabs, assets, materials, packages, build settings, tests, profiler, or object/component data.
- The task has multiple Unity Editor steps.
- JSON output is useful for automation.
- You need safer structured editor workflows instead of ad hoc C# probes.
Safety rules:
- Do not modify scenes, prefabs, or serialized Unity assets if the editor state is dirty or unsafe.
- Check tool health with
doctor or connect when the bridge state is unclear.
- Use
--json when another script or agent needs stable machine-readable output.
- If UCP is missing or cannot connect to the Unity bridge, report the exact blocker.
Tool Selection Rules
- Use ripgrep first for searching files and text.
- Use UnityCli for quick Unity checks and small editor actions.
- Use UCP for structured or multi-step Unity workflows.
- Prefer project-local tools over global installations.
- Run commands from the project root when possible.
- If a required local tool is missing, report the missing tool and path.
Unity C# Coding Standard
Project and Text Rules
- This is a Unity 3D C# project.
- Write code comments in English.
- Keep all project text files encoded as UTF-8.
- If a touched text file is ANSI/Windows-1252, convert it to UTF-8 before editing its content.
- Prefer project-local tools over globally installed tools when a local tool exists.
Code Style
- Prefer simple, direct, flat, readable Unity C#.
- Keep code small and keep logic near the execution point.
- Avoid unnecessary abstraction, indirection, utility layers, over-engineered managers, generic helper classes, and one-use helper methods.
- Prefer explicit code over architecture created only for neatness.
- Prefer direct
if / if else logic at the call site over one-use condition helper methods.
- Inline simple or one-use logic.
- Small duplication is acceptable when it keeps the code easier to read.
- Add methods only for large logic, reused logic, or clear business actions.
- Do not extract null checks, simple boolean checks, one-line wrappers, trivial UI toggles, tiny formatting helpers, simple getters, save/load wrappers, or trivial conversions.
- Do not use
switch in any form: switch statements, switch expressions, pattern switches, or switch-like operators.
- Use early returns only for errors, blockers, invalid input, or invalid state.
- Keep normal success paths linear and easy to follow.
Unity Runtime Rules
- Scenes should be composition surfaces only.
- Do not put reusable runtime logic directly into scene-specific code.
- Put project-specific app logic under
Assets/scripts.
- Put reusable systems and modules under
Assets/Modules.
- Reusable modules should not depend on project-specific app shell code.
- WebGL template files should only contain host-page customization, not Unity runtime logic or business logic.
Workflow and Safety
- Do not invent success when a compile, reimport, tool call, or source access is blocked.
- If source access, authentication, permissions, or required tool capability is missing, stop and report the exact blocker.
- Do not create duplicate temporary Unity project copies to bypass compile blocks, dirty scenes, or unsaved editor state.
- Do not modify scenes, prefabs, or serialized Unity assets when the Unity editor state is unsafe or dirty.
- Temporary editor scripts created only to modify scenes, prefabs, or serialized assets must be deleted after the edit unless they are real product code or the user asks to keep them.
I also recommend setting up a harness. In my opinion, the best approach is Karpathy’s LLM Wiki.
To migrate the project to Karpathy’s LLM Wiki pattern, run this prompt:
Apply Karpathy’s LLM Wiki pattern to this project.
Official source:
https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
First, download the official Karpathy / LLM Wiki GitHub Gist file and save it inside the project here:
Docs/wiki/karpathy-llm-wiki.md
Use that file as the reference for building the project wiki.
The project wiki must live in the root-level Docs/wiki/.
Create and maintain a persistent project wiki in Markdown. Use it as long-term memory for the codebase, architecture, Unity systems, workflows, important decisions, bugs, fixes, and recurring project knowledge.
When you inspect the project, do not only answer the current question. Also update the wiki when you discover useful information. Keep pages short, linked, and practical. Add backlinks between related systems. Track contradictions, outdated assumptions, and important implementation details.
Suggested structure:
* Docs/wiki/index.md — main entry point
* Docs/wiki/log.md — chronological work log
* Docs/wiki/karpathy-llm-wiki.md — downloaded Karpathy LLM Wiki reference
* Docs/wiki/systems/ — Unity systems and features
* Docs/wiki/architecture/ — project structure and technical decisions
* Docs/wiki/workflows/ — build, test, deploy, debug workflows
* Docs/wiki/issues/ — known bugs, fixes, and investigations
* Docs/wiki/glossary.md — project terms and naming
Before working on a task, read the relevant wiki pages. After finishing, update the wiki with anything useful for future work.
For OpenAI Codex, put the project instructions into AGENTS.md.