Toad

A unified interface for AI in your terminal (release announcement).

Quickstart

Install:

curl -fsSL batrachian.ai/install | sh

Run:

toad

See Getting Started if you have any problems.

What is Toad?

Toad is an interface to coding agents, such as Claude, Gemini, Codex, OpenHand, and many more.

Toad blends a traditional shell based workflow and powerful agentic AI, with an intuitive Terminal User Interface.

AI "App store" Find, install, and run dozens of agents directly from the Toad UI. There is a large and growing list of AI agents that work with Toad. Discover agents from big tech and smaller Open Source projects. Developers can add support for their own agents, via the Agent Client Protocol.
Toad Shell While most terminal agent interfaces can run commands (with the ! syntax), they aren't running a shell. If you change directory or set environment variables, they won't persist from one command to the next. Output that contains more than simple text will typically be garbled, and anything interactive will fail or even break the TUI entirely. Toad integrates a fully working shell with full-color output, interactive commands, and tab completion. Allowing you to interleave prompts for the agent with terminal workflows. At time of writing Toad is the only terminal UI which does this.
Prompt Editor Toad has a nice Markdown prompt editor, with syntax highlighting for code fences. Full mouse support, cut and paste, many keybindings and shortcuts.
File Picker Add a file to your prompt with @, and toad will show a fuzzy file picker. Type a few characters from the filename or folder and Toad will refine the search as you type. Hit enter to add the file to the prompt. The fuzzy picker is great when you know the file you want to mention. If you want to explore your files, you can press tab to switch to an interactive tree control.
Beautiful Diffs Side-by-side or unified diffs, with syntax highlighting for most languages.
Elegant Markdown Markdown is the language of LLMs (AI). Toad's streaming Markdown support can display syntax highlighted code fences, elegant tables, quotes, lists, and more.
Simple Settings An intuitive settings system (no need to manually edit JSON files). Tune Toad to your liking. Almost everything in Toad may be tweaked. If you want to create an ultra-minimal UI with nothing more than a prompt—you can!
Concurrent sessions Launch and run multiple agents from potentially different providers. Hit ctrl+s to show the current state of all your agents in one screen.
Session Resume Resume previous sessions with your agent. Hit ctrl+r to pick a previous session to resume.

Video

Watch a preview of the Toad User Interface:

fizz.mp4

Compatibility

Toad runs on Linux and macOS. Native Windows support is currently lacking (but on the roadmap), but Toad will run quite well with WSL.

Toad is a terminal application. Any terminal will work, although if you are using the default terminal on macOS you will get a much reduced experience. I recommend Ghostty which is fully featured and has amazing performance.

Clipboard

On Linux, you may need to install xclip to enable clipboard support.

sudo apt install xclip

Getting Started

The easiest way to install Toad is by pasting the following in to your terminal:

curl -fsSL batrachian.ai/install | sh

You should now have toad installed.

If that doesn't work for any reason, then you can install with the following steps:

First install UV:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then use UV to install toad:

uv tool install -U batrachian-toad --python 3.14

Toad is also available on conda-forge, and can be installed using pixi:

pixi global install batrachian-toad

Using Toad

Launch Toad with the following:

toad

You should see something like this:

From this screen you will be able to find, install, and launch a coding agent. If you already have an agent installed, you can skip the install step. To launch an agent, select it and press space.

The footer will always display the most significant keys for the current context. To see all the keys, press F1 to display the help panel.

Toad CLI

When running Toad, the current working directory is assumed to be your project directory. To use another project directory, add the path to the command. For example:

toad ~/projects/my-awesome-app

If you want to skip the initial agent screen, add the -a switch with the name of your chosen agent. For example:

toad -a open-hands

To see all subcommands and switches, add the --help switch:

toad --help

Web server

You can run Toad as a web application.

Run the following, and click the link in the terminal:

toad serve

Toad development

Toad was built by Will McGugan and is currently under active development.

To discuss Toad, see the Discussions tab, or join the #toad channel on the Textualize discord server.

Pi MCP inventory (draft integration)

During an active ACP turn, Toad may also render a package-owned live MCP status note delivered by the agent-comms relay inside a zero-text ACP chunk (_meta.agentComms.mcpClient). It is accepted only while a server-owned turn is active, expires with that turn's settlement, is redacted (no command, env or digest) and is never a grant or approval. Missing or malformed receipts mean static-only; they never disable the package.

Toad's command palette offers Pi MCP inventory, a read-only view of the installed Pi MCP package's redacted, static version-2 declaration snapshot. Configure mcp.node_path and mcp.cli_path in Toad's user settings as absolute paths to Node and the installed package's bin/pi-mcp.mjs. Toad will not find a package from PATH, a source checkout, or project files. An absent, incompatible, or failing CLI shows unavailable; a configured CLI path is user-selected and is not proof that an ACP session has loaded the package. Inventory runs without a TTY; local decisions require a visible PTY. Toad never parses MCP config, approval ledgers, or protocol messages.

This snapshot does not report live server state. On POSIX, Toad offers package-owned Deny project and Require call asks through a visible local PTY. Each action rechecks the whole typed snapshot, then the package displays its complete declaration and exact digest challenge. The user must type the answer personally; Toad cannot auto-answer or claim approval. Its child is stopped on dismissal, timeout, or lost controller, but a package write already committed cannot be rolled back; refresh inventory to inspect an uncertain outcome. Positive Approve project and Allow autonomous calls likewise launch the package CLI in the visible PTY: the package owns the whole approval display, challenge and ledger write, and a project denial retires previous grants while a grant commit revalidates its approval under the ledger lock. The CLI entrypoint bytes are identical across vulnerable and fixed builds, so positive grants additionally require the installed package to advertise the exact package-owned inventory compatibility capability {version: 1, positiveDecisions: "locked-project-approval-v1"}; missing, malformed or unsupported capability keeps Approve/Allow held while Deny/Require-asks stay available.\nOn other platforms or when the package CLI is absent, actions are unavailable. Use the installed package CLI in a local terminal for supported manual operations; changes apply on the next Pi turn. This optional draft is not a full MCP server management UI.

Roadmap

Some planned features:

• UI for MCP servers
• Expose model selection (waiting on ACP update)
• Sessions (resume)
• Multiple agents
• Windows native support
• Builtin editor
• Sidebar (widgets)
  • Git pending changes

Reporting bugs

This project is trialling a non-traditional approach to issues. Before an issue is created, there must be a post in Discussions, approved by a Toad dev (Currently @willmcgugan).

By allowing the discussions to happen in the Discussion tabs, issues can be reserved for actionable tasks with a clear description and goal.

Licensing

Toad is licensed under the AGPL license. Commercial licenses are available. See COMMERCIAL_LICENSE.md.