Persona Motion Studio

A local desktop home for a VRM character that an MCP-enabled AI assistant can show, animate, and react through — with a visual motion editor built in.

What it does

• imports your own humanoid .vrm character into a private on-device library;
• keeps the character on top of your desktop while you work;
• lets you pose body, hands, and individual fingers with degree controls;
• creates, edits, duplicates, scrubs, previews, and saves animation keyframes;
• exports portable .vrma files and editable .persona-motion.json projects;
• installs named motions into Persona so an AI assistant can discover and play them through local MCP tools; and
• reacts to supported desktop voice output without recording or saving audio.

No character model is included in the repository or installer.

Install on Windows

1. Open the repository's Releases page.
2. Download Persona-Motion-Studio-...-windows-x64-setup.exe.
3. Run the installer and open Persona Motion Studio.
4. Choose a .vrm character when the welcome guide appears.

The installer contains the native audio helper. Your friends do not need Node.js, Git, Visual Studio, or this source repository.

Windows may show a SmartScreen warning for early unsigned builds. Check that the download came from this repository's release page and compare its SHA-256 value with SHA256SUMS.txt before continuing.

Linux AppImage/DEB and macOS DMG/ZIP packages are built by the release workflow. The first beta is primarily tested on Windows.

Five-minute walkthrough

1. Import a character

Press Import your VRM and choose a humanoid .vrm file. Persona copies it into the app's private data folder. It is not added to projects, source control, MCP responses, or network requests.

Only use a model whose creator permits your intended use. Some VRoid Hub models allow personal avatar use but forbid redistribution or modification.

2. Make a pose

Choose a bone in the left panel. Move its X, Y, and Z controls in the right panel. The selected joint is marked on the character, and Show skeleton overlay makes the whole rig easier to understand.

Hands and individual thumb, index, middle, ring, and little-finger joints are available when the imported VRM exposes those standard humanoid bones.

3. Turn poses into movement

Select Frame 1, adjust the pose, and press Save changes to Frame 1. Duplicate the frame, give it a later time, change the pose, and save again. Press Play to preview the interpolation between frames.

The editor autosaves locally. Save project creates an editable project file you can share without sharing the character. Export VRMA creates a portable animation.

4. Install it for your assistant

Give the motion a memorable name, choose a reaction slot, and press Install for GPT. Persona stores the motion in the same private local library and previews it immediately.

5. Connect Codex or another MCP client

Leave Persona running and add its loopback-only MCP endpoint:

codex mcp add persona --url http://127.0.0.1:47831/mcp

Start a new Codex task after adding the connection. Ask it to list saved Persona motions, play one, open Motion Studio, or show/hide the character.

Other desktop AI clients can use the same Streamable HTTP endpoint if they support local MCP servers. A hosted web-only assistant generally cannot reach 127.0.0.1 on your computer.

Privacy and security

• The VRM and custom motion library stay under the operating system's app-data folder.
• Release builds actively remove model.vrm and local custom-motion folders even if a developer accidentally leaves them in the source tree.
• MCP exposes six narrow Persona tools, not filesystem or shell access.
• The local server binds only to 127.0.0.1 and rejects non-loopback host headers.
• Voice activity is calculated from supported application output in memory. Persona does not capture a microphone, transcribe, save, or upload audio.

See Integrations for the exact tool contract.

Build from source

Requirements:

• Node.js 24 or newer;
• npm;
• hardware-accelerated desktop graphics; and
• Visual Studio Build Tools with Desktop development with C++ for Windows packaging.

npm install
npm run check
npm run demo

Create an installer for the current operating system:

npm run dist:windows
# or: npm run dist:linux / npm run dist:mac

Build outputs go to release/. Character media and user-created VRMA files are ignored by Git and excluded from the package.

Project lineage and licence

This project is based on xikhar/persona, whose excellent local desktop character and voice-reactive foundation is MIT-licensed. See Third-party notices.

Application source and code-generated starter motions are covered by MIT. Imported characters retain their creators' licences and are not covered by this repository's licence.