agent-cli

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]" -p 3.13.

Quick Start

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 -p 3.13

# Using pip
pip install agent-cli

[!NOTE] The -p 3.13 flag is required because some dependencies (like onnxruntime) don't support Python 3.14 yet. See uv issue #8206 for details.

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 -p 3.13. On Windows and macOS, this is handled automatically.