Skip to main content

Architecture overview

Buril is a multi-repo product. The bridge UPM package is the only component you install in Unity — everything else either talks to the bridge over MCP, ships separately, or is scaffolded for a later wave.

This page is a 1-page map so you know what lives where, what's reachable from the chat panel, and where to read next per layer.

The five layers​

LayerWhat it isStatusWhere it ships
BridgeC# Unity Editor package. 3,691 ITools, MCP server (HTTP + TCP), local RAG, vision feedback, Reference-to-Scene Pipeline, Multi-Agent Studio.Shipped 1.0UPM package: com.buril.bridge
Claude Code pluginA ~/.claude/plugins/buril/ plugin that auto-discovers the bridge MCP server, adds Buril-aware slash commands, and surfaces ITools to any Claude Code terminal session.Shipped 1.0npm-distributed install or in-repo copy
Buril StudioNext.js + React Flow visual workflow renderer. Pipeline dashboard, agent canvas, ITool composer.Scaffolded (Y1 Q3 / 1.3)buril-studio/ in the bridge repo
Buril Cloud (backend)Cloudflare Workers + D1 + R2 backend for asset CDN, optional cloud RAG, marketplace billing.Scaffolded (Y1 Q4)buril-cloud-backend/ in the bridge repo
Buril IDETypeScript VS Code fork. Chat sidebar, diff viewer, vault browser, MCP wizard.Scaffolded (Y2 Q1 / 1.5)buril-ide/ in the bridge repo

Data flow​

User
  │
  ▼  prompt / command
┌──────────────────────────────────────┐
│  Buril chat panel  (Window → Buril)  │
└──────────────┬───────────────────────┘
               │
               ▼
       ┌───────────────────┐
       │     AgentLoop     │  (Editor/Agent/AgentLoop.cs)
       │  • streams from   │
       │    provider       │
       │  • dispatches     │
       │    tool_use       │
       │  • captures       │
       │    vision PNG     │
       └─────────┬─────────┘
                 │
                 ▼ tool_use
         ┌──────────────────────┐
         │      ITool.Run()     │  (Editor/Tools/*)
         │  3,691 implementations
         └─────────┬────────────┘
                   │
                   ▼ Unity API
            Unity Editor (live process)


External clients reach the same ITools via the MCP server:

                              ┌────────────────────┐
                              │  bridge MCP server │
                              │  :8766 /rpc (HTTP) │
                              │  :8765      (TCP)  │
                              └─────────┬──────────┘
                                        │
   ┌────────────────┬───────────────────┼─────────────────┬───────────────────┐
   │                │                   │                 │                   │
   ▼                ▼                   ▼                 ▼                   ▼
Claude Code     Buril IDE         Buril Studio       Buril Cloud         Future
(external)      (VS Code fork)    (React Flow)       (workers)           integrations
 — shipped       — Y2 Q1           — Y1 Q3            — Y1 Q4

The bridge is the only component that touches the live Unity Editor. Everything else is a UX layer over the JSON-RPC surface.

What runs where​

Inside the Unity Editor process:

  • The bridge UPM package, all ITool dispatch, the MCP server (both HTTP and TCP transports), AgentLoop, vision feedback capture, the local RAG index (~30 MB resident when loaded), CLIP/MiniLM Sentis inference.
  • One TCP listener on 127.0.0.1:8765 and one HTTP listener on 127.0.0.1:8766/rpc. Both are loopback-only by default and gated by either a bearer token (default) or OAuth 2.1 with DCR + PKCE (opt-in).

As a subprocess of the Editor:

  • The subprocess CLI providers (claude, codex, copilot). Each is spawned via --print mode, fed conversation history via stdin, streams stream-json events to stdout. One spawn per chat turn — not per tool call.
  • The 3 companion DCC MCP servers (buril-daz-mcp, buril-zbrush-mcp, buril-cascadeur-mcp) — Python MCP servers that proxy to the actual DCC tool process. Optional; only loaded if you've installed them.

As an external process on the same machine:

  • A Claude Code terminal session connecting via the npm relay (@anthropic-ai/mcp-relay buril --url http://127.0.0.1:8766/rpc) or directly via the HTTP transport with a bearer token.
  • The Buril Editor (VS Code fork) when Y2 Q1 ships — same loopback HTTP connection.
  • The Buril Studio web canvas when Y1 Q3 ships — same loopback HTTP connection.

Never on the wire by default:

  • Your code. Your scene data. Your provider key. Buril does not phone home; the only network traffic is what your provider key triggers.

Compose paths​

Three reasonable ways to drive Buril:

  1. Inside Unity, chat panel. Open Window → Buril → Bridge Window. Pick a provider. Type prompts. The fastest end-to-end loop — provider streams, AgentLoop dispatches, vision feedback runs, scene updates. Default.
  2. From Claude Code terminal. Add Buril as an MCP server (see BYOK providers for the claude mcp add command). Now any claude session has the 3,691 ITools available in its tool catalog. Best when you're already in a Claude Code workflow and want Buril's tools next to your other MCP servers.
  3. From the Buril Editor (Y2 Q1) or Buril Studio (Y1 Q3). Auto-discovers on 127.0.0.1:8766/rpc out of the box. Same tool catalog, different UX.

All three paths hit the same MCP server, dispatch the same ITools, and produce the same scene mutations. The chat panel UX is a wrapper, not the contract — every other path is equally first-class.