adh-cli

# ADH CLI

ADH CLI is a policy-aware Terminal User Interface (TUI) for working with Google’s Gemini / ADK platform. It combines a chat-forward experience with tool orchestration, safety checks, and human-in-the-loop confirmation so you can explore ideas safely from your terminal.

## Highlights
- **Policy-aware orchestration** – Every tool call flows through a policy engine (`PolicyDecision`, safety pipeline, audit logging) before execution.
- **Human-in-the-loop tooling** – The tool execution manager shows pending/active runs, supports confirmation and cancellation, and keeps a local history.
- **Optional Google web tools** – Gemini’s built-in web search and URL context (requires Python 3.10+).
- **Configurable agents** – Agents are defined in Markdown (`adh_cli/agents/`) and loaded at runtime with variable substitution and model overrides.
- **Themed Textual UI** – Dark/light themes, command palette integrations, clipboard export, and keyboard-friendly chat navigation.
- **XDG-compliant storage** – Config, policies, audit logs, and backups live under `~/.config/adh-cli/` via `ConfigPaths`.
- **Well-tested codebase** – 300+ pytest cases cover core logic, UI widgets, policies, safety checks, and services.

## Quick Start

### Prerequisites
- Python 3.10 or newer
- [`uv`](https://github.com/astral-sh/uv) for fast, reproducible environments (pip works too)

### Clone & Install
```bash
git clone https://github.com/allenhutchison/adh-cli.git
cd adh-cli

# Create and activate a virtual environment (uv recommended)
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install the project with development extras
uv pip install -e '.[dev]'
# or use the task helper
task install-dev
```

### First Run
```bash
# Provide a Claude API key via env or .env
export GOOGLE_API_KEY="your-api-key"  # or GEMINI_API_KEY

# Launch the TUI
adh-cli              # console script entry point
# or use the task wrapper
task run

# Enable Textual dev tools
task dev