unifocl

The programmable operations layer for Unity—built for keyboard-driven developers and autonomous AI agents.

Unity is a powerful engine, but its graphical, mouse-driven Editor can introduce friction for automation, LLM workflows, and developers who prefer the terminal. unifocl solves this by providing a structured, deterministic way to interact with, navigate, and mutate your Unity projects without relying on the GUI.

Whether you are a developer looking for a snappy Terminal User Interface (TUI) to manipulate scenes, or you are hooking up an AI agent via the Model Context Protocol (MCP) to autonomously write code and edit prefabs, unifocl provides the bridge.

unifocl is an independent project and is not associated with, affiliated with, or endorsed by Unity Technologies.

Why unifocl?

• Native Agentic Tooling (MCP): Comes with a built-in MCP server. AI agents (like Claude) can seamlessly read your hierarchy, inspect components, and safely mutate assets using strict JSON/YAML response envelopes.
• Lean & Token-Efficient: LLMs struggle with massive, unstructured context windows. unifocl is specifically designed to keep its API surface streamlined, feeding agents exactly the project state they need. This saves tokens, reduces costs, and keeps your agents focused.
• Safe, Deterministic Mutations: Never let an AI break your project. Every single mutation command features mandatory dry-run capabilities and transactional safety (Undo/Redo integration), ensuring predictability before anything touches the disk.
• Instantly Extensible: Need a custom tool for your agent? Add the [UnifoclCommand] attribute to your C# editor methods. unifocl automatically discovers them and exposes them as live MCP tools with built-in dry-run sandboxing.
• Dual-Interface: A clean, keyboard-driven Spectre.Console TUI for humans, alongside a stateless, headless execution path for multi-agent workflows.
• Debug Artifact Reports: Collect tiered snapshots of your project state—console logs, validation results, profiler data, recorder output—into a single structured JSON file. Feed it to agents for automated bug reports or pipe it straight to Jira/Wrike.
• Zero-Touch Compilation: Deploy new editor scripts and let unifocl trigger Unity recompilation automatically—no manual window focusing required.
• Runtime Operations: Control running player instances—Editor PlayMode, standalone builds, mobile devices—through the same typed, risk-classified interface. Attach to targets, execute queries, and extend the surface with your own [UnifoclRuntimeCommand] methods packaged into lazy-loadable categories.

Installation

macOS (Apple Silicon & Intel)

Shell Installer:

curl -fsSL https://raw.githubusercontent.com/Kiankinakomochi/unifocl/main/scripts/install.sh | sh

Homebrew:

brew tap Kiankinakomochi/unifocl
brew install unifocl

Windows (x64)

Winget:

winget install unifocl

PowerShell Installer:

iwr -useb https://raw.githubusercontent.com/Kiankinakomochi/unifocl/main/scripts/install.ps1 | iex

Manual Download

Download pre-built archives from the latest GitHub release and place the binary anywhere in your PATH.

Agent Setup (Claude Code & Codex)

unifocl agent setup /path/to/your-unity-project

Auto-detects installed agent tools (claude, codex) and writes the required config files into the project directory. Commit the generated .claude/settings.json and CLAUDE.md to share the integration with your team — each contributor runs agent setup once locally for their own permissions.

Requirements

• .NET 10 (or later) for the CLI.
• Unity 2020.1 or later for editor scripts. Unity 2022.1+ is recommended — newer APIs (e.g. FindObjectsByType) are used when available, with automatic fallbacks for older versions. The Roslyn analyzer integration requires Unity 2022.2+.

Quick Start

For Humans (The TUI)

Launch the interactive shell to navigate your project at the speed of thought.

# Start the unifocl bridge in your project
unifocl

> /open ./MyUnityProject
> /hierarchy
> f PlayerController        # Fuzzy find
> mk Cube                   # Create a GameObject
> /inspect 12               # Inspect the object
> set speed 5               # Change a component field

For AI (The MCP Server & Agentic Execution)

Agents can use the built-in MCP server or the one-shot exec path to read deterministic state and make safe changes.

# Run an agentic dry-run to see what will change
unifocl exec "rename 3 PlayerController --dry-run" --agentic --format json

unifocl returns a structured diff payload, letting the LLM verify the change before committing it:

{
  "status": "success",
  "action": "rename",
  "diff": {
    "format": "unified",
    "summary": "Rename GameObject index 3",
    "lines": ["--- before", "+++ after", "-  name: \"Cube\"", "+  name: \"PlayerController\""]
  }
}

Every mutation command supports --dry-run. The operation executes inside a Unity Undo group, captures a before/after diff, and immediately reverts—nothing touches the disk until you confirm.

Custom MCP Tools with [UnifoclCommand]

Expose your own C# editor methods as live MCP tools:

[UnifoclCommand("myteam.reset-player", "Reset player to spawn point")]
public static void ResetPlayer(UnifoclCommandContext ctx)
{
    var player = GameObject.FindWithTag("Player");
    player.transform.position = Vector3.zero;
    ctx.Return("Player reset to origin");
}

unifocl discovers these at runtime and makes them available as MCP tools—complete with automatic dry-run sandboxing. See docs/custom-commands.md for the full guide.

Dynamic C# Eval

Execute arbitrary C# directly in the Unity Editor context—no script files needed:

# Simple read query
unifocl eval 'return Application.productName;'

# Dry-run: execute and revert all Unity Undo-tracked changes
unifocl eval 'Undo.RecordObject(Camera.main, "t"); Camera.main.name = "CHANGED";' --dry-run

Eval uses a dual-compiler strategy (Unity AssemblyBuilder in Bridge mode, bundled Roslyn in Host mode) and supports async/await, custom declarations, timeout protection, and --dry-run sandboxing. The entry point is always async Task<object>, so await works naturally.

Asset Describe — Let Agents See Without Vision Tokens

AI agents working with Unity often need to understand what an asset looks like — is this sprite a character? A tileset? A UI icon? Normally this means sending the image to a multimodal LLM and burning tokens on cross-modal comprehension.

asset.describe solves this by running a local vision model (BLIP or CLIP) on your machine. Unity exports a thumbnail, the CLI captions it locally, and the agent receives a compact text description — zero vision tokens spent.

unifocl exec '{"operation":"asset.describe","args":{"assetPath":"Assets/Sprites/hero.png"},"requestId":"r1"}'

{
  "status": "Completed",
  "result": {
    "description": "a cartoon character with a blue hat",
    "assetType": "Texture2D",
    "engine": "blip",
    "model": "Salesforce/blip-image-captioning-base@82a37760"
  }
}

Choose between two engines:

• blip (default) — open-ended natural language captions
• clip — zero-shot classification against game-asset labels (sprite, mesh, UI, material, etc.)

Dependencies: Requires python3 (>= 3.10) and uv — run unifocl init to install them automatically. Runtime installs are driven by a hash-locked requirements file (uv run --with-requirements) pinned to transformers==5.5.0, torch==2.11.0 (CPU-compatible wheel selection by platform), and Pillow==12.2.0. The first invocation also downloads the model weights (~990 MB for BLIP, ~600 MB for CLIP) from HuggingFace; subsequent runs load entirely from cache with no network access. Model revisions are pinned to exact commit SHAs for supply-chain safety.

See the Command Reference — Asset Describe for full details.

Documentation Reference

To keep this README clean, detailed technical specifications and command lists have been split into dedicated documents:

Document	Description
Command & TUI Reference	Full list of slash commands, contextual operations, keyboard shortcuts, dry-run mechanics, and eval details.
Agentic Workflow & Architecture	Deep dive into the daemon architecture, JSON envelopes, ExecV2 endpoints, concurrent worktrees, and the Persistence Safety Contract.
Custom Commands Guide	How to expose your C# methods as MCP tools with [UnifoclCommand].
MCP Server Architecture	Built-in MCP server setup, agent JSON configuration, and multi-client guide.
Editor Compilation	Details on headless/CI compilation behavior and zero-touch recompilation.
Validate & Build Workflow	Project validation checks and build workflow commands.
Test Orchestration	Unity test runner integration (EditMode/PlayMode).
Project Diagnostics	Assembly graphs, scene deps, compile errors, and other read-only introspection.
Debug Artifact Workflow	Tiered debug report collection (prep → playmode → collect) for agents and CI.

Contributing & License

External contributions are accepted for version 0.3.0 and later.

Unless explicitly stated otherwise, any Contribution intentionally submitted for inclusion in version 0.3.0 and later is licensed under the Apache License 2.0.

Apache License 2.0 applies to version 0.3.0 and all later versions.

All content before version 0.3.0 is proprietary and all rights reserved.