### Quick Start Agent CLI Command

Source: https://github.com/basnijholt/agent-cli/blob/main/reddit.md

A basic example of how to install and run the agent-cli for autocorrection.

```bash
pip install agent-cli
agent-cli autocorrect "test sentance"
```

--------------------------------

### Full Local Setup using CLI Commands

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/getting-started.md

Install Agent CLI, required services, start services, and optionally set up system-wide hotkeys using CLI commands.

```bash
# 1. Install agent-cli
uv tool install agent-cli -p 3.13

# 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
```

--------------------------------

### Install and run agent-cli with full service setup

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/index.md

This sequence installs agent-cli, all required AI services (Ollama, Whisper, TTS, etc.), starts the services, and optionally sets up system-wide hotkeys for seamless integration.

```bash
# 1. Install agent-cli
uv tool install agent-cli -p 3.13

# 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"
```

--------------------------------

### Basic Daemon Operations Examples

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/daemon.md

Illustrative examples for common daemon management tasks: installing a daemon, checking status, and uninstalling.

```bash
# Install whisper as a background daemon
agent-cli daemon install whisper

# Check status of all daemons
agent-cli daemon status

# Uninstall a daemon
agent-cli daemon uninstall whisper
```

--------------------------------

### Run Linux setup script

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

Executes the setup script for Linux. This script installs uv, Ollama, all AI services, and agent-cli.

```bash
./scripts/setup-linux.sh
```

--------------------------------

### Full Local Setup using Shell Scripts

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/getting-started.md

Clone the repository and use setup scripts for macOS or Linux to install Agent CLI and its services.

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

# 2. Run setup
./scripts/setup-macos.sh  # or setup-linux.sh

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

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

--------------------------------

### Start All Services

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/macos.md

Start all necessary services for agent-cli using the provided script. This command assumes the setup script has been successfully executed.

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

--------------------------------

### Clone and Run Setup Script

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/macos.md

Clone the agent-cli repository and execute the macOS setup script. Ensure Homebrew is installed beforehand.

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

--------------------------------

### Run agent-cli Setup Script

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/linux.md

Execute the setup script for agent-cli on Linux. This is the recommended first step for script-based installation.

```bash
scripts/setup-linux.sh
```

--------------------------------

### Run macOS setup script

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

Executes the setup script for macOS. This script installs Homebrew, uv, Ollama, all AI services, and agent-cli.

```bash
./scripts/setup-macos.sh
```

--------------------------------

### Clone Repository and Setup Agent CLI (Shell Scripts)

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

Steps to set up agent-cli using shell scripts, including cloning the repository, running the setup script, starting services, and optionally setting up hotkeys.

```bash
# 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"
```

--------------------------------

### Manual Installation Dependencies

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/linux.md

Install dependencies for manual setup of agent-cli, including uv and Ollama.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
curl -fsSL https://ollama.ai/install.sh | sh
```

--------------------------------

### Start Open WebUI with Memory Proxy

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/architecture/memory.md

This setup involves pulling necessary models, starting Open WebUI, and then launching the memory proxy. Ensure to configure the base URL correctly for the LLM to interact with the proxy. The memory path is specified for local storage.

```bash
# 1. Pull the required models (one-time setup)
ollama pull embeddinggemma:300m  # for memory embeddings
ollama pull qwen3:4b             # for chat

# 2. Start Open WebUI (runs in background)
#    On Linux, add: --add-host=host.docker.internal:host-gateway
docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e WEBUI_AUTH=false \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8100/v1 \
  -e OPENAI_API_KEY=dummy \
  ghcr.io/open-webui/open-webui:main

# 3. Start the memory proxy (runs in foreground so you can watch the logs)
uvx -p 3.13 --from "agent-cli[memory]" agent-cli memory proxy \
  --memory-path ./my-memories \
  --openai-base-url http://localhost:11434/v1 \
  --embedding-model embeddinggemma:300m

# 4. Open http://localhost:3000, select "qwen3:4b" as model, and start chatting — it remembers you
```

--------------------------------

### Pixi Project Setup

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to install project dependencies using Pixi when pixi.toml or pixi.lock is detected.

```bash
pixi install
```

--------------------------------

### Node.js Project Setup (npm)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to install Node.js dependencies using npm when package-lock.json is detected.

```bash
npm install
```

--------------------------------

### Install all available extras

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/install-extras.md

To install all optional dependencies at once, use the `--all` or `-a` flag.

```bash
agent-cli install-extras --all
```

--------------------------------

### Install Agent CLI Hotkeys (macOS)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/system-integration.md

Automatically installs audio and llm extras, then sets up platform-specific dependencies and creates a default configuration with common hotkeys. Recommended for macOS setup.

```bash
agent-cli install-hotkeys
```

--------------------------------

### Start Services with GPU Acceleration

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/docker.md

Use this command to start all services with NVIDIA GPU acceleration enabled. Ensure you have the NVIDIA Container Toolkit installed.

```bash
docker compose -f docker/docker-compose.yml --profile cuda up
```

--------------------------------

### Python Project Setup (unidep monorepo)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to install Python dependencies for all subdirectories in a monorepo using unidep.

```bash
unidep install-all -e -n <env>
```

--------------------------------

### Start llama-server

Source: https://github.com/basnijholt/agent-cli/blob/main/LLAMA_SERVER_USAGE.md

Launch llama-server with a specified GGUF model, context size, and network configuration. Ensure the model path and parameters are correct for your setup.

```bash
llama-server \
  -m /path/to/your/model.gguf \
  -c 2048 \
  --host 0.0.0.0 \
  --port 8080
```

--------------------------------

### Node.js Project Setup (yarn)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to install Node.js dependencies using yarn when yarn.lock is detected.

```bash
yarn install
```

--------------------------------

### Python Project Setup (poetry)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to install Python dependencies using poetry when pyproject.toml and poetry.lock are detected.

```bash
poetry install
```

--------------------------------

### Ruby Project Setup

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to install Ruby gem dependencies when Gemfile or Gemfile.lock is detected.

```bash
bundle install
```

--------------------------------

### Workflow Example: Initial Email Draft

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/voice-edit.md

The starting point of a workflow example, showing an informal email draft that will be transformed using the agent-CLI.

```plaintext
hey can u help me with the project tmrw?
```

--------------------------------

### Setup macOS Hotkeys Script

Source: https://github.com/basnijholt/agent-cli/blob/main/scripts/macos-hotkeys/README.md

Run this bash script to install and configure the necessary components for macOS hotkeys.

```bash
./setup-macos-hotkeys.sh
```

--------------------------------

### Python Project Setup (pip)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to install Python dependencies using pip when requirements.txt is detected.

```bash
pip install -r requirements.txt
```

--------------------------------

### Node.js Project Setup (pnpm)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to install Node.js dependencies using pnpm when pnpm-lock.yaml is detected.

```bash
pnpm install
```

--------------------------------

### Setup Linux Hotkeys Script

Source: https://github.com/basnijholt/agent-cli/blob/main/scripts/linux-hotkeys/README.md

Execute this script to install notification support, display hotkey bindings, and generate copy-paste configurations for your desktop environment.

```bash
./setup-linux-hotkeys.sh
```

--------------------------------

### Quick Start: TTS Server with Kokoro

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/server/index.md

Install the Kokoro backend and run the TTS server. The server provides an OpenAI-compatible API at http://localhost:10201.

```bash
pip install "agent-cli[kokoro]"
agent-cli server tts --backend kokoro
```

--------------------------------

### Start Memory Proxy with Docker Compose

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/architecture/memory.md

Use this command to start the memory proxy and Ollama backend using Docker Compose for an easy setup. Point your chat client to the specified address.

```bash
# Start Memory proxy with Ollama backend
docker compose -f docker/docker-compose.yml --profile cpu up memory-proxy ollama

# Point your chat client at http://localhost:8100/v1
# The LLM will now remember facts across conversations
```

--------------------------------

### Verify GPU Setup

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/linux.md

Verify that the NVIDIA GPU and CUDA toolkit are correctly installed and configured.

```bash
nvidia-smi
```

```bash
nvcc --version
```

--------------------------------

### Setup Linux Hotkeys

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

Execute this script to install necessary notification tools and configure hotkeys for voice transcription and clipboard actions, supporting various desktop environments on Linux.

```bash
./scripts/setup-linux-hotkeys.sh
```

--------------------------------

### Start RAG Proxy and Chat with OpenAI CLI

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/architecture/rag.md

This setup involves two terminals. The first starts the RAG proxy and pulls necessary Ollama models. The second terminal uses the OpenAI CLI to chat with your documents, with environment variables pointing to the RAG proxy.

```bash
# Terminal 1: Pull models and start proxy
ollama pull embeddinggemma:300m && ollama pull qwen3:4b
uvx -p 3.13 --from "agent-cli[rag]" agent-cli rag-proxy \
  --docs-folder ./my-docs \
  --openai-base-url http://localhost:11434/v1 \
  --embedding-model embeddinggemma:300m
```

```bash
# Terminal 2: Chat with your docs (env vars point to proxy)
OPENAI_BASE_URL=http://localhost:8000/v1 OPENAI_API_KEY=dummy \
  uvx openai api chat.completions.create \
  -m qwen3:4b \
  -g user "What does my documentation say about X?"
```

--------------------------------

### Install agent-cli

Source: https://github.com/basnijholt/agent-cli/blob/main/reddit.md

Install the agent-cli tool using pip or uv. This is the primary method for setting up the application.

```bash
uv tools install agent-cli
```

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

--------------------------------

### Install Agent CLI using uv or pip

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/getting-started.md

Use uv for recommended installation with a specific Python version, or pip for a standard installation.

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

# Using pip
pip install agent-cli
```

--------------------------------

### Quick Start: Whisper Server

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/server/index.md

Install the necessary package and run the Whisper ASR server. The server will be accessible via an OpenAI-compatible API at http://localhost:10301.

```bash
pip install "agent-cli[faster-whisper]"
agent-cli server whisper
```

--------------------------------

### Python Project Setup (unidep)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to install Python dependencies using unidep. If conda-lock.yml is present, it's also used.

```bash
unidep install -e . -n <env>
```

--------------------------------

### Start all services script

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

Launches all AI services in a single terminal session using Zellij. This script is part of the automated full setup.

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

--------------------------------

### Install agent-cli

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/macos.md

Install the agent-cli tool using `uv` or `pip`. The `uv` tool is recommended for faster installation. Specify the Python version if needed.

```bash
uv tool install agent-cli -p 3.13
```

```bash
pip install agent-cli
```

--------------------------------

### Install multiple extra dependencies

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/install-extras.md

You can install multiple optional dependencies simultaneously by listing them after the command, separated by spaces. For instance, to install 'rag', 'memory', and 'vad':

```bash
agent-cli install-extras rag memory vad
```

--------------------------------

### Install Notification Support (Ubuntu/Debian)

Source: https://github.com/basnijholt/agent-cli/blob/main/scripts/linux-hotkeys/README.md

Install the necessary notification library for Ubuntu and Debian-based systems if notifications are not working.

```bash
sudo apt install libnotify-bin  # Ubuntu/Debian
```

--------------------------------

### Install Server Daemons

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/daemon.md

Install agent-cli server daemons as background processes. Options include installing all daemons or skipping confirmation prompts.

```bash
# Install specific daemons
agent-cli daemon install whisper tts-kokoro

# Install all daemons
agent-cli daemon install --all

# Skip confirmation prompts
agent-cli daemon install whisper -y
```

--------------------------------

### Install all required services

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

This command installs all necessary AI services required by the agent-cli tool. It should be run after the agent-cli tool itself is installed.

```bash
agent-cli install-services
```

--------------------------------

### Start Services Individually (Manual)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/linux.md

Manually start individual services required for agent-cli. Each service is started in a separate terminal.

```bash
# Terminal 1: Ollama
ollama serve
```

```bash
# Terminal 2: Whisper (with GPU)
agent-cli server whisper
```

```bash
# Terminal 3: Piper
agent-cli server tts --backend piper
```

```bash
# Terminal 4: OpenWakeWord
scripts/run-openwakeword.sh
```

--------------------------------

### Install a single extra dependency

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/install-extras.md

Install a specific optional dependency by providing its name after the command. For example, to install the 'vad' extra:

```bash
agent-cli install-extras vad
```

--------------------------------

### Install Notification Support (Fedora/RHEL)

Source: https://github.com/basnijholt/agent-cli/blob/main/scripts/linux-hotkeys/README.md

Install the necessary notification library for Fedora and RHEL-based systems if notifications are not working.

```bash
sudo dnf install libnotify      # Fedora/RHEL
```

--------------------------------

### Spawn Agent with Prompt from File (Example Workflow)

Source: https://github.com/basnijholt/agent-cli/blob/main/agent_cli/dev/skill/SKILL.md

Demonstrates the workflow for using `--prompt-file`. First, write the prompt to a file, then spawn the agent using that file. Optionally, clean up the prompt file afterward.

```bash
# 1. Write prompt to file
# 2. Spawn agent with the file
agent-cli dev new my-feature --prompt-file .claude/spawn-prompt.md
# 3. Optionally clean up
rm .claude/spawn-prompt.md
```

--------------------------------

### Install Notification Support (Arch)

Source: https://github.com/basnijholt/agent-cli/blob/main/scripts/linux-hotkeys/README.md

Install the necessary notification library for Arch-based systems if notifications are not working.

```bash
sudo pacman -S libnotify        # Arch
```

--------------------------------

### Install agent-cli

Source: https://github.com/basnijholt/agent-cli/blob/main/reddit.md

Install the agent-cli package using pip. This is the first step in setting up the AI hotkey assistant.

```bash
pip install agent-cli
```

--------------------------------

### Test agent-cli Setup

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/windows.md

Runs a basic transcription command to verify the agent-cli setup is working correctly.

```powershell
agent-cli transcribe
```

--------------------------------

### Go Project Setup

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to download Go module dependencies when go.mod is detected.

```bash
go mod download
```

--------------------------------

### Quick Start with Kokoro

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/server/tts.md

Instructions for quickly setting up and running the TTS server with the Kokoro backend, leveraging GPU acceleration.

```APIDOC
## Quick Start with Kokoro

### Description
This guide outlines the steps to quickly start the agent-cli TTS server using the Kokoro backend, which is recommended for high-quality synthesis with GPU acceleration.

### Installation
```bash
pip install "agent-cli[kokoro]"
```

### Running the Server
```bash
agent-cli server tts --backend kokoro
```

### Verification
Once the server is running, you can verify its status using `curl`:
```bash
curl http://localhost:10201/health
```

The server will automatically download the necessary models from HuggingFace upon first use.
```

--------------------------------

### Implement Plugin System with Agent CLI

Source: https://github.com/basnijholt/agent-cli/blob/main/agent_cli/dev/skill/examples.md

Use this prompt to implement a plugin system and generate documentation simultaneously. It outlines a workflow for reading the codebase, designing the system, and creating an example plugin. Focus on the core requirements and skip advanced features like versioning or sandboxing.

```bash
agent-cli dev new plugin-system --prompt "Implement a plugin system.

<workflow>
- Read existing codebase structure in parallel before designing
- Make incremental git commits as you complete each component
- Run tests and linting before writing your final report
</workflow>

<code_exploration>
Think carefully about the architecture before implementing:
- Read the existing codebase structure to understand where plugins fit
- Check for any existing extension points or hooks
- Look at how configuration is handled
- Understand the application lifecycle

Design the plugin system to integrate naturally with existing patterns.
</code_exploration>

<requirements>
- Plugin base class with lifecycle hooks: on_load(), on_unload(), on_event(event_name, data)
- Plugin registry for discovery and management
- Auto-load plugins from plugins/ directory
- Create one example plugin demonstrating the interface
- Plugins should be able to register event handlers
</requirements>

<scope>
Implement the minimal system that allows extending functionality through plugins. Skip: plugin dependencies, versioning, hot-reloading, sandboxing, or a plugin marketplace.
</scope>

<implementation_notes>
- Use importlib for dynamic loading
- Simple dict-based event system is sufficient
- Plugins should fail gracefully without crashing the app
</implementation_notes>

<report>
After tests pass, write to .claude/REPORT.md:

## Architecture
[Diagram or description of how plugins integrate]

## Plugin Interface
```python
class Plugin:
    # document the interface
```

## Example Plugin
[Show the example plugin code]


```

--------------------------------

### GET /health API Response Example

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/iOS_Shortcut_Guide.md

Example JSON response from the Agent CLI health check endpoint, indicating the server status and version.

```json
{
  "status": "healthy",
  "version": "1.0.0"
}

```

--------------------------------

### Python Example for Audio Transcription with Timestamps

Source: https://github.com/basnijholt/agent-cli/blob/main/scripts/nvidia-asr-server/README.md

This Python example demonstrates how to get word-level timestamps during transcription using the 'parakeet-tdt-0.6b-v2' model. The 'timestamp_granularities' parameter must be set to 'word'.

```python
response = requests.post(
    "http://localhost:9898/v1/audio/transcriptions",
    files={"file": open("audio.wav", "rb")},
    data={
        "model": "parakeet-tdt-0.6b-v2",
        "timestamp_granularities": ["word"]
    }
)

result = response.json()
for word in result.get("words", []):
    print(f"{word['start']:.2f}s - {word['end']:.2f}s: {word['word']}")
```

--------------------------------

### Development installation

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

Commands for setting up the agent-cli for development purposes. Includes cloning the repository, synchronizing dependencies, and activating the virtual environment.

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

--------------------------------

### Generate Markdown Documentation Snippet

Source: https://github.com/basnijholt/agent-cli/blob/main/CLAUDE.md

Example of a markdown-code-runner marker used to generate documentation dynamically. This specific example calls a Python function to get all options for a given command.

```markdown
<!-- CODE:START -->
<!-- from agent_cli.docs_gen import all_options_for_docs -->
<!-- print(all_options_for_docs("transcribe")) -->
<!-- CODE:END -->
```

--------------------------------

### Install Agent CLI with MLX Whisper (Apple Silicon)

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/getting-started.md

Install Agent CLI with MLX Whisper backend for Apple Silicon GPUs. This command also starts a Whisper server.

```bash
pip install "agent-cli[mlx-whisper]"
agent-cli server whisper --backend mlx
```

--------------------------------

### Example Conversation with Tool Usage

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/chat.md

Demonstrates a user query and the AI's response using the read_file tool.

```text
You: "Read the pyproject.toml file and tell me the project version."
AI: (Uses read_file tool) "The project version is 0.5.0."

You: "What dependencies does it have?"
AI: "The project has the following dependencies: typer, pydantic, ..."

You: "Thanks!"
AI: "You're welcome! Let me know if you need anything else."
```

--------------------------------

### Toggle Recording Hotkey Example

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/transcribe.md

Use the --toggle flag for hotkey integration to start and stop recording. The first press starts recording, and the second press stops it and initiates transcription.

```bash
agent-cli transcribe --toggle --input-device-index 1
```

```bash
agent-cli transcribe --toggle
```

--------------------------------

### Start RAG Proxy with Open WebUI

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/architecture/rag.md

This sequence of commands sets up and runs the RAG proxy alongside Open WebUI. It includes pulling necessary Ollama models, starting the Open WebUI, and then launching the RAG proxy. Ensure the docs-folder and OpenAI base URL are correctly configured.

```bash
# 1. Pull the required models (one-time setup)
ollama pull embeddinggemma:300m  # for document embeddings
ollama pull qwen3:4b             # for chat

# 2. Start Open WebUI (runs in background)
#    On Linux, add: --add-host=host.docker.internal:host-gateway
docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e WEBUI_AUTH=false \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8000/v1 \
  -e OPENAI_API_KEY=dummy \
  ghcr.io/open-webui/open-webui:main

# 3. Start the RAG proxy (runs in foreground so you can watch the logs)
uvx -p 3.13 --from "agent-cli[rag]" agent-cli rag-proxy \
  --docs-folder ./my-docs \
  --openai-base-url http://localhost:11434/v1 \
  --embedding-model embeddinggemma:300m

# 4. Open http://localhost:3000, select "qwen3:4b" as model, and chat with your docs
```

--------------------------------

### Quick Start with Piper

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/server/tts.md

Instructions for quickly setting up and running the TTS server with the Piper backend, which is CPU-friendly.

```APIDOC
## Quick Start with Piper

### Description
This guide outlines the steps to quickly start the agent-cli TTS server using the Piper backend, which is a fast, CPU-friendly option.

### Installation
```bash
pip install "agent-cli[piper]"
```

### Running the Server
```bash
agent-cli server tts --backend piper
```

### Verification
Once the server is running, you can verify its status using `curl`:
```bash
curl http://localhost:10201/health
```

The server will automatically download the necessary models and voices upon first use.
```

--------------------------------

### Agent CLI Install Extras Help Output

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

Displays detailed usage information for the `install-extras` command, including available extras and options.

```yaml
Usage: agent-cli install-extras [OPTIONS] [EXTRAS]...

 Install optional dependencies with pinned, compatible versions.

 Many agent-cli features require optional dependencies. This command installs them with
 version pinning to ensure compatibility. Dependencies persist across uv tool upgrade
 when installed via uv tool.

 Available extras:

  • audio - Audio recording/playback
  • diarization - Speaker diarization (pyannote.audio)
  • faster-whisper - Whisper ASR via CTranslate2
  • kokoro - Kokoro neural TTS (GPU)
  • llm - LLM framework (pydantic-ai)
  • memory - Long-term memory proxy
  • mlx-whisper - Whisper ASR for Apple Silicon
  • piper - Piper TTS (CPU)
  • rag - RAG proxy (ChromaDB, embeddings)
  • server - FastAPI server components
  • speed - Audio speed adjustment (audiostretchy)
  • vad - Voice Activity Detection (Silero VAD via ONNX)
  • vectordb - Vector database with embeddings (ChromaDB)
  • whisper-transformers - Whisper ASR via HuggingFace transformers
  • wyoming - Wyoming protocol support

 Examples:


 agent-cli install-extras rag           # Install RAG dependencies
 agent-cli install-extras memory vad    # Install multiple extras
 agent-cli install-extras --list        # Show available extras
 agent-cli install-extras --all         # Install all extras


╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮
│   extras      [EXTRAS]...  Extras to install: audio, diarization, faster-whisper,      │
│                            kokoro, llm, memory, mlx-whisper, piper, rag, server,       │
│                            speed, vad, vectordb, whisper-transformers, wyoming         │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --list  -l        Show available extras with descriptions (what each one enables)      │
│ --all   -a        Install all available extras at once                                 │
│ --help  -h        Show this message and exit.                                          │
╰────────────────────────────────────────────────────────────────────────────────────────╯

```

--------------------------------

### Install uv and agent-cli with Cloud Providers

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/windows.md

Installs uv and agent-cli using PowerShell, then configures API keys for cloud-based ASR and LLM providers.

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install agent-cli
uv tool install agent-cli -p 3.13

# Use with cloud providers (requires API keys)
$env:OPENAI_API_KEY = "sk-..."
agent-cli transcribe --asr-provider openai --llm-provider openai
```

--------------------------------

### Download Whisper model without starting server

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/server/whisper.md

Downloads the specified Whisper model (e.g., large-v3) using the faster-whisper backend without actually starting the ASR server. This requires the faster-whisper backend to be installed.

```bash
agent-cli server whisper --model large-v3 --download-only
```

--------------------------------

### Diarize a 3-person meeting

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/diarize-live-session.md

Example of diarizing a meeting with a known number of speakers. Specify the date, start, and end times of the session.

```bash
# Diarize a 3-person meeting from saved transcribe-live chunks
agent-cli diarize-live-session \
  --date 2026-04-22 \
  --start 11:32 \
  --end 12:29 \
  --speakers 3
```

--------------------------------

### Example Agent CLI Configuration Defaults

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

An example TOML configuration snippet showing default provider settings for LLM, ASR, and TTS. Uncomment and set API keys as needed for cloud services.

```toml
[defaults]
# llm_provider = "ollama"  # 'ollama', 'openai', or 'gemini'
# asr_provider = "wyoming" # 'wyoming', 'openai', or 'gemini'
# tts_provider = "wyoming" # 'wyoming', 'openai', 'kokoro', or 'gemini'
# openai_api_key = "sk-..."
# gemini_api_key = "..."

```

--------------------------------

### Start agent-cli chat with local Ollama LLM

Source: https://github.com/basnijholt/agent-cli/blob/main/README.md

Starts the agent-cli chat command configured to use a local Ollama instance for the Large Language Model (LLM) and the Wyoming ASR provider. This setup is ideal for users who prefer running models locally.

```bash
agent-cli chat --llm-provider ollama
```

--------------------------------

### Start agent-cli services and attach

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/start-services.md

Use this command to start all agent-cli services and automatically attach to the Zellij session. This is the default behavior.

```bash
agent-cli start-services
```

--------------------------------

### List available extras

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/install-extras.md

To see a list of all available optional dependencies and their descriptions, use the `--list` or `-l` flag.

```bash
agent-cli install-extras --list
```

--------------------------------

### Initialize Agent CLI Configuration

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/config.md

Use `config init` to create a new configuration file with all options commented out. Specify a custom path with the `--path` option or use `-f` to overwrite without confirmation.

```bash
agent-cli config init
```

--------------------------------

### Curl Example: Get SRT Subtitles

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/server/whisper.md

Obtain subtitles in SRT format by specifying 'srt' as the response format. This requires a backend/model that supports timestamped output.

```bash
curl -X POST http://localhost:10301/v1/audio/transcriptions \
  -F "file=@recording.wav" \
  -F "model=whisper-1" \
  -F "response_format=srt"
```

--------------------------------

### Install agent-cli with Kokoro support using uv

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/server/tts.md

Install the agent-cli with Kokoro support using the uv package manager. This is an alternative to using pip.

```bash
uv sync --extra kokoro
```

--------------------------------

### Quick Start: Transcription Proxy Server

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/server/index.md

Install the server package and run the transcription proxy. This proxy forwards requests to your configured ASR provider and runs at http://localhost:61337.

```bash
pip install "agent-cli[server]"
agent-cli server transcribe-proxy
```

--------------------------------

### Setup System-wide Hotkeys

Source: https://github.com/basnijholt/agent-cli/blob/main/reddit.md

Set up system-wide hotkeys for agent-cli on Linux or macOS to enable quick access to AI functionalities.

```bash
./scripts/setup-macos-hotkeys.sh
```

```bash
# Bind to system-wide hotkeys
./scripts/setup-linux-hotkeys.sh  # or setup-macos-hotkeys.sh
```

--------------------------------

### Spawn New Agent for a Feature

Source: https://github.com/basnijholt/agent-cli/blob/main/agent_cli/dev/skill/SKILL.md

Creates a new git worktree and branch, installs dependencies, saves the prompt, and launches an AI agent for a new feature. Use for tasks starting from origin/main.

```bash
agent-cli dev new <branch-name> --prompt "Implement the new feature..."
```

--------------------------------

### Dev New Command Options

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Customize the creation of new development environments with various options, including specifying the source branch, opening in an editor, starting an AI agent, and configuring environment setup.

```bash
agent-cli dev new [BRANCH] [OPTIONS]
```

--------------------------------

### Rust Project Setup

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/dev.md

Command to build Rust project dependencies when Cargo.toml is detected.

```bash
cargo build
```

--------------------------------

### JSON Diarization Output

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/transcribe.md

Use the `--diarize-format json` flag to get diarization results in a structured JSON format. This format includes speaker, start time, end time, and the transcribed text for each segment.

```json
{
  "segments": [
    {"speaker": "SPEAKER_00", "start": 0.0, "end": 2.5, "text": "Hello, how are you today?"},
    {"speaker": "SPEAKER_01", "start": 2.7, "end": 4.1, "text": "I'm doing well, thanks for asking!"},
    {"speaker": "SPEAKER_00", "start": 4.3, "end": 5.2, "text": "Great to hear."}
  ]
}
```

--------------------------------

### Test agent-cli installation

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/index.md

After installing the agent-cli package, run this command to verify the installation and check its help documentation.

```bash
agent-cli autocorrect --help
```

--------------------------------

### Start Services with CPU Only

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/installation/docker.md

Use this command to start all services using only the CPU. This is an alternative if GPU acceleration is not available or needed.

```bash
docker compose -f docker/docker-compose.yml --profile cpu up
```

--------------------------------

### Install Agent-CLI with Server Extra

Source: https://github.com/basnijholt/agent-cli/blob/main/docs/commands/server/transcribe-proxy.md

Install the agent-cli package with the necessary 'server' extra for running the transcribe-proxy. Alternatively, use `uv sync` with the --extra server flag.

```bash
pip install "agent-cli[server]"
```

```bash
uv sync --extra server
```

--------------------------------

### Manage Development Environments with Git Worktrees

Source: https://context7.com/basnijholt/agent-cli/llms.txt

Commands for managing parallel development environments using git worktrees. Create new worktrees for feature branches, optionally starting an AI agent or specifying a prompt. You can also branch from specific references, use custom agents and editors, list, status, remove, and get paths to worktrees. Commands are also available to start agents or open editors in existing worktrees, run commands within them, and clean up merged or abandoned worktrees. System requirements and available tools can be checked with `doctor`, and lists of agents, editors, and terminals can be displayed.

```bash
agent-cli dev new feature-login
```

```bash
agent-cli dev new feature-auth --start-agent
```

```bash
agent-cli dev new --prompt "Fix the authentication bug in login.py"
```

```bash
agent-cli dev new --branch-name-mode ai --prompt "Implement dark mode toggle"
```

```bash
agent-cli dev new feature-x -e --start-agent
```

```bash
agent-cli dev new hotfix --from v1.2.3
```

```bash
agent-cli dev new feature --from origin/develop
```

```bash
agent-cli dev new feature --agent claude --with-editor cursor
```

```bash
agent-cli dev list
```

```bash
agent-cli dev list --json
```

```bash
agent-cli dev status
```

```bash
agent-cli dev rm feature-login
```

```bash
agent-cli dev rm feature-login --force --delete-branch
```

```bash
cd "$(agent-cli dev path my-feature)"
```

```bash
agent-cli dev agent my-feature
```

```bash
agent-cli dev agent my-feature -a claude -p "Continue the auth refactor"
```

```bash
agent-cli dev editor my-feature
```

```bash
agent-cli dev editor my-feature --editor vscode
```

```bash
agent-cli dev run my-feature npm test
```

```bash
agent-cli dev run my-feature git status
```

```bash
agent-cli dev clean --merged
```

```bash
agent-cli dev clean --no-commits
```

```bash
agent-cli dev doctor
```

```bash
agent-cli dev agents
```

```bash
agent-cli dev editors
```

```bash
agent-cli dev terminals
```

```bash
agent-cli dev install-skill
```

--------------------------------

### Install Agent CLI via Pip

Source: https://github.com/basnijholt/agent-cli/blob/main/reddit.md

Provides instructions for installing the agent-cli package using pip, including the command for development installations.

```bash
pip install agent-cli
# or for development:
git clone https://github.com/basnijholt/agent-cli
cd agent-cli
pip install -e .
```