WARUDO Agent Bridge

English | 한국어 | 日本語

Ask an AI in plain words, and it operates WARUDO for you.

Send a chat message like "Smile, wave, and take one shot from the front." The AI moves the camera in WARUDO, changes the expression, sets the pose, takes the photo and shows it to you. No coding needed. Installing means pasting one command.

The photos above are all real screenshots of the WARUDO default character (Shipilka) running the requests from the examples section through this bridge.

Not affiliated with WARUDO or HakuyaLabs. Free (MIT licensed), made by StudioRaming.

Table of contents

1. What is MCP? (start here if new)

2. What can you do? (examples)

3. Requirements

4. Install (step by step)

5. Connect to an AI app: Claude Desktop, Claude Code, Codex, ChatGPT Desktop

6. First use

7. Safe use

8. FAQ

9. Troubleshooting

10. Advanced

Related MCP server: Unreal-MCP-Ghost

What is MCP?

ChatGPT and Claude can normally only chat in text. They cannot click buttons in a program running on your computer.

MCP (Model Context Protocol) is a common spec for giving tools to AI. Think of USB. The spec is the same everywhere, so it plugs into any AI app.

WARUDO Agent Bridge is a set of MCP tools for WARUDO. Once installed, the AI gets 63 tools: "move camera", "change expression", "set pose", "take photo" and more.

you (ask in chat)
 ↓
AI app (Claude, Codex, ChatGPT Desktop)
 ↓ MCP
WARUDO Agent Bridge (runs on your PC)
 ↓
WARUDO

Good to know:

• AI app and WARUDO must be running on the same PC. The bridge passes data to WARUDO only through files on your PC. It opens no internet port.

• Chat goes to the AI service. What you send and what the AI reads (scene info, captured photos) are handled by that company's servers like normal chat.

• The bridge is free. AI app fees follow each service's pricing.

• Windows only. WARUDO is a Windows program.

What can you do?

Examples of what you send to AI and the result. For each photo, the tools that fit the request were actually run through this bridge on the WARUDO default character (Shipilka). AI replies are shortened. "Tools used" are chosen by AI; you don't need to memorize them.

📸 Photos and camera

"Take a photo from front, diagonal, side and back. Show me all four."

"Widened the field of view to 60 degrees and walked around the character taking four shots." Tools: warudo_camera_zoom → warudo_camera_pose → warudo_camera_capture (four times; shown as one composite here)

😊 Expressions

Each character has different expression names. The AI reads the character's expression list (blendshapes) first, then picks the ones that fit your request. This character had 106.

🙋 Poses

Poses work by saying which way to aim body parts. The bridge prevents impossible joint angles, and returns the result once the pose actually shows on screen.

"Check if the pose is right. Is the foot sinking into the floor?"

"Drew the skeleton without clothes and background from front and side. Knees and feet touch the floor. The shoe tips sink about 0.5cm. The tail ornament reaches 18cm below the floor, so in this sitting pose it will look buried." Tools: warudo_analysis_capture (WARUDO screen does not change)

💃 Animations and outfits

🔎 Scene inspection and undo

💡 More requests like these

All 63 tools are in docs/TOOLS.md.

Tips for good requests

• If you want to see the result, add "and show me a photo" at the end. The AI takes a photo and shows it in the chat.

• If you don't like it, just ask to adjust. "Raise the arm a bit higher", "move the camera a bit left".

• You can make multiple requests at once. "Smile, wave your hand, and take a photo from the front."

• When done, "put it back to normal" resets the expression, pose and camera in one request.

Requirements

Install the AI app and run it once first, then install the bridge. The installer finds AI apps on this PC and connects automatically.

Install

Step 1: Open PowerShell

• Windows 11: Right-click the Start button (Windows logo) at the bottom → Terminal

• Windows 10: Right-click the Start button → Windows PowerShell

A black (or blue) window appears. No admin access needed.

Step 2: Paste the install command

Copy the line below, paste it into the PowerShell window (Ctrl+V or right-click), and press Enter.

irm https://raw.githubusercontent.com/StudioRaming/warudo-agent-bridge/main/install.ps1 | iex

This downloads and runs install.ps1 from this repo. Open the link first if you want to see what it does.

Step 3: Answer questions if they appear

If Node.js is missing, it asks:

Install Node.js LTS now with winget? [Y/n]

Type Y and press Enter. Windows asks "Do you want to allow this app to make changes to your device?" Click Yes. If it says "Open a new PowerShell window and run the installer again", close this window and open a new one, then redo step 2.

Step 4: Check the result

When done, you see (line count varies by which AI apps were found):

WARUDO Agent Bridge 0.2.0
  home:     C:\Users\YOU\.warudo-agent-bridge
  runtime:  C:\...\Warudo\Warudo_Data\StreamingAssets\Playground\WarudoAgentBridge\WarudoAgentBridge.cs
  claude-code     registered (user scope)
  codex           registered
  claude-desktop  registered Restart Claude Desktop to load it.

Next: start WARUDO. A running WARUDO loads the new bridge by itself once Playground recompiles (up to about 30 seconds).
Open a new agent session and ask it to call warudo_status. Check anything odd with: warudo-agent-bridge doctor

• runtime: means the bridge file was placed in WARUDO.

• registered means the AI app's connection is set up. If your app is not listed, see Connect to an AI app.

• Config files that get changed are backed up first to %USERPROFILE%\.warudo-agent-bridge\backups.

Step 5: Restart WARUDO and the AI app

1. Start WARUDO. If it was already running, wait about 30 seconds. WARUDO loads the new file automatically.

2. Fully close the AI app (just closing the window may leave it running in the background. Also close it from the system tray at the bottom right).

Now go to First use.

Connect to an AI app

The installer already registered apps it found. Below is how to verify and what to do if it did not work.

Claude Desktop

• Auto-register location: %APPDATA%\Claude\claude_desktop_config.json

• Verify: Fully close the app and reopen it. Click the + button at the bottom left of the chat box → Connectors → Manage connectors. If warudo-agent-bridge appears, it is connected. You can also see it in Settings Developer tab. When the AI tries to use tools, it asks for permission.

• If connection fails, check %APPDATA%\Claude\logs\mcp-server-warudo-agent-bridge.log for why.

• If the install result did not show claude-desktop: run the app once, then run this in PowerShell:

npx --yes @studioraming/warudo-agent-bridge@latest install --clients claude-desktop

Claude Code

• Auto-register: claude mcp add -s user ... (registers for user scope, works in any folder)

• Verify: Run claude mcp list in a new terminal, or type /mcp inside Claude Code.

• If the install showed manual: the claude command was not found. Run the run: command that came with the result.

Codex (CLI, IDE extension)

• Auto-register location: %USERPROFILE%\.codex\config.toml (also adds tool_timeout_sec = 180 to prevent long captures from timing out)

• Verify: Run codex mcp list or type /mcp inside Codex.

• If the install did not show codex:

npx --yes @studioraming/warudo-agent-bridge@latest install --clients codex

ChatGPT

• ChatGPT web and mobile app general chat cannot use this. General chat can only connect to MCP servers on the internet (HTTPS), but this bridge runs only on your PC.

• ChatGPT Desktop app (Windows) can use this. The desktop app shares the same config file with Codex CLI and IDE extension (%USERPROFILE%\.codex\config.toml), and the installer registers the bridge there.

  1. Install and log into ChatGPT Desktop.

  2. Run the --clients codex command from the Codex section above (skip if the install already showed codex).

  3. In the app, go to Settings → MCP servers and check if warudo-agent-bridge appears. If it does, click Restart.

  4. Type /mcp in the input box to see the connected servers.

• Menu names and available plans may change. As of September 2026, this follows OpenAI docs (MCP setup).

Cursor and other apps

Cursor auto-registers to %USERPROFILE%\.cursor\mcp.json. Other MCP apps: see Manual registration.

First use

1. Open WARUDO with a scene that has a character.

2. Open a new chat in your AI app. (A chat opened before install may not show tools.)

3. Send this:

   Check whether WARUDO is connected, using warudo_status.

   If the reply says it is connected and shows the WARUDO version and the open scene name, it worked.

4. If the AI app asks whether it may use a tool, read what it wants to do and allow it.

5. Now try the examples from What can you do? one by one. Start with "Take a photo of the character from the front" because you see the result right away.

Safe use

• Save important scenes first. Or ask "make a snapshot of the current state first". The bridge also saves a recovery snapshot before opening scenes, restoring snapshots, or deleting assets. It keeps old files when overwriting saved scenes.

• Be careful during streaming. Changes the AI makes show up in WARUDO right away. Do a test run before a real stream.

• Only one AI can change WARUDO at a time. A second AI gets a "busy" reply instead of fighting over the scene.

• Results are honest. If WARUDO closes mid-operation, you get "not run" or "check state". Changes with uncertain results do not auto-retry.

• Unity script calls are off by default. Only methods you allow in the config file can be called.

FAQ

Do I have to pay?
The bridge is free. AI app costs follow each service's pricing.

Do I need to know coding?
No. Just paste one command line at install. After that, ask by chat.

Do I need to install a WARUDO mod?
No. The installer just drops one script file in WARUDO's Playground folder.

Does it work with my character?
Yes. Pose tools work on any humanoid avatar or VRM. Expression names vary by character, but the AI reads the list first and picks the right ones.

Can I ask in my own language?
Yes. Any language the AI app understands. Tool names are English but your requests can be in any language.

Does it work on Mac?
No. WARUDO is Windows only, so the bridge is too.

Can I undo what the AI changed?
Expression, pose, and camera: just say "put it back to normal". For the whole scene, use a snapshot you made first.

How do I update?
Run the install command from Step 2 again. It upgrades to the latest version.

Troubleshooting

To check everything at once:

npx --yes @studioraming/warudo-agent-bridge@latest doctor

Any line that says FAIL is the problem (INFO lines are only information). If you still cannot fix it, copy that output and open an issue.

Advanced

Install options

• --clients claude-code,codex (or none): pick which AI apps to register.

• --warudo "D:\...\Warudo": tell the installer where WARUDO is if Steam lookup fails.

• --skip-runtime: only register AI apps, do not touch WARUDO.

To add options to the one-line install, set an environment variable first:

$env:WARUDO_AGENT_BRIDGE_CLIENTS = "claude-code,codex"; irm https://raw.githubusercontent.com/StudioRaming/warudo-agent-bridge/main/install.ps1 | iex

Manual registration

The installer prints the exact command for your machine. For Claude Code it looks like this:

claude mcp add -s user warudo-agent-bridge -- node "C:\Users\YOU\.warudo-agent-bridge\app\bin\warudo-agent-bridge.mjs" mcp

JSON clients use {"mcpServers": {"warudo-agent-bridge": {"command": "node", "args": ["C:\\Users\\YOU\\.warudo-agent-bridge\\app\\bin\\warudo-agent-bridge.mjs", "mcp"]}}}.

How it works

AI client ──stdio──> MCP server (Node) ──files──> runtime inside WARUDO (Playground C#)
                     %USERPROFILE%\.warudo-agent-bridge\runtime

• No network. Requests and replies are files in your user folder. Nothing listens on a port.

• One writer at a time. Tools that change WARUDO need a short write lease. The MCP server takes it for you; a second agent gets a clear "busy" reply instead of fighting over the scene.

• Honest results. A request is claimed before it runs. If WARUDO closes or reloads the bridge, the reply says NOT_EXECUTED (safe to send again) or UNKNOWN (check state). Reads and absolute-value writes retry once across a reload on their own.

• Undo paths. Opening a scene, restoring a snapshot, and deleting an asset save a recovery snapshot first. Overwriting a saved scene keeps the old file.

Character pose

Pose tools use Unity humanoid terms, so they fit any humanoid avatar or VRM.

• warudo_character_pose_set takes bone aims ({"LeftUpperArm": {"aim": [-1, -0.2, 0]}}, x right, y up, z forward) and/or muscles, applied parent-first down the hierarchy. base: "standing" starts from the avatar's rest pose; hipsHeight sets the hips in meters (adult body standing on knees is about 0.35).

• Joints stay inside the avatar's range. When an aim asks for more, the reply lists it under limited so the agent can ease that aim.

• The reply comes once the character shows the pose (shown), so a capture right after is correct.

• warudo_analysis_capture renders the body without materials or background, colored by body part, from several views at once, and reports hand contacts, how high each body part is above the floor, and where every joint lands in the camera frame. Agents use it to check a pose against a reference image instead of guessing from a shaded screenshot.

• warudo_character_pose_save writes the pose as a Unity humanoid .anim, into WARUDO's own animation list or to any folder (for example a Unity project).

• warudo_character_pose_clear puts the previous idle animation back.

Configuration

%USERPROFILE%\.warudo-agent-bridge\config.json (created from config.example.json):

• componentCall.allow: Unity component methods the agent may call, as {"typePrefix": "My.Namespace.", "methods": ["Refresh"]} entries. Empty by default, so warudo_component_call is off.

• retention: how long replies, captures, snapshots and pose previews are kept before warudo_maintenance_cleanup removes them.

Command line

The same operations are available without an AI client:

npx @studioraming/warudo-agent-bridge status
npx @studioraming/warudo-agent-bridge call scene.get
npx @studioraming/warudo-agent-bridge tools

After install, %USERPROFILE%\.warudo-agent-bridge\bin\warudo-agent.cmd is a shortcut to the same CLI.

Uninstall

npx @studioraming/warudo-agent-bridge uninstall

This removes the runtime from WARUDO's Playground (restart WARUDO to unload it) and the MCP entries from the clients, with backups. Add --purge to also delete %USERPROFILE%\.warudo-agent-bridge except its backups folder.

Development

See CONTRIBUTING.md. Security reports: SECURITY.md.

License

MIT © StudioRaming