Three commands, and the installer does the rest

1 Clone and install

Linux and macOS:

git clone https://github.com/fswolf/luna-local-agent.git ~/ai-voice
cd ~/ai-voice
./installer/install.sh

Windows, in PowerShell:

git clone https://github.com/fswolf/luna-local-agent.git $HOME\ai-voice
cd $HOME\ai-voice
powershell -ExecutionPolicy Bypass -File installer\install.ps1

The folder is ~/ai-voice, and every path in the docs assumes it. What the installer does, in order:

1. Checks. Python 3.10 to 3.13 (it offers to install 3.12 if there's none), your GPU, disk space.
2. System packages through your own package manager (dnf, apt, pacman, zypper, brew or winget): PortAudio for audio, espeak-ng for the voice, git. It shows the exact command first.
3. Luna's Python environment. PyTorch comes as the small CPU build, since only voice detection uses it here.
4. Her voice. It clones kokoro-reader next to this folder, in its own environment, with PyTorch for your GPU (NVIDIA, AMD with ROCm, Apple) or the CPU.
5. Her brain. LM Studio (it tells you what to click), or llama.cpp built here for the research features.
6. Extras, pick any: wake word, MCP, portrait tools, Live2D runtime, embedding model, chat plugins.
7. Launchers. A luna command and an app-launcher entry on Linux, Luna.command on macOS, luna.cmd and a Start menu shortcut on Windows.
8. A health check, then a summary of what's ready and what isn't.

2 Start her

luna            # or ./start.sh, or luna.cmd on Windows

The launcher starts her voice server too if the installer set one up, and llama.cpp if it's built and no model server is answering, and stops both again when she exits. It checks the model server and the voice on the way past and says if either is down rather than refusing to start: she runs as a text chat without speech, and a launcher that won't launch is worse than one that tells you why it'll be quiet.

3 Her brain: LM Studio or llama.cpp

LM Studio is the easy path: install it, download a model with a tool template (Qwen, Llama 3.1+, Mistral, Hermes), start its Local Server, and check it answers on http://localhost:1234. That's it.

llama.cpp serves the same GGUF file and opens up what LM Studio keeps inside: token probabilities (which is where her confidence colouring, calibration and adaptive thinking come from), control vectors for the introspection experiments, and the embedding and reranker servers for recall by meaning. Luna works with either and picks by herself at startup, llama-server first if both are up.

llama/install.sh          # Vulkan on Linux ("rocm" for ROCm/HIP), Metal on a Mac
./start.sh                # starts llama.cpp too, then Luna

With MODEL left empty it finds the GGUF in LM Studio's own model folders, so there's no second 10 GB copy. On a Mac it builds for Metal and reads a lighter settings file. The model can also live on another machine: point the URLs in config.json at it.

4 Her voice

Speech is synthesized by kokoro-reader rather than inside Luna, so one loaded model serves every app that asks and she starts in seconds. The installer sets it up; by hand it's:

git clone https://github.com/fswolf/kokoro-reader.git ~/kokoro-reader
source ~/ai-voice-venv/bin/activate
KOKORO_VOICE=af_bella python3 ~/kokoro-reader/server/kokoro_server.py

If the server isn't answering she says so and keeps working as a text chat. Any speech server that answers /tts, /health and /voices can stand in for it.

5 Check, update, undo

./start.sh --check        # what's missing and how to fix it, in plain words
./update.sh               # the latest version, keeping your config.json and your changes
python installer/uninstall.py    # removes what the installer added, never your memory or settings

Luna's check:
  ✓ Python packages
  ✗ no model server answering (llama.cpp :8080 or LM Studio :1234)
      → open LM Studio's Local Server, or build llama.cpp: bash llama/install.sh
  ✓ her voice server is installed - ./start.sh starts it

config.json is yours and isn't in git: the first start makes it from config.example.json, and updates never touch your copy. Every setting can be changed from inside the terminal with /set, saved immediately, most without a restart.

6 Then switch on what you want

7 Platforms, honestly

Linux is where Luna lives and is tested. On macOS and Windows she installs and runs as a voice and text companion, and the macOS side has its own tester. The Linux-only parts (the global hotkey through evdev, Hyprland window tools, grim screenshots) say "not available" instead of working. Reports are welcome.