---
icon: lucide/apple
---

# macOS Native Installation

Native macOS setup with full Metal GPU acceleration for optimal performance.

> [!TIP]
> **🍎 Recommended for macOS** — ~10x better performance than Docker via Metal GPU acceleration.

> [!NOTE]
> Prefer a menu bar app with global shortcuts and no terminal session? See the [macOS Menu Bar App](macos-app.md), which can be installed with Homebrew.

## Prerequisites

- macOS 12 Monterey or later
- 8GB+ RAM (16GB+ recommended)
- 10GB free disk space
- Homebrew installed

## Quick Start

1. **Clone and run the setup script:**

   ```bash
   git clone https://github.com/basnijholt/agent-cli.git
   cd agent-cli
   ./scripts/setup-macos.sh
   ```

2. **Start all services:**

   ```bash
   scripts/start-all-services.sh
   ```

3. **Install agent-cli:**

   ```bash
   uv tool install agent-cli
   # or: pip install agent-cli
   ```

4. **Test the setup:**
   ```bash
   agent-cli autocorrect "this has an eror"
   ```

## What the Setup Does

The `setup-macos.sh` script:

- ✅ Checks for Homebrew
- ✅ Installs `uv` if needed
- ✅ Installs/checks Ollama (native macOS app)
- ✅ Installs Zellij for session management
- ✅ Installs Whisper and TTS as launchd daemons via `agent-cli daemon install`

## Services Overview

| Service          | Implementation          | Port  | GPU Support          |
| ---------------- | ----------------------- | ----- | -------------------- |
| **Ollama**       | Native macOS app        | 11434 | ✅ Metal GPU         |
| **Whisper**      | MLX Whisper (via daemon)| 10300 | ✅ Apple Silicon MLX |
| **TTS (Kokoro)** | Kokoro TTS (via daemon) | 10200 | ✅ Metal GPU (MPS)   |
| **OpenWakeWord** | Wyoming OpenWakeWord    | 10400 | N/A                  |

> [!NOTE]
> Whisper and TTS run as launchd daemons via `agent-cli daemon install`, using MLX and Metal for GPU acceleration on Apple Silicon.

## Session Management with Zellij

The setup uses Zellij for managing all services in one session:

### Starting Services

```bash
scripts/start-all-services.sh
```

### Zellij Commands

- `Ctrl-O d` - Detach (services keep running)
- `zellij attach agent-cli` - Reattach to session
- `zellij list-sessions` - List all sessions
- `zellij kill-session agent-cli` - Stop all services
- `Alt + arrow keys` - Navigate between panes
- `Ctrl-Q` - Quit (stops all services)

## Manual Service Management

If you prefer running services individually:

```bash
# Ollama (brew service recommended)
brew services start ollama
# Or run in foreground:
ollama serve

# Whisper and TTS are installed as launchd daemons
agent-cli daemon status              # Check all daemon status
agent-cli daemon install whisper     # Install whisper daemon
agent-cli daemon install tts-kokoro  # Install TTS daemon

# Or run in foreground (without daemon):
agent-cli server whisper
agent-cli server tts --backend kokoro

# OpenWakeWord
scripts/run-openwakeword.sh
```

Intel Macs: prefer Docker or a Linux-style Wyoming Faster Whisper setup; MLX Whisper is Apple Silicon only.

## Why Native Setup?

- **10x faster than Docker** - Full Metal GPU acceleration
- **Better resource usage** - Native integration with macOS
- **Automatic model management** - Services handle downloads

## Troubleshooting

### Terminal-notifier Popup Issues

- Ensure Settings > Notifications > terminal-notifier > Allow Notifications is enabled.
- For a persistent “Listening…” badge, set the Alert style to **Persistent** (or choose **Alerts** on macOS versions that still offer Alert/Banner). This keeps the recording indicator visible while other notifications still auto-dismiss automatically.

### Ollama Issues

```bash
# Check if Ollama is running
ollama list

# Pull a model manually
ollama pull gemma3:4b

# Check Ollama logs
tail -f ~/.ollama/logs/server.log
```

### Service Port Conflicts

```bash
# Check what's using a port
lsof -i :11434
lsof -i :10300
lsof -i :10200
lsof -i :10400
```

### uv/Python Issues

```bash
# Reinstall uv
brew reinstall uv

# Check uv installation
uv --version
```

### Zellij Issues

```bash
# Kill stuck sessions
zellij kill-all-sessions

# Check session status
zellij list-sessions

# Start without Zellij (manual)
# Run each script in separate terminals
```

### Memory/Performance Issues

- Close other apps to free RAM
- Check Activity Monitor for high CPU/Memory usage
- Services will automatically download required models

## Alternative: Docker

If you prefer Docker despite performance limitations:

- [Docker Setup Guide](docker.md)
- Note: ~10x slower due to no GPU acceleration
