---
icon: lucide/mic
---

# Agent CLI

A collection of **local-first**, AI-powered command-line agents that run entirely on your machine.

<img src="https://raw.githubusercontent.com/basnijholt/agent-cli/refs/heads/main/.github/logo.svg" alt="agent-cli logo" style="width: 200px; float: right; margin-left: 20px;" />

## What is Agent CLI?

Agent CLI 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 can run **100% locally**. Your data—whether from your clipboard, microphone, or files—stays on your machine unless you configure a cloud provider. This keeps workflows private and allows the tools to work offline.
>
> You can optionally configure the agents to use OpenAI/Gemini services.

## Quick Demo

<iframe width="560" height="315" src="https://www.youtube.com/embed/7sBTCgttH48" title="Agent-CLI Demo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

<!-- CODE:START -->
<!-- print(include_section("../README.md", "why-i-built-this")) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
## 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.

<!-- OUTPUT:END -->

## Features

| Command | Description |
|---------|-------------|
| [`autocorrect`](commands/autocorrect.md) | Correct grammar and spelling using a local LLM |
| [`transcribe`](commands/transcribe.md) | Transcribe audio from your microphone to clipboard |
| [`transcribe-live`](commands/transcribe-live.md) | Continuous background transcription with VAD |
| [`diarize-live-session`](commands/diarize-live-session.md) | Retroactively label speakers in saved `transcribe-live` sessions |
| [`speakers`](commands/speakers.md) | List, rename, and merge persistent diarization speaker identities |
| [`speak`](commands/speak.md) | Convert text to speech using a local TTS engine |
| [`voice-edit`](commands/voice-edit.md) | Edit clipboard text with voice commands |
| [`assistant`](commands/assistant.md) | Wake word-based voice assistant |
| [`chat`](commands/chat.md) | Conversational AI with tool-calling capabilities |
| [`rag-proxy`](commands/rag-proxy.md) | Chat with your documents via RAG |
| [`memory`](commands/memory.md) | Long-term memory system for conversations |
| [`dev`](commands/dev.md) | Parallel development with git worktrees and AI coding agents |
| [`server`](commands/server/index.md) | Local ASR & TTS servers with dual-protocol (Wyoming & OpenAI), TTL-based memory, and multi-platform acceleration (MLX/CUDA) |

## Quick Start

### Prefer the macOS app?

Install the native menu bar app with Homebrew:

```bash
brew tap basnijholt/agent-cli https://github.com/basnijholt/agent-cli
brew install --cask agent-cli
```

The app provides global shortcuts, a menu bar UI, automatic local Whisper setup, and a private bundled `agent-cli` runtime. See the [macOS app guide](installation/macos-app.md).

### Just want the CLI tool?

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

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

# Using pip
pip install agent-cli
```

Then use it:

```bash
agent-cli autocorrect "this has an eror"
```

### Want automatic setup with everything?

```bash
# 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 automatically installs:

- ✅ 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)

## Requirements

- [uv](https://docs.astral.sh/uv/) (recommended) or Python 3.11+
- A microphone (for voice features)
- Speakers (for text-to-speech features)

## Documentation

- [Getting Started](getting-started.md) - Installation and first steps
- [macOS App](installation/macos-app.md) - Native menu bar app and Homebrew cask
- [Configuration](configuration.md) - All configuration options
- [Commands](commands/index.md) - CLI reference
- [System Integration](system-integration.md) - Hotkeys and system setup
- [Architecture](architecture/index.md) - How it works under the hood

## License

MIT
