macOS Native Installation

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

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:

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

2. Start all services:

   scripts/start-all-services.sh
   

3. Install agent-cli:

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

4. Test the setup:

   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

Session Management with Zellij

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

Starting Services

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:

# 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

# 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

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

uv/Python Issues

# Reinstall uv
brew reinstall uv

# Check uv installation
uv --version

Zellij Issues

# 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
• Note: ~10x slower due to no GPU acceleration