Meuxe

[!WARNING] Early development. Meuxe is actively changing. Expect rough edges, breaking config/API changes, and incomplete features. Feedback and issues are welcome - production use is at your own risk.

What is Meuxe

Meuxe is a character on your screen who remembers past conversations, speaks with a voice, and reacts with expressions. Everything about the relationship (memory, persona, mood) is stored locally on your machine. Chat is powered by a coding agent you already have installed (Claude Code, Codex, OpenCode, or any ACP agent). Optional cloud voices only if you turn them on.

Highlights

• Remembers you. Your companion writes down what matters as you talk: facts about you, moments you shared, and how they feel about you. Moods have a cause and stick around until you actually address them. They notice when you have been gone.
• Your agent, your choice. Chat runs through the CLI agent you install and select; Meuxe is the Agent Client Protocol client, not a locked-in model API.
• Expressive avatars. Live2D and VRM characters with lip sync, expression tags parsed from agent replies, and framing controls on stage.
• Voice in and out. Your companion speaks aloud with live captions, and listens through your microphone with optional on-device Whisper transcription.
• Mini mode. A transparent desktop widget with hover-to-reveal chat, size presets, and expand to the full app.
• Keyboard shortcuts. Toggle mini mode, focus chat, and control the mic without reaching for the mouse.
• Local-first privacy. Memories, persona, sessions, and relationship state stay on your machine.
• Characters as files. Layered companion profiles as editable .yaml and .md files (soul.md, style.md, rules.md, and more).

Screenshots

Install

Pre-built binaries are on GitHub Releases. This first release is a prerelease for macOS 11+ (Apple Silicon) and Linux (.deb for Ubuntu 22.04+ and AppImage). Intel Macs and Windows are not built yet.

macOS (Apple Silicon)

Builds are not signed or notarized, so Gatekeeper treats the download as quarantined. macOS may say the developer cannot be verified, or that the app is damaged.

1. Download the .dmg from Releases.
2. Open it and drag Meuxe into Applications.
3. Clear the quarantine flag (required once):

xattr -c /Applications/Meuxe.app

4. Open Meuxe from Applications or Spotlight.

If you skip step 3, right-click the app → Open sometimes works, but the xattr command is the reliable fix.

Linux

Debian / Ubuntu (.deb) — also pulls WebKitGTK 4.1 and AppIndicator:

sudo apt install ./Meuxe_*.deb

AppImage (some distros need FUSE):

chmod +x Meuxe_*.AppImage
./Meuxe_*.AppImage

After install

First launch walks you through you, your companion, voice, and an assistant. Chat will not start without an ACP agent (see Pick an agent).

The first time you use the microphone, Meuxe downloads a ~75 MB speech model into app data (models/whisper/ggml-tiny.bin). After that, transcription stays on this computer.

To hack on Meuxe instead of installing a release, see Build from source.

Pick an agent

First launch walks you through choosing an agent, and you can change it later in Settings → Agent. Meuxe does not ship its own model: every message goes to the agent you pick, over ACP.

Preset	Typical install
OpenCode	opencode CLI (npm i -g opencode-ai), launched as opencode acp
Claude Code	npm i -g @agentclientprotocol/claude-agent-acp (binary claude-agent-acp)
Codex	npm i -g @agentclientprotocol/codex-acp (binary codex-acp)
Custom	Any ACP agent: set command and args (or a full path) in Settings

How it works

Meuxe is an Agent Client Protocol client. Before each turn it writes persona, memory, and relationship context into companion-home/ in the app data directory and uses that tree as the agent's working directory. See docs/companion-home.md and docs/acp-agents.md for details.

For voice, Meuxe TTS is the default (free, no API key). You can switch to this computer’s system speech, or add ElevenLabs and OpenAI in Settings → Voice. Microphone input uses on-device Whisper after a one-time model download.

Development

Build from source

• Node.js 22 (see .nvmrc)
• Rust 1.88.0 with Cargo (pinned in rust-toolchain.toml; see Tauri prerequisites for OS-specific packages)
• Linux: WebKitGTK and related dev packages (the same set used in CI is a good reference)
• An ACP agent for chat (see Pick an agent)
• Network access during npm run build / npm run tauri dev to fetch Live2D Cubism Core (not committed; see scripts/fetch-cubism-core.mjs)

git clone https://github.com/meet447/Meuxe.git
cd Meuxe
npm ci
npm run tauri dev

npm run tauri build  # production desktop bundle
npm run dev          # Vite frontend only (without Tauri shell)
npm test             # Vitest unit tests
npm run build        # typecheck + production frontend build
npm run icons        # regenerate app icons from src-tauri/icons/source/icon.svg

Rust (Linux)

whisper-rs-sys needs CMake and g++. On Linux, link against GCC's libstdc++:

export CC=gcc CXX=g++
gcc_dir=$(dirname "$(gcc -print-file-name=libstdc++.so)")
export RUSTFLAGS="-C link-arg=-L${gcc_dir}"
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Project structure

Meuxe/
├── src/                 # React (Vite) frontend
├── src-tauri/           # Tauri shell, ACP client, Rust commands
├── crates/meuxe-core/   # Shared Rust logic (persona, memory, sessions, TTS)
├── characters/          # Local companion profiles
├── models/              # Live2D and VRM assets
├── data/                # Local session and memory data (created at runtime)
├── scripts/             # Build and asset helpers
└── docs/                # Product docs and architecture notes

See CONTRIBUTING.md for how we handle issues, pull requests, and code review.

Migrating from MeuxCompanion

The desktop app identifier is now com.meuxe.app (product name Meuxe). Local data no longer lives under com.meuxcompanion.app.

Quit both apps, then copy the old app data directory into the new path (replace, do not merge piecemeal):

OS	Old → new
macOS	~/Library/Application Support/com.meuxcompanion.app → ~/Library/Application Support/com.meuxe.app
Linux	~/.local/share/com.meuxcompanion.app → ~/.local/share/com.meuxe.app

Copy config.json, data/, characters/, models/, and companion-home/ if they exist.

Releases

Tagged releases are built with GitHub Actions. Maintainers publish draft GitHub Releases from CI artifacts when ready.

Contributing

We welcome issues and pull requests. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before participating.

Security

If you discover a security vulnerability in this repository, please follow SECURITY.md so we can address it responsibly.

License

This project is licensed under the MIT License.