everything-claude-unity

English | 中文 | 日本語 | 한국어 | Español | Português | Deutsch | Français | Türkçe

The ultimate Claude Code toolkit for Unity game development.

A production-ready, plug-and-play system that gives Claude Code deep Unity expertise — from writing performant C# to building scenes, profiling performance, and triggering iOS/Android builds — all through natural language.

Built for solo indie mobile game developers. Drop it into any Unity project and it works.

Why this works?

• Drop-in, zero-config — one install.sh and Claude Code knows Unity inside out
• 20 specialized agents across haiku/sonnet/opus tiers with automatic complexity routing
• 22 safety hooks that prevent scene/meta corruption, silent data loss, and GC spikes before they happen
• MVS architecture built-in — VContainer + MessagePipe + UniTask patterns enforced by rules and templates
• MCP-native — scene building, profiling, and iOS/Android builds triggered from chat
• 60+ automated tests and reproducible benchmarks so the toolkit itself stays honest

---

What You Get

| Component | Count | Purpose | |-----------|-------|---------| | Agents | 20 | Specialized sub-agents across 3 model tiers (haiku/sonnet/opus) | | Commands | 22 | Slash commands like /unity-workflow, /unity-ralph, /unity-team, /unity-skillify | | Skills | 41 | Knowledge modules for Unity systems, gameplay patterns, and mobile genres | | Hooks | 22 | Safety net, quality gates, notifications, session persistence, auto-learning | | Rules | 5 | C# coding standards, performance rules, MVS architecture patterns | | Scripts | 8 | Validation tools for meta files, code quality, serialization, architecture | | Templates | 10 | C# templates for MVS pattern (Model, View, System, LifetimeScope, Message) | | Tests | 60+ | Automated test suite for hooks, state, cross-validation, templates, skills | | Benchmarks | 4 | Quality evaluation scenarios with structural comparison |

---

Highlights

/unity-workflow — Full Development Pipeline

A structured 4-phase pipeline for any feature: Clarify requirements, Plan the implementation, Execute with specialized agents, Verify with automated review + fix loop.

/unity-workflow "add a combo scoring system with multipliers and visual feedback"

/unity-prototype — One Prompt to Playable

Describe a mechanic, and Claude writes the C# scripts, builds the scene via MCP, sets up physics layers, configures the camera, and verifies it compiles.

/unity-prototype "2D platformer with wall jumping and dash"

/unity-ralph — Relentless Verify-Fix Loop

Runs the verify-fix loop persistently — refuses to stop until the project is clean or hits the safety limit. Up to 30 effective verification passes with stall detection.

/unity-ralph --max-iterations 10

/unity-team — Parallel Agent Orchestration

Spawn multiple agents simultaneously — coder + tester + reviewer working in parallel for faster development.

/unity-team --build "add health system with damage and healing"
/unity-team --security "audit the save system"
/unity-team --build --quick "add a basic score counter"

What's New in v1.3.0

• Smart Model Routing — complexity heuristics auto-select haiku/sonnet/opus agents based on task signals
• Persistent State — session data survives reboots in .claude/state/ with structured schema
• Plan Critic — unity-critic agent challenges your plans before execution (built into /unity-workflow)
• Security Auditing — unity-security-reviewer catches PlayerPrefs secrets, hardcoded keys, insecure saves
• Benchmarking — measure agent quality with reproducible evaluation scenarios
• Skillify — /unity-skillify auto-generates skills from your accumulated session learnings
• Multi-channel Notifications — Discord, Slack, OS-native with event filtering and rate limiting
• Hardened CI — cross-validation, tool restriction checks, template and skill quality gates

Verify-Fix Loop

The unity-verifier agent automatically reviews your code changes, fixes safe issues (missing [FormerlySerializedAs], uncached GetComponent, ?. on Unity objects), and re-verifies — up to 3 iterations until clean. Built into /unity-workflow and available as an optional step in /unity-feature and /unity-prototype.

Hook Profiles

Hooks are organized into three profiles. Set UNITY_HOOK_PROFILE to control which hooks run:

| Profile | What's Active | Best For | |---------|--------------|----------| | minimal | Safety hooks only (block scene/meta corruption, editor guards, pre-compact) | CI pipelines, experienced developers | | standard | Safety + quality warnings + session persistence + stop validation (default) | Daily development | | strict | Everything: GateGuard, cost tracking, auto-learning, build analysis | New projects, learning, auditing |

UNITY_HOOK_PROFILE=strict          # Enable all hooks including GateGuard
UNITY_HOOK_PROFILE=minimal         # Only critical safety hooks
DISABLE_UNITY_HOOKS=1              # Bypass all hooks entirely
UNITY_HOOK_MODE=warn               # Downgrade blocks to warnings
DISABLE_HOOK_BLOCK_SCENE_EDIT=1    # Disable a specific hook

---

Quick Start

Prerequisites

• Claude Code installed
• Unity 2021.3 LTS or later
• unity-mcp (optional but recommended for full pipeline)

Install

# From your Unity project root:
git clone https://github.com/XeldarAlz/everything-claude-unity.git /tmp/ecu
/tmp/ecu/install.sh --project-dir .
rm -rf /tmp/ecu

Or manually:

git clone https://github.com/XeldarAlz/everything-claude-unity.git
cp -r everything-claude-unity/.claude your-unity-project/.claude
chmod +x your-unity-project/.claude/hooks/*.sh

Upgrade / Uninstall

# Upgrade to latest (preserves your customizations, creates backup)
./upgrade.sh --project-dir .

# Preview changes before upgrading
./upgrade.sh --project-dir . --dry-run

# Clean removal (with backup)
./uninstall.sh --project-dir .

Setup Unity MCP (Recommended)

The MCP bridge gives Claude direct control over the Unity Editor — scene building, profiling, builds, and more.

1. In Unity: Window > Package Manager > + > Add package from git URL
2. Paste: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
3. Open Window > MCP for Unity and click Start Server
4. Claude Code auto-connects via .claude/settings.json

First Run

cd your-unity-project
claude

# Verify installation:
/unity-doctor         # Check MCP, hooks, project structure

# Start working:
/unity-audit          # Full project health check
/unity-workflow       # Full pipeline: clarify → plan → execute → verify
/unity-prototype      # Rapid prototype a game mechanic

---

Agents

Code Agents

| Agent | Model | What It Does | |-------|-------|-------------| | unity-coder | opus | Implements features with Unity subsystem awareness, loads relevant skills | | unity-coder-lite | sonnet | Lightweight variant for simple additions (fields, methods, straightforward components) | | unity-fixer | opus | Diagnoses bugs using Unity-specific patterns (missing refs, execution order, coroutine lifecycle) | | unity-fixer-lite | sonnet | Quick fixes for obvious issues (typos, missing imports, simple errors) | | unity-reviewer | sonnet | Code review checking serialization safety, GC in hot paths, lifecycle ordering | | unity-shader-dev | opus | HLSL/ShaderGraph development optimized for mobile GPUs, live testing via MCP |

Orchestration Agents

| Agent | Model | What It Does | |-------|-------|-------------| | unity-verifier | opus | Verify-fix loop: reviews changes, auto-fixes safe issues, re-verifies (max 3 iterations) | | unity-prototyper | opus | End-to-end prototyping: writes code + builds scene + physics + camera |

MCP-Powered Agents

| Agent | Model | What It Does | Key MCP Tools | |-------|-------|-------------|---------------| | unity-scene-builder | opus | Builds scenes from descriptions | manage_scene, batch_execute | | unity-test-runner | sonnet | Writes + runs tests, reports results | run_tests, read_console | | unity-build-runner | sonnet | Configures and triggers builds | manage_build, manage_packages | | unity-optimizer | opus | Profiles and fixes performance issues | manage_profiler, manage_graphics |

Hybrid Agents

| Agent | Model | What It Does | |-------|-------|-------------| | unity-ui-builder | opus | Builds UI screens with code + visual setup via MCP | | unity-network-dev | opus | Implements multiplayer with Netcode/Mirror/Photon/Fish-Net | | unity-migrator | sonnet | Unity version and render pipeline migration |

Commands support --quick (routes to sonnet lite agent) and --thorough (routes to opus) flags. See docs/MODEL-ROUTING.md for the full routing table.

---

Commands

Full Pipeline

/unity-workflow <description>   Clarify → Plan → Execute → Verify (the recommended workflow)

Daily Workflow

/unity-feature <description>    Plan + implement a feature (--quick for simple tasks)
/unity-fix <bug or error>       Diagnose and fix a bug (--quick for obvious fixes)
/unity-prototype <mechanic>     One prompt to playable prototype
/unity-scene <description>      Build a scene via MCP
/unity-shader <description>     Create shaders with live preview
/unity-ui <screen description>  Build UI with visual setup
/unity-network <framework>      Set up multiplayer

Quality Gates

/unity-review [scope]           Code review (--thorough for deep analysis)
/unity-optimize                 Profile via MCP + fix bottlenecks
/unity-test                     Write + run tests via MCP
/unity-audit                    Full project health check
/unity-profile                  Deep profiling session

Orchestration

/unity-ralph [options]          Persistent verify-fix loop (refuses to stop until clean)
/unity-team <--preset|--custom> Parallel agents (coder + tester + reviewer simultaneously)
/unity-interview <topic>        Deep Socratic requirements interview before coding
/unity-learn [subcommand]       Session analytics: review, extract patterns, draft skills

Project Lifecycle

/unity-init                     Scan project + generate CLAUDE.md
/unity-build                    Configure + trigger builds
/unity-migrate                  Plan version/pipeline migration
/unity-doctor                   Diagnostic health check (MCP, hooks, project structure)

---

Hooks

22 hooks across 5 lifecycle events, organized by profile level.

Blocking Hooks — PreToolUse (minimal profile)

| Hook