> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Toad Terminal

> Use OpenHands with the Toad universal terminal interface for AI agents

[Toad](https://github.com/Textualize/toad) is a universal terminal interface for AI agents, created by [Will McGugan](https://willmcgugan.github.io/), the creator of the popular Python libraries [Rich](https://github.com/Textualize/rich) and [Textual](https://github.com/Textualize/textual).

The name comes from "**t**extual c**ode**"—combining the Textual framework with coding assistance.

![Toad Terminal Interface](https://willmcgugan.github.io/images/toad-released/toad-1.png)

## Why Toad?

Toad provides a modern terminal user experience that addresses several limitations common to existing terminal-based AI tools:

* **No flickering or visual artifacts** - Toad can update partial regions of the screen without redrawing everything
* **Scrollback that works** - You can scroll back through your conversation history and interact with previous outputs
* **A unified experience** - Instead of learning different interfaces for different AI agents, Toad provides a consistent experience across all supported agents through ACP

OpenHands is included as a recommended agent in Toad's agent store.

## Prerequisites

Before using Toad with OpenHands:

1. **OpenHands CLI installed** - See [Installation](/openhands/usage/cli/installation)
2. **LLM settings configured** - Run `openhands` and use `/settings`

## Installation

Install Toad using [uv](https://docs.astral.sh/uv/):

```bash theme={null}
uvx batrachian-toad
```

For more installation options and documentation, visit [batrachian.ai](https://www.batrachian.ai/).

## Setup

### Using the Agent Store

The easiest way to set up OpenHands with Toad:

1. Launch Toad: `uvx batrachian-toad`
2. Open Toad's agent store
3. Find **OpenHands** in the list of recommended agents
4. Click **Install** to set up OpenHands
5. Select OpenHands and start a conversation

The install process runs:

```bash theme={null}
uv tool install openhands --python 3.12 && openhands login
```

### Manual Configuration

You can also launch Toad directly with OpenHands:

```bash theme={null}
toad acp "openhands acp"
```

## Usage

### Basic Usage

```bash theme={null}
# Launch Toad with OpenHands
toad acp "openhands acp"
```

### With Command Line Arguments

Pass OpenHands CLI flags through Toad:

```bash theme={null}
# Use LLM-based approval mode
toad acp "openhands acp --llm-approve"

# Auto-approve all actions
toad acp "openhands acp --always-approve"
```

### Resume a Conversation

Resume a specific conversation by ID:

```bash theme={null}
toad acp "openhands acp --resume abc123def456"
```

Resume the most recent conversation:

```bash theme={null}
toad acp "openhands acp --resume --last"
```

<Tip>
  Find your conversation IDs by running `openhands --resume` in a regular terminal.
</Tip>

## Advanced Configuration

### Combined Options

```bash theme={null}
# Resume with LLM approval
toad acp "openhands acp --resume --last --llm-approve"
```

### Environment Variables

Pass environment variables to OpenHands:

```bash theme={null}
LLM_API_KEY=your-key toad acp "openhands acp"
```

## Troubleshooting

### "openhands" command not found

Ensure OpenHands is installed:

```bash theme={null}
uv tool install openhands --python 3.12
```

Verify it's in your PATH:

```bash theme={null}
which openhands
```

### Agent doesn't respond

1. Check your LLM settings: `openhands` then `/settings`
2. Verify your API key is valid
3. Check network connectivity to your LLM provider

### Conversation not persisting

Conversations are stored in `~/.openhands/conversations`. Ensure this directory exists and is writable.

## See Also

* [IDE Integration Overview](/openhands/usage/cli/ide/overview) - ACP concepts and other IDEs
* [Toad Documentation](https://www.batrachian.ai/) - Official Toad documentation
* [Terminal Mode](/openhands/usage/cli/terminal) - Use OpenHands directly in terminal
* [Resume Conversations](/openhands/usage/cli/resume) - Find conversation IDs