agent-cli-dev

Agent CLI

agent-cli is a collection of local-first, AI-powered command-line agents that run entirely on your machine. It provides a suite of powerful tools for voice and text interaction, designed for privacy, offline capability, and seamless integration with system-wide hotkeys and workflows.

[!TIP] Short aliases available: You can use agent or ag instead of agent-cli for convenience.

[!IMPORTANT] Local and Private by Design All agents in this tool are designed to run 100% locally. Your data, whether it's from your clipboard, microphone, or files, is never sent to any cloud API. This ensures your privacy and allows the tools to work completely offline. You can also optionally configure the agents to use OpenAI/Gemini services.

Why I built this

I got tired of typing long prompts to LLMs. Speaking is faster, so I built this tool to transcribe my voice directly to the clipboard with a hotkey.

What it does:

• Voice transcription to clipboard with system-wide hotkeys (Cmd+Shift+R on macOS)
• Autocorrect any text from your clipboard
• Edit clipboard content with voice commands ("make this more formal")
• Runs locally - no internet required, your audio stays on your machine
• Works with any app that can copy/paste

I use it mostly for the transcribe command when working with LLMs. Being able to speak naturally means I can provide more context without the typing fatigue.

Since then I have expanded the tool with many more features, all focused on local-first AI agents that integrate seamlessly with your system.

See agent-cli in action: Watch the demo

Features

• autocorrect: Correct grammar and spelling in your text using a local LLM.
• transcribe: Transcribe audio from your microphone to clipboard.
• speak: Convert text to speech using a local TTS engine.
• voice-edit: Edit clipboard text with voice commands.
• assistant: Wake word-based voice assistant.
• chat: Conversational AI with tool-calling capabilities.
• memory: Long-term memory system with memory proxy and memory add.
• rag-proxy: RAG proxy server for chatting with your documents.
• dev: Parallel development with git worktrees and AI coding agents.
• server: Local ASR and TTS servers with dual-protocol (Wyoming & OpenAI-compatible APIs), TTL-based memory management, and multi-platform acceleration. Whisper uses MLX on Apple Silicon or Faster Whisper on Linux/CUDA. TTS supports Kokoro (GPU) or Piper (CPU).
• transcribe-live: Continuous background transcription with VAD. Install with uv tool install "agent-cli[vad]".

Quick Start

Prefer the macOS menu bar app?

Install the native AgentCLI app with Homebrew:

brew install --cask basnijholt/tap/agent-cli

The app provides global shortcuts, a menu bar UI, automatic local Whisper setup on first transcription, and a private bundled agent-cli runtime. See the macOS app guide for setup, updates, and uninstall instructions.

Just want the CLI tool?

If you already have AI services running (or plan to use OpenAI), simply install:

# Using uv (recommended)
uv tool install agent-cli

# Using pip
pip install agent-cli

Then use it:

agent-cli autocorrect "this has an eror"

Want automatic setup with everything?

We offer two ways to set up agent-cli with all services:

Option A: Using Shell Scripts (Traditional)

# 1. Clone the repository
git clone https://github.com/basnijholt/agent-cli.git
cd agent-cli

# 2. Run setup (installs all services + agent-cli)
./scripts/setup-macos.sh  # or setup-linux.sh

# 3. Start services
./scripts/start-all-services.sh

# 4. (Optional) Set up system-wide hotkeys
./scripts/setup-macos-hotkeys.sh  # or setup-linux-hotkeys.sh

# 5. Use it!
agent-cli autocorrect "this has an eror"

Option B: Using CLI Commands (New!)

[!NOTE] agent-cli uses sounddevice for real-time microphone/voice features. On Linux only, you need to install the system-level PortAudio library (sudo apt install portaudio19-dev / your distro's equivalent on Linux) before you run uv tool install agent-cli. On Windows and macOS, this is handled automatically.

# 1. Install agent-cli
uv tool install agent-cli

# 2. Install all required services
agent-cli install-services

# 3. Start all services
agent-cli start-services

# 4. (Optional) Set up system-wide hotkeys
agent-cli install-hotkeys

# 5. Use it!
agent-cli autocorrect "this has an eror"

install-hotkeys also installs the required audio and llm extras if they are missing.

The setup scripts automatically install:

• ✅ Package managers (Homebrew/uv) if needed
• ✅ All AI services (Ollama, Whisper, TTS, etc.)
• ✅ The agent-cli tool
• ✅ System dependencies
• ✅ Hotkey managers (if using hotkey scripts)

• Installation
  • Option 1: CLI Tool Only
  • Option 2: Automated Full Setup
    • Step 1: Clone the Repository
    • Step 2: Run the Setup Script
    • Step 3: Start All Services
    • Step 4: Test Your Installation
• macOS Menu Bar App
• System Integration
  • macOS Hotkeys
  • Linux Hotkeys
  • Claude Code Plugin
• Prerequisites
  • What You Need to Install Manually
  • What the Setup Scripts Install for You
    • Core Requirements (Auto-installed)
    • AI Services (Auto-installed and configured)
    • Alternative Cloud Services (Optional)
    • Alternative Local LLM Servers
• Usage
  • Installation Commands
    • Installing Optional Extras
  • Configuration
    • Environment variable overrides
    • Managing Configuration
    • Provider Defaults
  • autocorrect
  • transcribe
  • transcribe-live
  • speak
  • voice-edit
  • assistant
  • chat
  • rag-proxy
  • memory
    • memory proxy
    • memory add
• Development
  • Running Tests
  • Pre-commit Hooks
• Contributing
• License

Installation

Option 1: CLI Tool Only

If you already have AI services set up or plan to use cloud services (OpenAI/Gemini):

# Using uv (recommended)
uv tool install agent-cli

# Using pip
pip install agent-cli

Option 2: Automated Full Setup

For a complete local setup with all AI services:

Step 1: Clone the Repository

git clone https://github.com/basnijholt/agent-cli.git
cd agent-cli

Step 2: Run the Setup Script

Platform	Setup Command	What It Does	Detailed Guide
🍎 macOS	./scripts/setup-macos.sh	Installs Homebrew (if needed), uv, Ollama, all services, and agent-cli	macOS Guide
🐧 Linux	./scripts/setup-linux.sh	Installs uv, Ollama, all services, and agent-cli	Linux Guide
❄️ NixOS	See guide →	Special instructions for NixOS	NixOS Guide
🐳 Docker	See guide →	Container-based setup (slower)	Docker Guide

Step 3: Start All Services

./scripts/start-all-services.sh

This launches all AI services in a single terminal session using Zellij.

Step 4: Test Your Installation

agent-cli autocorrect "this has an eror"
# Output: this has an error

[!NOTE] The setup scripts handle everything automatically. For platform-specific details or troubleshooting, see the installation guides.

For contributing or development:

git clone https://github.com/basnijholt/agent-cli.git
cd agent-cli
uv sync
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

macOS Menu Bar App

AgentCLI is also available as a native macOS menu bar app for voice workflows that should work from any app without keeping a terminal open.

Install it with Homebrew:

brew install --cask basnijholt/tap/agent-cli

The app is a SwiftUI wrapper around the same agent-cli commands. It bundles uv, installs a private agent-cli[audio,llm] runtime in your Application Support folder on first use, and starts the local Whisper daemon automatically the first time you transcribe.

Default shortcuts:

• Fn+Space - Toggle transcription
• Fn - Record while held and insert the transcript
• Cmd+Shift+A - Autocorrect clipboard text
• Cmd+Shift+V - Start voice edit

You can change shortcuts, enable Start at Login, or switch to a user-installed agent-cli runtime from the app's Settings... screen. See the macOS app guide for details.

System Integration

Want system-wide hotkeys? You'll need the repository for the setup scripts:

# If you haven't already cloned it
git clone https://github.com/basnijholt/agent-cli.git
cd agent-cli

macOS Hotkeys

./scripts/setup-macos-hotkeys.sh

This script automatically:

• ✅ Installs Homebrew if not present
• ✅ Installs skhd (hotkey daemon) and terminal-notifier
• ✅ Configures these system-wide hotkeys:
  • Cmd+Shift+R - Toggle voice transcription
  • Cmd+Shift+A - Autocorrect clipboard text
  • Cmd+Shift+V - Voice edit clipboard text

[!NOTE] After setup, you may need to grant Accessibility permissions to skhd in System Settings → Privacy & Security → Accessibility

[!TIP] To keep the recording-status notification visible for the whole flow, open System Settings → Notifications → terminal-notifier and set the Alert style to Persistent (or choose Alerts on older macOS versions). Also enable "Allow notification when mirroring or sharing the display". The hotkey scripts keep only the recording notification pinned; status and result toasts auto-dismiss.

Linux Hotkeys