A small launcher / orchestrator for Unreal Engine projects: it starts and
supervises the Unreal Editor and an agent (e.g. Claude Code), and gives the
agent an to drive the editor, trigger builds, read logs, and run
Python/Node code in prepared runtimes.
Slim launcher/orchestrator for Unreal Engine projects: supervises UE + agent, with a built-in MCP server (editor control, build, runtimes, permissions). Dependency-free, cross-compilable Linux -> Windows.
MCP server
A single .exe — cross-compilable from Linux to Windows. Stdlib Go only,
plus one vendored YAML parser; vendor/ is checked in, so builds are
offline-reproducible.
Full working example — a real UE project wired to Claude Code with both MCP
servers running: unreagent-example.
The launcher hands the agent both via --mcp-config (mcp.extraServers in
the config), so the agent does not have to wire anything up itself. Stdio
bridges are fully checked before the agent starts, with each step logged
loudly, instead of letting the agent run into a meaningless -32000
connect error: binary on PATH? bridge script present? node_modules there
(or run npm install)? does the bridge answer a real initialize handshake
(smoke test)? And once the in-editor server (UNREAL_MCP_URL) is reachable,
that's logged too — or a warning with the usual suspects if it isn't.
The same config can additionally be written to a file for external clients
(your own Claude session, Cursor, VS Code). Via mcp.writeConfig (a list of
{path, format}, format mcp_json or vscode) or the flag
-write-mcp-config <path>. Handy with -no-agent: the launcher writes the
.mcp.json and keeps UE + MCP running, you connect externally.
Building
Requirement: Go (>= 1.19). Dependencies are vendored (vendor/); builds run
offline.
make windows # -> dist/unreagent.exe (cross-compile from Linux)
make linux # -> dist/unreagent (for local tests)
make all
Or directly:
GOOS=windows GOARCH=amd64 go build -ldflags "-s -w" -o dist/unreagent.exe ./cmd/launcher
Windows: metadata & "Unknown Publisher"
The .exe carries an icon + version info (CompanyName, ProductName,
description, copyright) and an asInvoker manifest (no UAC elevation
prompt). This fills Properties -> Details and the program name in dialogs.
The "Unknown Publisher" warning itself comes from the signature, not
from metadata. Two paths:
A) Self-signed (in the repo, for your own team / known users) — the
.exe is signed with a self-signed certificate from "conflict.industries
digital GmbH". Users import the public certificate once:
powershell -ExecutionPolicy Bypass -File signing\import-cert.ps1 # as admin
After that: no publisher warning, the GmbH appears as publisher. Details
and trade-offs: signing/. (The private key is not in the
repo.)
B) CA certificate (for a wider audience) — an OV / EV code-signing
cert does not need user-side import (EV gives immediate SmartScreen
reputation). With such a cert you also sign the .exefrom Linux
(osslsigncode).
Change publisher / version: cmd/launcher/versioninfo.json -> make resource.
Try it now (demo)
The release zip ships a ready-to-go demo unreagent.yaml that runs without
UE and without an agent (ping as a placeholder "editor"). Just unpack the
zip and start unreagent.exe — the MCP server will then run on
http://127.0.0.1:8765/mcp. Details: example/. In the console:
status, logs, c hello, r ue, q.
The "LLM thing" (Claude Code) is not included — it is a CLI you install
separately. The demo therefore leaves the agent off; to arm it, set
agent.enabled: true (see below).
Use example/ to poke at the MCP server without installing UE or an agent.
For the real thing — a UE project with Claude Code driving both
unreagent-MCP and the in-editor MCP together — clone the standalone
unreagent-example repo:
env UE_ROOT -> engineRoot (local.yaml) -> auto-detect of the Epic default paths
${PROJECT} / ${PROJECT_DIR} / ${PROJECT_NAME}
.uproject next to the config (auto-detect)
Machine-specific overrides go in a git-ignored unreagent.local.yaml,
which is overlaid on top of unreagent.yaml:
# unreagent.local.yaml (DO NOT commit)
engineRoot: "D:/UE/UE_5.7" # if auto-detect fails
agent: { command: "C:/.../claude.cmd" } # if claude is not on PATH
Recommended .gitignore entry in the UE project:
unreagent.exe
unreagent.local.yaml
When the agent ends (/quit or crash)
In window mode the agent is the lead process — if it ends (e.g. /quit) and
is not restarted, the launcher prompts on the console (agent.onExit: ask,
the default):
Agent ended.
[Enter] shut down everything (UE + launcher)
[k] keep editor running, drop to launcher console
[r] restart the agent
> _ (30s -> shut down everything)
Without a TTY (headless -p), it shuts down cleanly instead. Alternatives:
onExit: shutdown (always shut everything down immediately) or onExit: leave
(everything keeps running, warning only — manual Ctrl-C required).
In-editor MCP: UE LLM Toolkit setup (Windows)
For the agent to work inside the editor (blueprints, assets, levels, UE
Python), the UE project needs the in-editor plugin. The short version:
drop the plugin into the Plugins/ folder — done. No .uproject patching,
no enabling in the plugin browser.
What the machine must have
Component
What for
Note
Unreal Engine 5.7
the editor itself
auto-detect via registry / default paths; otherwise engineRoot in unreagent.local.yaml
Visual Studio 2022 ("Game development with C++" workload)
once to build the plugin
the plugin ships as C++ source; UE asks "rebuild?" on first start
Node.js >= 18
the plugin's stdio bridge
npm install for the bridge is done by the launcher automatically
Claude Code
the agent
claude on PATH; otherwise agent.command in local.yaml
Drop the plugin into the project — copy or clone the repo/folder to
<Project>/Plugins/UELLMToolkit/. The .uplugin has
EnabledByDefault: true and activates its own engine dependencies
(EditorScriptingUtilities, Niagara, ControlRig, IKRig, ...) — nothing
to change on the .uproject.
First editor start — UE reports "Missing Modules ... rebuild?" -> Yes.
The build needs Visual Studio (once; afterwards the binaries live in the
plugin). Alternatively ahead of time via the launcher: console -> c compile.
Done. The plugin's HTTP server starts with the editor automatically on
port 3000. The launcher forwards the bridge via --mcp-config to the
agent — for that, in unreagent.yaml:
Optional: For unreal_execute_script with Python scripts, enable the UE
plugin "Python Editor Script Plugin" (Edit -> Plugins) — the other
tools don't need it.
What the launcher does automatically on startup (see above): install
bridge node_modules, check binary / script, initialize smoke test, wait
for port 3000 — every step with a clear message in unreagent.log.
Access from another machine
The UE HTTP server binds to localhost by default. If a remote Claude session
should reach the in-editor server (port 3000) directly:
; Config/DefaultEngine.ini of the UE project
[HTTPServer.Listeners]
DefaultBindAddress=any
Plus a Windows firewall rule for port 3000 — and only in trusted networks,
the server controls the entire editor. On the other side UNREAL_MCP_URL
then points to http://<windows-ip>:3000.
Troubleshooting: "Failed to reconnect: -32000"
-32000 from Claude Code just means "bridge process immediately gone again"
— the real cause is in unreagent.log (check chain) or in Claude Code's MCP
logs (%LOCALAPPDATA%\claude-cli-nodejs\Cache\<project>\mcp-logs-*). Usual
suspects, in this order:
Bridge path wrong (Cannot find module ...) — check the path in
extraServers against the real plugin layout.
Node missing or not on PATH in the agent's session.
node_modules missing — this no longer happens, the launcher installs
them.
Editor (not yet) reachable — port 3000 only appears once the editor
is fully up; the launcher logs once it is.
Configuration (quick reference)
Section
Purpose
agent
agent command + args; claudeIntegration injects --mcp-config (+ permission tool); window (on by default) = interactive in the foreground (inherits console / TTY, launcher logs -> unreagent.log); on Windows, claudeIntegration additionally sets CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (powershellTool: false to disable)
permissions
permission layer: allow_all / allowlist (default if unset) / deny_all, plus allow / deny rules — Bash(...) rules are matched per shell segment, see Permission layer below
runtimes
python (via uv run) and node for run_python / run_node
mcp
MCP server on/off, address (default 127.0.0.1:8765), optional token (Bearer auth — auto-set by hermes-setup); every request needs Content-Type: application/json and, if present, a loopback Origin — see MCP server hardening below
optional — your own one-shot commands (compile / package are built-in)
engineRoot
usually only in local.yaml — engine path override
No process zombies (Windows)
Every running instance is attached to a Windows Job Object with
KILL_ON_JOB_CLOSE. If the handle closes — by clean stop, restart,
or crash / hard-kill of the launcher — the operating system terminates
the entire process tree (including ShaderCompileWorker etc.). OS-enforced,
no external dependency. On Linux (development) only the direct child is
killed.
Crashes & recovery (unattended)
Two UE dialogs otherwise block agent-driven operation: the crash reporter
("Send and Restart / Close") and the recovery prompt on restart
("not closed cleanly, restore?"). The launcher therefore starts the editor
with -unattended — this suppresses both in UE 5.7 code (crash
dialog and both recovery systems: PackageAutoSaver and disaster recovery)
and discards the unclean state instead of asking.
Option (unreal:)
Default
Effect
unattended
true
appends -unattended — no crash dialog, no recovery prompt
killCrashReporter
true
kills CrashReportClientEditor.exe before every (re)start (belt and suspenders)
If a human is working interactively in the editor in parallel, set
unattended: false. In addition (so the reporter never even sends/starts)
in the project:
With permissions.enabled + agent.claudeIntegration the launcher starts
the agent with --permission-prompt-tool mcp__unreagent__approve — but
only in headless mode (agent.args contains -p/--print, or
agent.window: false). Every permission prompt from Claude Code then goes
through the approve tool, which decides per the configured policy.
Interactive window mode (the default) does not enforce the policy this
way. With mode: allow_all the launcher passes
--dangerously-skip-permissions instead (Claude Code's own prompting is
skipped entirely); with any other mode no flag is added and Claude Code
prompts the user directly in the window, same as without unreagent. To have
the policy actually enforced, run headless or drive Claude Code externally
against the MCP server (-no-agent).
Modes: allow_all = auto-approve everything, deny rules still apply (e.g.
Bash(rm -rf *)); allowlist (the default when mode is unset) = deny
everything except what an allow rule matches — the only mode that fails
closed by construction; deny_all = reject everything.
Bash(...) rules are matched per shell segment, not against the whole
command line: the command is split on ;, &&, ||, |, newlines, on
$(...)/backtick bodies, { ... } groups, and on the script handed to a
nested bash -c/sh -c. A deny rule matches if any segment matches
(so cd /tmp && rm -rf / cannot walk past a deny rule for Bash(rm -rf *));
an allow rule requires every segment to be covered by some allow rule
(so git status | head needs both Bash(git *) and Bash(head *), and
cd /proj && git status needs both Bash(cd *) and Bash(git *)). Deny
matching additionally normalizes whitespace/quotes/escapes, reduces a
path-qualified command to its base name (/bin/rm -> rm), and looks
through wrapper commands (sudo, env, eval, xargs, ...) at what they
wrap. This is a heuristic, not a shell parser — it cannot follow variable
indirection, aliases, or data piped into an interpreter (python -c ...). A
deny list under allow_all is a guard rail, not a security boundary.
Bracket rules also work on non-Bash tools, matched against the tool's
path-like input — Write(/etc/*), Read(/secrets/*),
mcp__unreagent__write_file(/etc/*). A rule whose tool carries no evaluable
input field fails closed: a deny rule still blocks, an allow rule still does
not grant.
Windows:claudeIntegration sets CLAUDE_CODE_USE_POWERSHELL_TOOL=1 by
default (see the agent row above), so Claude Code's shell tool is named
PowerShell, not Bash — write rules as PowerShell(...) there (e.g.
deny: ["PowerShell(Remove-Item *)"]). The segment splitter above is
POSIX-shaped; there is no PowerShell-specific tokenizer yet.
Note: the exact input schema of --permission-prompt-tool is not
officially documented by Anthropic. The approve handler reads the tool
fields defensively (tool_name / toolName / name,
tool_input / input / arguments). If a Claude Code update changes the
format, only that one handler in cmd/launcher/main.go needs adapting.
Hermes Agent (alternative agent)
Hermes Agent (Nous Research)
is an autonomous agent with its own MCP client — useful as an alternative to
Claude Code. unreagent plugs in by registering the same MCP server
(ue_start / ue_stop / logs / run_command / run_python / …) under
Hermes' mcp_servers: block. The launcher does not auto-merge on
normal runs; you opt in once with a sub-command:
# unreagent.yaml
agent:
hermes:
enabled: true
unreagent hermes-setup # merges MCP entry into ~/.hermes/config.yaml
What hermes-setup does, in order:
Resolves the target config: explicit agent.hermes.configPath →
$HERMES_HOME/config.yaml → ~/.hermes/config.yaml.
If mcp.token is empty, generates 32 random bytes (hex) and writes
mcp.token: into unreagent.local.yaml (git-ignored). The launcher
reads it back on the next start, so the token survives restarts.
Backs up an existing Hermes config to <path>.bak (once; never
overwrites a previous backup).
Sets mcp_servers.unreagent: { url, headers: { Authorization: Bearer } }
in the Hermes config. A second run overwrites the entry rather than
duplicating it — the operation is idempotent.
Writes the file atomically (temp + rename) so a crash mid-write cannot
leave a half-written config.
The MCP server enforces Authorization: Bearer <token> whenever
mcp.token is set — including for the embedded Claude Code agent, which
gets the matching headers: block in its --mcp-config automatically.
The token check uses crypto/subtle.ConstantTimeCompare; the empty-token
default (the historic behaviour) keeps the server open on 127.0.0.1.
Restart Hermes after running hermes-setup so it picks up the new entry.
Runtimes for the agent
run_python executes code via uv run python — uv builds / syncs the venv
automatically from pyproject.toml / requirements and installs the right
Python version on demand. run_node runs JS in the project context. Both
tools write the script into the runtime's working directory (not a system
temp directory) and run it from there, so run_python can import modules
that sit next to pyproject.toml and run_node resolves bare imports
through the project's node_modules. The agent does not have to analyse
or set up the environment itself; the instructions are in the MCP tool
description and are therefore automatically in context.
MCP tools
Tool
Function
status
process status + available commands — a service whose control loop misses the internal 10s timeout is reported as "unresponsive": true (running/pid unknown, sent as false/0) instead of being dropped from the list
ue_start / ue_stop / ue_restart
editor lifecycle
run_command
run a preconfigured command (compile, package)
logs
last output lines of a service
run_python / run_node
run code in a prepared environment
read_file / list_dir / write_file / edit_file
file access on the project (only with files.enabled / -files, scoped to root)
approve
permission prompt tool for Claude Code
MCP server hardening
The /mcp HTTP endpoint rejects malformed or unexpected requests instead of
guessing:
Every POST must carry Content-Type: application/json — anything else
gets 415 Unsupported Media Type (the manual test below already sets it).
A request that carries an Origin header is rejected with 403 Forbidden
unless the origin is loopback (http/https on localhost, 127.0.0.1
or ::1, any port) — a defence against a web page in the user's browser
driving the launcher (CSRF/DNS-rebinding). Requests without an Origin
header — every non-browser MCP client, including Claude Code and curl —
are unaffected. The allowlist is not yet configurable, so a browser-hosted
client on another origin cannot be pointed at unreagent today.
initialize negotiates protocolVersion against 2025-06-18 (default)
and 2025-03-26; any other value is answered with the default rather than
echoed back, since this server implements only the Streamable-HTTP
transport (no SSE, no sessions).
Connection timeouts guard against a wedged socket: ReadHeaderTimeout 10s,
ReadTimeout 60s, IdleTimeout 120s. WriteTimeout is 4h — the ceiling
for a single tool call, so a long-running run_command (e.g. a full UE
build) has room; it is a backstop, not a request budget.
CLI flags
Flag
Effect
-config <path>
alternative path to unreagent.yaml
-no-agent
do not start the agent — only UE + MCP server. An external agent (your own Claude Code session) then connects to the MCP server.
-files
enable the file tools (read_file / write_file / list_dir / edit_file) even if off in the config.
-write-mcp-config <path>
additionally write the assembled MCP config as .mcp.json to <path> (for external clients).
Sub-commands
Sub-command
Purpose
unreagent hermes-setup
One-shot merge of the unreagent MCP server into Hermes Agent's config.yaml (idempotent; auto-generates mcp.token if missing). See "Hermes Agent" above.
How the agent runs (three modes)
Claude Code is an interactive TUI and needs a TTY — as a raw background
subprocess it won't start. Hence three ways:
Interactive in the foreground (agent.window, on by default) — the
agent inherits the real console (TTY) and runs as an interactive TUI in
the window you started unreagent in. UE + MCP run in the background,
launcher logs go to unreagent.log (next to the project) so the agent
has the window to itself. Disable with window: false; off in -p mode.
Headless / task (agent.args: ["-p", "<task>"]) — one-shot task
without a window, then the agent exits.
External (-no-agent) — the launcher does not start an agent; you
connect your own Claude session with the .mcp.json / the MCP server.
Headless / external agent
With -no-agent everything runs without an embedded agent — UE + MCP server.
That's how you hook up your own Claude Code to work on the project "without
anyone being present locally":
unreagent.exe -no-agent -files # UE + MCP + file tools, no embedded agent
# in your Claude Code session:
claude --mcp-config '{"mcpServers":{"unreagent":{"type":"http","url":"http://127.0.0.1:8765/mcp"}}}'
For access from another machine set mcp.address to 0.0.0.0:8765 (only
in trusted networks — the server then has file-write access).
Manual control (stdin)
status · r [name] (restart) · start <name> · stop <name> ·
c <name> (run command) · q (quit)
Slim launcher/orchestrator for Unreal Engine projects: supervises UE + agent, with a built-in MCP server (editor control, build, runtimes, permissions). Dependency-free, cross-compilable Linux -> Wind
Slim launcher/orchestrator for Unreal Engine projects: supervises UE + agent, with a built-in MCP server (editor control, build, runtimes, permissions). Dependency-free, cross-compilable Linux -> Windows.
Ferramentas
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Unreagent?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.