Installation

Prerequisites

Step 1: Plugin Installation

Option A: Retail / Epic Games Launcher Build

Copy the AgentUX folder (the one containing AgentUX.uplugin) into your project's plugin directory:

<YourProject>/Plugins/AgentUX/

The pre-compiled binaries in Binaries/Win64/ are loaded automatically. No compilation needed.

Option B: Source Build

Copy the AgentUX folder into the engine's plugin directory:

<UE Root>/Engine/Plugins/Experimental/AgentUX/

Build the plugin (from a terminal in your UE root):

Engine/Build/BatchFiles/Build.bat UnrealEditor Win64 Development -Module=AgentUX

This incremental build takes approximately 10 seconds.

Enable the Plugin

Add to your project's .uproject file:

{
  "Plugins": [
    { "Name": "AgentUX", "Enabled": true }
  ]
}

Step 2: Run the Installer

From the AgentUX root directory:

python install.py

The installer performs the following steps:

1. Installs Python dependencies (Bridge + GraphRAG)
2. Detects Neo4j (if running) and configures credentials
3. Restores the pre-built knowledge base into Neo4j
4. Validates the ONNX embedding model
5. Generates MCP configuration for Claude Code

Plugin-Only Install (No Neo4j)

To start with editor control only and skip the knowledge base:

python install.py --skip-graphrag

Everything works without GraphRAG: you just won't have the engine knowledge tools. You can add them later by installing Neo4j and running the full installer.

Step 3: MCP Server Configuration

The installer generates mcp_config.json with two MCP servers. Add its contents to your Claude Code MCP settings.

Full Configuration (Editor Control + GraphRAG)

Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "agentux": {
      "command": "python",
      "args": ["<path-to>/AgentUX/Bridge/agentux_mcp_bridge.py"]
    },
    "ue-graphrag": {
      "command": "python",
      "args": ["<path-to>/AgentUX/GraphRAG/mcp_server/server.py"],
      "env": {
        "GRAPHRAG_CONFIG": "<path-to>/AgentUX/GraphRAG/config.yaml"
      }
    }
  }
}

Editor-Only Configuration

If you used --skip-graphrag, omit the ue-graphrag entry:

{
  "mcpServers": {
    "agentux": {
      "command": "python",
      "args": ["<path-to>/AgentUX/Bridge/agentux_mcp_bridge.py"]
    }
  }
}

The agentux bridge auto-detects whether GraphRAG is available and exposes a graphrag_status tool so Claude can check connectivity at runtime.

CLAUDE.md Template

Copy the provided template into your UE project's .claude/CLAUDE.md. This teaches Claude how to control the editor and verify UE API names before writing code:

# From your UE project root:
mkdir -p .claude
cp <path-to>/AgentUX/Docs/CLAUDE_TEMPLATE.md .claude/CLAUDE.md

Step 4: GraphRAG Setup (Optional)

Install Neo4j Community Server

1. Download Neo4j Community Edition 5.x
2. Ensure Java 21+ is installed (java -version)
3. Extract and start Neo4j:

   neo4j console

   Or install as a Windows service for auto-start:

   neo4j install-service
   neo4j start

4. Verify Neo4j is accessible at bolt://localhost:7687

Build the Knowledge Base

The installer handles this automatically when Neo4j is detected. If you need to rebuild or installed Neo4j after the initial setup:

python install.py --skip-deps

This reconfigures credentials, restores the pre-built knowledge base, and validates the ONNX embedding model.

What GraphRAG Provides

See the GraphRAG Guide for the full tool reference and usage workflows.

Step 5: Verification

Test Editor Control

With the Unreal Editor open, run this Python script to verify the WebSocket connection:

import asyncio, json, websockets

async def ping():
    async with websockets.connect(
        "ws://localhost:9877",
        additional_headers={"Origin": "http://localhost"}
    ) as ws:
        await ws.send(json.dumps({
            "jsonrpc": "2.0", "id": 1, "method": "agentux.ping"
        }))
        print(json.dumps(json.loads(await ws.recv()), indent=2))

asyncio.run(ping())

Expected response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "ok",
    "plugin_version": "3.0.0",
    "ue_version": "5.7",
    "uptime_seconds": 42.5
  }
}

Test Engine Knowledge

If GraphRAG is installed, ask Claude in Claude Code:

"What properties does USpotLightComponent have?"

Instead of guessing from training data, Claude calls get_class_details("USpotLightComponent") and returns the exact property names, types, and metadata from your engine version.

Performance

Tip: Start Neo4j as a Windows service so it's always running when the editor launches.

Troubleshooting

WebSocket connection refused

• Is the editor running with the plugin loaded?
• Is port 9877 in use? Check with netstat -an | findstr 9877
• Are you sending the Origin header? It's required by the WebSocket server.

"Method not found" error

• Use agentux.methods.list to see available methods
• Method names are case-sensitive

Plugin not loading (retail build)

• Ensure the Binaries/Win64/ folder is present (pre-compiled DLLs)
• Ensure "Installed": true is set in AgentUX.uplugin
• Check the Output Log for LogAgentUX messages

Plugin not loading (source build)

• Run the build command with the editor closed
• Verify the plugin folder is under Engine/Plugins/Experimental/

GraphRAG not responding

• Is Neo4j running? Check bolt://localhost:7687
• Run python install.py --skip-deps to reconfigure and test
• Verify GRAPHRAG_CONFIG env var points to the correct config.yaml

Next Steps

• Quick Start: Get running in under 10 minutes
• API Reference: All 558+ methods documented
• GraphRAG Guide: Full knowledge base reference