# Unreal AI Connection — agent context

**Read [`docs/HANDOFF.md`](docs/HANDOFF.md) before doing any substantive work.** The "Closing notes from prior sessions" section at the bottom captures what the previous agent was carrying in working memory — the latest entry is the operative one for resuming.

## Quick orientation (deeper detail in HANDOFF.md and ARCHITECTURE.md)

UE 5.7 plugin + Python bridge exposing editor automation to MCP-compliant clients (Claude Code, Codex CLI, Cursor, Gemini CLI, Continue, …) over a localhost TCP socket. **105 tools total: 72 native C++ handlers + 33 bridge-side synthetic tools.** Vendor-neutral — the wire protocol is open MCP; the "Claude" in the repo name is decorative.

## Where to look first for any change

- **C++ handlers** (72) — `UnrealClaudeMCP/Source/UnrealClaudeMCP/Private/MCP/Handlers/Handler_*.cpp`, one per tool. Registered in `UnrealClaudeMCPModule.cpp` (the `Reg.Register(...)` block).
- **Bridge-side synthetic tools** (33: `wait_for_events`, `get_camera_transform`, `set_camera_transform`, `screenshot_actor`, `compile_mod_pak`, `compile_mod_pak_direct`, `bulk_delete_assets`, `bulk_move_assets`, `bulk_rename_assets`, `bulk_duplicate_assets`, `bulk_inspect_assets`, `inspect_data_asset`, `inspect_sound_class`, `inspect_sound_submix`, `inspect_audio_bus`, `inspect_material_function`, `inspect_metasound`, `find_unused_assets`, `get_reference_chain`, `bulk_compile_blueprints`, `audit_blueprint_compile_status`, `find_actors_by_class`, `bulk_focus_actors`, `bulk_screenshot_actors`, `bulk_set_actor_property`, `compare_assets`, `bulk_set_console_variables`, `inspect_dependency_graph`, `bulk_fix_redirectors`, `marketplace_search`, `marketplace_import`, `convert_hdri_to_cubemap`, `sequencer_add_transform_keyframe`) — `bridge/unreal_ai_connection_bridge.py`'s `SYNTHETIC_TOOLS` dict.
- **Tool catalog (kept in sync manually across three places)** — `UnrealClaudeMCP/Resources/mcp_manifest.json`, `bridge/unreal_ai_connection_bridge.py`'s `TOOLS` list, and `docs/TOOLS.md`. The `tests/test_manifest_sync.py` suite catches drift between the first two.
- **Architecture notes + UE 5.7 API gotchas** — `docs/ARCHITECTURE.md`.
- **Host-build runbook** — top of `docs/HANDOFF.md` (steps 1–6, PowerShell). Live verification on the host machine is the perpetual next step.
- **Per-tool JSON schemas + examples** — `docs/TOOLS.md`.
- **Restart-recovery procedure** (use after a fresh OS install / C: format) — [`docs/RESTART-RECOVERY.md`](docs/RESTART-RECOVERY.md). Step-by-step setup (git, gh, Node, Python, VS C++ workload, Codex CLI, Claude Code, UE 5.7) plus how to restore session memory from `docs/session-memory-archive/`.
- **Session memory archive** — [`docs/session-memory-archive/`](docs/session-memory-archive/). Snapshot of Claude Code's per-project memory files (directives, conventions, operational gotchas) — survives format because it lives in the repo. Restore to `~/.claude/projects/.../memory/` post-recovery.

## House rules carried forward across sessions

- **One handler = one `.cpp` file** in `Source/UnrealClaudeMCP/Private/MCP/Handlers/`, plus one `extern` declaration and one `Reg.Register(...)` line in `UnrealClaudeMCPModule.cpp`. Don't grow the foundation; add leaves.
- **Verify UE API claims against UE 5.7 source** before committing C++. Past reviewer agents have asserted UE APIs that turned out wrong.
- **Vendor-neutral framing** in any user-facing copy — repo description, `.uplugin` Description, README, tool descriptions. Don't bake "Claude Code" specifically into anything that ships.
- **Smoke test runs against a live UE editor** (`examples/smoke_test.py` hits `127.0.0.1:18888` directly). Bridge unit tests under `tests/` run without UE.
- **Live UE launches are pre-authorized by default in any session.** The maintainer granted standing permission on 2026-05-12 morning: "we always use Unreal for testing if you want." No need to ask each session. Launch UE 5.7 against the host project at `F:/ax plug in/HDMediaVirtualStudio/HDMediaVirtualStudio.uproject` whenever live verification is the next step. **Path-quoting recipe (critical — `Start-Process -ArgumentList @('path with spaces')` splits the path on whitespace and UE falls back to Project Browser):** `Start-Process 'F:\UE_5.7\Engine\Binaries\Win64\UnrealEditor.exe' -ArgumentList '"F:\ax plug in\HDMediaVirtualStudio\HDMediaVirtualStudio.uproject"'` (pre-quote the path inside the array element). UE typically binds `127.0.0.1:18888` in ~2 minutes after launch; if CPU stays at ~7% one core and `Saved/Logs/HDMediaVirtualStudio.log` is stale, the launcher likely fell through to Project Browser — re-check the path-quoting.
- **Delegation-by-default (token conservation).** Every concrete work step goes to a sub-agent. Main Opus thread plays leader / integrator / decision-maker only — receives summaries, makes calls, ships. Concrete routing: file search / grep / repo exploration → Sonnet code-explorer or Explore agent; code review of in-flight diffs → local OSS LLM runtime (see private workflow config — coding-focused reasoning model + fast small instruction model in parallel) and GitHub PR bots (rule #5); both free, zero Claude tokens. Claude sub-agents (Sonnet code-reviewer, codex-rescue) reserved for true escalation when local capability is insufficient or for diff classes the GitHub bots historically miss; C++ implementation → Codex CLI; UE 5.7 API verification → codex-rescue or NVIDIA cloud reasoning agent; multi-file mechanical edits → general-purpose agent or `caveman:cavecrew-builder` (≤2 files); bot-review readout → delegated agent reads + summarises; memory file writes → delegated agent. Main thread NEVER does work a sub-agent can do; reserves itself for orchestration + integration + final decisions. Reason: the maintainer's Claude session token budget is the constraining resource; sub-agent runs do not bill against it. Sub-agents are the fleet; Opus is the captain.
- **Bot-review gate before any merge.** Never blind-merge a PR. After CI green + before `gh pr merge`, read every bot review on the PR. Current roster (2026-05-13): Gemini auto-review, CodeRabbit, chatgpt-codex-connector (Codex GitHub bot), greptile-apps, GitHub Copilot CLI. Any future bot the maintainer wires up joins the same gate. For each bot finding: **Apply** as a follow-up commit on the same branch (preferred for small fixes), OR **Dismiss** with explicit reason posted as a PR comment (e.g. "false positive: Build.cs:19 already has the dep" — verifiable claim). Bots regularly surface real defects the pre-commit ensemble missed; worked examples — PR #161's P0 `UInputSettings::GetActionMappings(NAME_None, ...)` non-existent overload (chatgpt-codex-connector caught post-merge); PR #162's vendor-neutral manifest regression (CodeRabbit caught); PR #164's three P2 follow-ups on error-code reuse / cached-state inconsistency / cross-handler `class` shape drift (greptile-apps + chatgpt-codex-connector caught). Blind-merging discards this safety net. **Mechanical-fix follow-up exception (reconciles with directive #7):** when a follow-up commit on the same branch applies bot findings as direct surgical fixes (no new logic — e.g. add quote-around-identifier, split error-code, cache a state read, restore a field name for parity), self-merge is permitted without waiting for a second-pass bot review since the bots' first pass already directed the fix. New-logic commits still require a fresh bot pass before merge.
- **Push to feature branches, never directly to `main`.** Open a PR; the user merges.
