everything-claude-unity

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)