# 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.

![Persona Motion Studio first-run walkthrough](docs/images/motion-studio-welcome.png)

## 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](https://github.com/Seravielle-de-Lochan/persona-motion-studio/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:

```powershell
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](docs/INTEGRATIONS.md) 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.

```powershell
npm install
npm run check
npm run demo
```

Create an installer for the current operating system:

```powershell
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](https://github.com/xikhar/persona),
whose excellent local desktop character and voice-reactive foundation is
MIT-licensed. See [Third-party notices](THIRD_PARTY_NOTICES.md).

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