Unifocl is a command-line interface (CLI) and terminal user interface (TUI) tool designed to provide deterministic interaction with Unity projects without requiring the Unity Editor. It serves as a programmable operations layer, enabling developers and AI agents to manipulate project assets, scenes, and workflows through a structured, keyboard-driven environment.
Key Features:
Model Context Protocol (MCP) Integration: Built-in MCP server for seamless AI agent interaction, allowing deterministic project state reading and safe asset mutations.
Deterministic Mutations: Every command supports dry-run operations, ensuring predictable outcomes before any changes are committed.
Keyboard-Driven TUI: A clean, efficient interface for developers to navigate and modify Unity projects using keyboard shortcuts.
Extensibility: Developers can create custom commands by adding the [UnifoclCommand] attribute to C# editor methods, which are automatically exposed as MCP tools.
Debug Artifact Reports: Collect project state snapshots into a structured JSON file, useful for automated bug reporting or integration with external tools like Jira.
Runtime Operations Control: Manage running player instances (Editor PlayMode, standalone builds, mobile devices) through a typed interface.
Audience & Benefit:
Ideal for developers who prefer CLI/TUI workflows and AI agents requiring deterministic project interaction. Unifocl streamlines Unity project manipulation, reduces friction in automation and LLM-driven development, and ensures safe, predictable changes to projects. It is particularly beneficial for teams integrating AI tools like Claude or Codex into their Unity workflows.
Unifocl can be installed via winget on Windows (x64) as part of its supported installation methods.
README
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 methods packaged into lazy-loadable categories.
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:
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:
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, 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.
{
"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
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.
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.