Skip to main content
Version: 0.6.3

Your First Conversation

You've installed the plugin and connected an MCP client. This page walks through what actually happens when you open the editor and have your first real conversation with Claudus. The examples are taken from a live session — both the friction and the recovery patterns shown below are real, not idealised.

Connecting as an agent, not as a human?

If you're an AI agent (Codex, another Claude Code session, Cursor, Windsurf, or a custom MCP client) and you need the exact wire-level commands to connect programmatically — JSON-RPC payloads, dispatch.json discovery, recovery when the runtime is stale, and the execution-agent work loop — read Agent Bootstrap Protocol. This page is the human-facing walkthrough; that one is the agent-facing runbook.

What you'll see on a fresh launch​

  1. Open the Unreal project. ClaudusBridge loads in PostEngineInit and starts the MCP HTTP server on port 3000 by default.
  2. Open the Claudus dashboard tab (Window → Claudus, or use the dock layout's Claudus tab if it's already there). The transcript is empty for a fresh editor session.
  3. Check the status bar. The dashboard's activity strip shows the active provider, model, access mode, MCP tool count, and the runtime port.

0.6.3 behaviour — runtime auto-starts. During Initialize() the plugin checks whether the provider runtime is already alive (by reading <LOCALAPPDATA>/ClaudusBridge/ProviderRuntime/dispatch.json). If it isn't, the plugin calls LaunchDesktop() itself in the background and writes a friendly welcome note to the chat log:

"Welcome to Claudus — starting the provider runtime in the background. Your AI will attach in a moment. Type a message any time; if a provider isn't connected yet, the runtime will catch up and reply."

Within ~2–3 seconds the runtime writes its fresh dispatch.json, and the existing self-heal logic auto-attaches your last-selected provider (read from provider-selection.json). The status bar jumps from No inference provider / mode: handshake to the model display name with no clicks.

If you type before the auto-attach completes, the dashboard input handler triggers LaunchDesktop() + Refresh() itself and shows a single-line note saying the runtime is coming up. You don't need to retype the message — once the provider attaches, the next chat goes through normally.

Manual override — /runtime start still works if you want to force a restart (e.g. after editing the runtime config). /login claude (or /login chatgpt, /login gemini) is the manual attach path when credentials are missing or you want to switch routes.

The /health endpoint as a sanity check​

Before typing anything in the dashboard, you can confirm the editor's MCP layer is healthy from any terminal:

curl http://localhost:3000/health

A healthy response looks like this:

{
  "status": "ok",
  "server": "ClaudusBridge",
  "version": "0.6.3",
  "port": 3000,
  "mcp_initialized": true,
  "tools_count": 567,
  "tools_list_count": 567,
  "registered_tools_count": 566
}

The tools_count reading is the number that propagates everywhere else (docs site, JSON-RPC serverInfo, the dashboard label). The 1-off between registered_tools_count and tools_count is the synthetic ClaudusBridge_guide tool that surfaces in tools/list but isn't a router-registered command.

Your first question​

In the dashboard input box, type a natural-language question. The provider will reason about it and emit tool calls as needed. Example:

Tell me what Unreal project you are connected to, in one short paragraph. Include the project name, current map, and one notable plugin you can see.

What you'll see in the transcript:

[Human]  Tell me what Unreal project you are connected to...

[Claudus]  Claudus is executing `get_project_info` and `get_current_map`
           natively and will return the results in this chat. I'll
           summarize project name, current map, and one notable plugin
           once those tool results come back.

[System / action-request]   Action request queued for claudus
                            (id=B01673A8…, capability=mcp): Get project
                            identity, enabled plugins, and content roots
[System / action-request]   Action request queued for claudus
                            (id=BE876665…, capability=mcp): Get the
                            currently loaded map
[System / action-auto-exec] Claudus Native Tool Executor started
                            `get_project_info` (id=B01673A8…)
[System / action-auto-exec] Claudus Native Tool Executor started
                            `get_current_map` (id=BE876665…)
[Agent / action-result]     Action result from Claudus Native Tool
                            Executor (id=B01673A8…, success=true): …
[Agent / action-result]     Action result from Claudus Native Tool
                            Executor (id=BE876665…, success=true): …
[System / message]          Auto-continuation batched (action BE876665…
                            deferred; previous continuation 7 ms ago
                            will absorb this result from the chat log).

[Claudus]  Connected to **MyGame** (UE 5.7, at `<ProjectDir>`),
           currently on the unsaved map **Untitled_1** (`/Temp/Untitled_1`).
           One notable plugin: **Oceanology**, a project plugin enabled
           in the .uproject with its own mounted content root at
           `/Oceanology/`.

A few things to notice:

  1. The provider doesn't claim facts before evidence arrives. The first message says "I'll summarize … once those tool results come back" — not a made-up answer.
  2. The action queue shows everything. Each tool call gets its own system entry: action-request (queued), action-auto-exec (run by the Claudus Native Tool Executor), action-result (evidence). You can read along.
  3. Multiple results in the same window get batched. When two tool results land within ~500 ms of each other, you see Auto-continuation batched — the second result rides the existing provider continuation instead of triggering a new one. That's the auto-continuation savings telemetry from 0.6.x doing its job.
  4. Only after evidence lands does the provider give a final answer. The last [Claudus] entry is the real answer with concrete facts.

Asking the provider to do real work​

The same pattern handles edits. Example:

Spawn a basic shape: a blue Sphere labeled DocsHello at world location [0, 0, 200]. Then call get_actor_transform on it and confirm where it landed.

This one is interesting because it doesn't go smoothly the first time. Real sessions don't, and the plugin is designed for that.

What happened in a real test:

[Claudus]  I'll spawn the sphere and then read its transform back.

[System]  Action queued: spawn_basic_shape
[System]  Action queued: get_actor_transform
[Agent]   spawn_basic_shape → success
[Agent]   get_actor_transform → error: Actor 'DocsHello' not found

[Claudus]  The sphere spawn reported success, but the actor lookup by
           label `DocsHello` failed — meaning the spawned actor likely
           has a different label (UE often auto-suffixes, e.g.
           `DocsHello_1`). Let me find it.

[System]  Action queued: get_actors_in_level
[Agent]   get_actors_in_level → error: Unknown command:
          get_actors_in_level. Similar registered tools: …

[Claudus]  `get_actors_in_level` no existe en este build. Voy a usar
           `get_selected_actors` — el actor recién spawneado normalmente
           queda seleccionado.

[System]  Action queued: get_selected_actors
[Agent]   get_selected_actors → success: 0 selected
…

Two failure modes resolved in real time:

  • API success ≠ visual success. spawn_basic_shape reported success=true, but get_actor_transform by the supplied label couldn't find the actor. The provider didn't trust the success message; it ran a follow-up lookup, got an error, and corrected course.
  • Unknown command auto-feedback. When the provider tried get_actors_in_level (which doesn't exist in this build), the router didn't just return an error — it returned a list of similar registered tool names + the auto-observation entry was tagged kind:unknown_command. The provider read the suggestion list and picked get_selected_actors for the next attempt.

This kind of recovery is the verification gap closing in real time, with zero manual prompt engineering. Every failure gets logged to the auto-observation journal so the next session sees the lesson without having to re-derive it. See Auto-Observations for how to read the journal.

Where the conversation lives​

Several places, all in sync:

  1. The Claudus dashboard transcript — color-coded by role (Human / Agent / Claudus / System), with quick actions and the live activity strip.
  2. The Unreal Output Log — every chat entry also routes through native UE log categories (LogClaudusUser, LogClaudusAgent, LogClaudusSystem, LogClaudusChatGPT, LogClaudusClaude, LogClaudusGemini). Use /logs claudus to filter the Output Log to just those categories.
  3. Disk — &lt;ProjectDir&gt;/Saved/Logs/&lt;Project&gt;.log gets the entries too, so you can tail them from any terminal or grep them later.
  4. get_claudus_chat_log MCP tool — any connected MCP client can call this to read the transcript programmatically.

Models and providers​

The plugin ships three provider routes (Claude / ChatGPT / Gemini) and several models per route. Pick any of them from the dashboard or the Output Log:

/provider claude              # account route
/model claude-opus-4.7-1m     # exact model (alias: opus 4.7 m)
/connect                      # activate

# or in one go:
/login claude                 # opens the login flow, defaults to a sensible model

The full model catalog is available with /models. Short aliases (opus m, sonnet, haiku, flash, mini, codex) work but the long names are recommended for clarity in logs and scripts.

See Native Editor Conversation for the complete command reference and the multi-AI shared-transcript story.

What gets generated on your first connect​

The plugin auto-writes a handful of files when the MCP initialize handshake completes for the first time. The files refresh on every reconnect (idempotent — they only get rewritten if the content changed) so you can safely delete them:

  • Saved/ClaudusBridge/CLAUDE.md — Full plugin reference for AI assistants (~150 KB)
  • Saved/ClaudusBridge/CLAUDUS_AI_SKILL.md — Provider-facing operating manual
  • Saved/ClaudusBridge/UE5_EDITOR_CONTROLS.md — UE5 shortcut reference for agents driving the editor through WebRTC
  • Saved/ClaudusBridge/cb.py — Ergonomic Python helper for everything in this guide
  • Saved/ClaudusBridge/watcher_subagent.prompt.md — Canonical prompt for the visual watcher sub-agent
  • Saved/ClaudusBridge/claudus_agent.prompt.md — Portable execution-agent prompt for Codex / Claude Code / Cursor / Windsurf
  • Saved/ClaudusBridge/claudus_documentation_agent.prompt.md — Documentation-specialist prompt
  • Saved/ClaudusBridge/claudusbridge_watcher.py — Persistent Python watcher daemon
  • Saved/ClaudusBridge/claudusbridge_offline.py — Standalone MCP stdio server for offline build/clean/launch tools
  • Saved/ClaudusBridge/CompanionAgents/ — Install packages for Claude Code, Cursor, Windsurf, Gemini CLI (one folder per host)
  • Saved/ClaudusBridge/CodexAgentRuntime/ — Codex-specific runtime package
  • Saved/ClaudusBridge/ClaudusAgents/ — 16 native agent manifests
  • Saved/ClaudusBridge/ClaudusSkills/ — 19 native skill manifests

Plus session state (these accumulate over time, not regenerated):

  • Saved/ClaudusBridge/claudus_memory.jsonl — Auto-observation ring buffer (256 entries, FIFO)
  • Saved/ClaudusBridge/feedback.jsonl — Plugin-improvement signal from record_feedback
  • Saved/ClaudusBridge/memory/ — Explicit topic-curated memory (framing.md, materials.md, …)
  • Saved/ClaudusBridge/WorkflowCheckpoints/ — Snapshots from claudus_checkpoint_workflow
  • Saved/ClaudusBridge/MultiAgentWorkflows/ — Durable workflow records
  • Saved/ClaudusBridge/TaskPlans/ — Single-agent multi-step plans
  • Saved/ClaudusBridge/ActionResults/ — Evidence JSON from every executed action

See Generated Files Reference for what each file contains, when it regenerates, and how to read it.

Where to go next​