LLM Integration

MCP server and Unity AI Assistant Unity 6.0+

On Unity 6 with the AI Assistant package (com.unity.ai.assistant), LLM Hooks registers three native juicebox_* tools with Unity's MCP Server — read, writescene, and writeshared. Agents connected to the Editor — Claude Desktop, Claude Code, Cursor — call JuiceBox directly to survey, dump, create, patch, place an animation on an object, and copy or fork one.

The two write tools are split by reach, so you decide how much to allow: writescene only edits an open scene — and never saves it for you — while writeshared writes shared definition assets. You can permit one without the other.

One-time setup:

1. Open Edit › Project Settings › AI › Unity MCP Server and check the bridge is running.
2. In the tools list, enable the JuiceBox group — new tools start disabled, so this one-time step switches them on.
3. Under Integrations, click Configure next to your client. If your client asks you to point at the server yourself, use Unity's relay executable in ~/.unity/relay/ (Unity fills this in for you when it writes the client's config). Then restart the client.
4. Back in Unity, approve the pending connection when it appears. Approval is remembered.

Unity writes the connection into your client's own MCP config — for Claude, an mcpServers.unity entry in ~/.claude.json that points at the relay executable. It lives outside your Unity project, and you can remove that entry to disconnect.

Unity's built-in Assistant (the chat inside the Editor) reaches JuiceBox too: it reads the shipped contracts and drives the same safeguarded operations through its command path. Everything below about tokens and rejection applies to it equally.

Recommended: tell the Assistant about JuiceBox up front via its custom instructions (Project Settings › AI › Assistant, the Custom Instructions box). The Setup window's first section has a one-line pointer that tells the Assistant to drive animation work through the JbxOps functions and points it at the shipped contracts (JBX-CONTRACT.md / JBXPATCH-CONTRACT.md) for the full schema. Custom instructions are your project's single slot — the pointer is meant to sit alongside whatever else you keep there. Copy to clipboard lets you paste it in yourself; Add for me appends it to your assigned instructions file (or creates and assigns one only if the slot is empty — it never replaces what you have).

Coding agents in your project folder Any Unity

For agents that work in your repository — Claude Code, Cursor, Codex, Copilot — open Tools › JuiceBox › LLM Hooks › Setup… and click Set up agent access. It writes AGENTS.md and CLAUDE.md into your project root, plus a self-contained skill package, so your agent discovers JuiceBox on its own. Existing files are never overwritten — a JuiceBox section is appended once.

"Give the coin a bouncy pickup animation."

The agent reads AGENTS.md, learns the format, and does the rest.

The file bridge Fallback

The backup path: a watched folder. Anything that can write a file can drive JuiceBox through it — useful for agents with no Editor connection, CI, or unusual setups. It is off until you create its folders; if you are using the paths above, you never need this.

To turn it on, open Tools › JuiceBox › LLM Hooks › Setup… and click Set up file bridge. That creates:

YourProject/
    Assets/
    JuiceBoxAgent/
        in/             <- work goes here
        out/            <- answers appear here
        in/processed/   <- inputs are archived here after they run

Drop a .jbx (create), .jbxpatch (modify), .jbxinsert (place on a scene object), or .jbxownership (copy, fork, or extract) into in/; Unity picks it up within a second — or the next time the Editor regains focus — applies it, and writes the verdict to out/<name>.report.json. After a successful change the asset is re-dumped automatically; that is what an agent reads before its next edit.

It will not clobber your work

When a patch is rejected

A rejection is the system working. The usual cause is that the animation changed after the agent last read it. The fix is always the same: re-read, then re-write — the agent takes a fresh dump and authors the patch again. Never hand-edit a token to make a patch apply; the token is the only thing standing between an agent and your work.

The Setup window

Everything lives behind one menu item — Tools › JuiceBox › LLM Hooks › Setup… — which opens a window holding the three paths above plus a quick check. It also opens by itself the first time you load a project with LLM Hooks installed.

What it can and cannot do

Agents can create sequences and effects, retune them, reorder them, wire combiners, and link one sequence's output to another's input — everything the graph exposes. That covers definition assets and animations embedded directly on a component alike: agents survey the open scenes, address an embedded animation by its object id or hierarchy path, and edit it in place.

They can also place an animation onto a GameObject that doesn't have one yet — linking a shared definition or embedding its own copy — and make ownership moves: copy an animation onto another object, extract an embedded one into a new shared definition, or make an instance unique to fork it off the definition it shared. (Creating the GameObject itself stays Unity's job; the agent only adds the animation.)

Two behaviors worth knowing. If a component uses a shared definition, edits are pointed at the definition asset — so every instance follows. A read reports how many objects share a definition, and editing a shared one warns you; to give a single instance its own variant, an agent forks it first (make unique, or copy) and edits the fork. And when a scene animation is edited or placed, the scene is marked dirty exactly like a hand edit — you see the usual unsaved star and save with Ctrl+S (or undo, or discard). JuiceBox never saves the scene for you.