Persona: a desktop VRM character that reacts to your assistant's voice output

The gap Persona fills between a voice assistant and the screen

Most local voice stacks are audible and invisible. You speak, a model answers, and nothing on the desktop indicates that a process is listening or speaking. Persona adds a character window that gives that conversation a visual identity. The scope is narrow on purpose: it captures the audio your assistant already plays out, animates a VRM model against that signal, and exposes a small set of controls over MCP. The README is explicit about the negative space. Persona does not capture the microphone, does not save audio, does not produce speech, does not transcribe content, and does not send audio over the network. That list is the best description of who this is for. If your assistant already runs somewhere else and you want a face on it, Persona is the missing piece. If you want Persona to be the assistant, it is the wrong download.

How the voice listener and the avatar window fit together

The architecture splits into a listener, a renderer, and an MCP surface. The listener is platform-specific and scoped to one playback process, either detected automatically or chosen by the user. On Linux it captures a PipeWire playback stream and needs pw-dump and pw-record on PATH. On Windows it uses WASAPI process-loopback and requires Windows 10 build 20348 or newer. On macOS 14.2 and later it uses a Core Audio process tap and asks once for System Audio Recording permission. The renderer is an Electron window holding the VRM model plus idle and speaking motion, and it ships with a default character you can replace or extend with .vrm and .vrma files from Settings. The third surface is a local MCP server at http://127.0.0.1:47831/mcp, which lets a connected agent play an installed animation, show or hide the window, and report whether the character and voice listener are active. The data flow is one-directional: playback audio in, animation state out, agent commands in through MCP. No audio leaves the machine and none is stored.

Install Persona and run the demo build

The README lists the requirements as Node.js 24 or newer, npm, and a desktop session with hardware-accelerated graphics. The package.json engines field agrees, declaring "node": ">=24". The fastest path is the demo script, which builds the renderer and launches the app with normal automatic voice-output detection.

npm install
npm run demo

For a background launch, the README gives a second form that skips the renderer build and starts Electron directly with a flag.

npm start -- --background

Before any of this produces a visible character, you need a model. The README states that until a default model exists, Persona does not create the avatar window or start its voice-output listener, and that the first imported model becomes the default automatically. Packaged VRM files belong under public/assets/models/ and packaged VRMA files under public/assets/animations/. To exercise the packaged-library path with the repository's ignored test media, the README says to copy the two example catalogs over the active published ones.

cp public/assets/library.json.example public/assets/library.json
cp public/assets/manifest.json.example public/assets/manifest.json

Both examples are usable and also document the catalog format. The README warns that their media is test-only: the example manifest keeps distribution disabled and its license fields incomplete.

Connecting Codex and other MCP clients

Once Persona is running, the README shows a single command to register its local MCP server with Codex.

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

New Codex sessions can then ask Persona to play an installed animation, show or hide its window, and report whether the local character and voice listener are active. The README is careful about what this connection is: Persona remains a separate desktop application and the MCP connection only exposes its own visual controls. The README also notes that any compatible MCP client can use the same animation tools, and points to docs/INTEGRATIONS.md for the voice side. That file is where the local voice app setup lives, so a reader wiring up a non-Codex agent should start there rather than assuming the Codex command is the only integration path. Custom actions carry a name, description, and trigger scenario, and Persona adds that metadata to its MCP animation tool so a connected agent can judge when an action fits.

Click-through behaves differently on Linux, and that is the main limitation

Click-through is the feature most likely to surprise a new user. The README describes two behaviours. On Windows and macOS only the transparent area passes clicks through and the character itself stays clickable, because Electron can keep delivering mouse moves to a window that ignores clicks there. On Linux there is no such forwarding, so the whole window passes clicks through at once and the character stops responding until the toggle comes back off. The README calls this experimental on Linux, notes that it relies on the X11 input shape, and states that no Wayland compositor has been verified. The tray menu labels it Click-through (whole window) to make the difference visible, and the tray toggle is the documented way back to an interactive window. Follow the cursor has the same Linux caveat: the pointer is seen only inside the avatar window, and with click-through on the window receives no mouse moves at all, so nothing is noticed there. The setting starts on, and the proximity threshold is measured against the character's own size rather than the window, so it survives a resize.

Where Persona stops and a full voice stack begins

Persona does not run language models, and the README says so directly. To use it with a local model stack you open Settings, go to Voice, and select the running app or Linux playback stream that produces assistant audio. Advanced users can supply a cross-platform process pattern, and pipelines that already calculate output levels can use the external-events mode. The practical alternative is not a competing avatar app but the voice stack itself. A project like a local speech pipeline that pairs a model server with a text-to-speech engine already owns the audio path; Persona attaches to that path from the outside and adds animation. The difference in approach matters when you are choosing. A stack that generates speech controls its own output and can drive lip sync from internal timing. Persona cannot, because it only sees a playback stream after the fact. It compensates with action slots and MCP control, but the animation is reactive rather than authored. If you need frame-accurate lip sync tied to phonemes, an integrated pipeline is the better fit.

Maintenance, packaging, and what the MIT licence covers

The repository is not archived and the last push was on 2026-09-02, so the codebase is recent. The version in package.json is 0.1.0-beta.0 and no releases were retrieved, which means you should expect to build from source rather than install a tagged artifact. The README does describe distribution formats per platform: AppImage and DEB on Linux, an NSIS installer on Windows, and DMG and ZIP for macOS on arm64 and x64. The licence is MIT, which permits commercial and private use with the copyright notice retained. That covers the code. It does not cover the bundled character media: the README states that the example manifest deliberately keeps distribution disabled and its license fields incomplete, so anyone repackaging Persona for others has to sort out model and animation rights separately. Packaged media is immutable, and editing or removing a packaged action creates a user-level override without changing the installed application. Reset packaged actions restores shipped metadata and visibility while leaving user-created actions and uploaded clips untouched. Upgrade cost is mostly the toolchain: Node.js 24 or newer, and the native capture paths that differ per platform.

Editorial conclusion

Adopt Persona if you already run a local voice assistant on Linux, Windows 10 build 20348 or newer, or macOS 14.2+, and you want an on-screen character driven by that assistant's output without touching a microphone. Skip it if you need a language model, speech synthesis, or transcription, because the README states Persona does none of those, and skip Linux with click-through enabled if you expect the character to stay interactive. Before installing, verify that pw-dump and pw-record are on PATH on Linux, that your Windows build meets the loopback requirement, and that you have a .vrm model ready, since Persona does not create the avatar window or start its voice-output listener until a default model exists.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. xikhar/persona on GitHub