Installation

Prerequisites

• Node.js 18+ — Mia uses ESM modules and modern Node APIs.
• Git — Required for workspace context and workflow commands.
• At least one AI provider CLI or API key:
  • Claude Code (claude binary)
  • OpenAI Codex (codex binary)
  • Google Gemini (API key)
  • OpenCode (opencode binary)

Install from Source

git clone https://github.com/m1ab0t/mia.git
cd mia
npm install
npm run build
npm link     # Makes `mia` available globally

First-Time Setup

Run the interactive setup wizard:

mia setup

This will:

1. Detect installed plugins — Checks which AI provider CLIs are available on your $PATH.
2. Select active plugin — Choose your primary AI backend (e.g., Claude Code).
3. Authenticate — Runs provider-specific auth (browser login, API key paste, or OAuth).
4. Select model — Choose the default model for your provider.
5. Verify — Sends a test prompt to confirm everything works.
6. Start daemon — Launches Mia in the background.
7. Show QR code — For optional mobile pairing.

Verify Installation

mia status       # Check daemon is running
mia doctor       # Run health diagnostics
mia ask "hello"  # Test a simple prompt

Directory Structure

Mia stores all configuration and data in ~/.mia/:

~/.mia/
├── mia.json              # Configuration file
├── .env                  # API keys and secrets
├── .mia.pid              # Daemon PID file
├── memory.db             # SQLite memory store
├── sessions.json         # Active sessions
├── scheduled-tasks.json  # Cron task definitions
├── context/              # Cached workspace context
├── traces/               # Dispatch trace logs
└── logs/                 # Daemon logs

Updating

Pull the latest code and rebuild:

cd ~/mia
git pull
npm install
npm run build
mia restart

Or use the built-in update command from the CLI or mobile app:

mia update