The Problem
Developers juggle multiple AI coding agents (Claude, Gemini, Codex) across separate terminal tools, each with its own interface, prompt syntax, and shell integration. Switching between agents means re-learning UIs and losing context. Toad unifies agent access behind a single terminal UI while preserving a real shell workflow.
What This Does
Toad is a Textual-based terminal application that acts as a front-end for coding agents. It discovers and installs agents from a built-in catalog (src/toad/data/agents/.toml), speaks the Agent Client Protocol (src/toad/acp/), and renders a full TUI with a prompt editor, fuzzy file picker, diff viewer, and agent response widgets. The shell integration (src/toad/shell.py, src/toad/shellread.py) runs a real interactive shell inside the TUI, so cd and environment variables persist between commands—something most agent UIs don't do.
Core logic lives in src/toad/: app.py and cli.py are entry points, screens/main.py is the primary UI, and widgets/ holds the individual components (conversation, prompt, terminal, tool calls). Settings are schema-driven via settingsschema.py and settings.py. The agent catalog is plain TOML files, making it straightforward to add new agents.
How To Use It
The repo has a pyproject.toml and a Makefile, so installation is pip/uv-based. There is no documented setup command in the README excerpt; the standard approach would be pip install -e . or uv sync from the repo root. The Makefile likely has targets for dev and build, but I can't confirm without seeing its contents.
Configuration: Agent credentials are typically provided via environment variables or the agent's own config files, but the repo doesn't document which variables Toad expects. Settings are managed in-app via src/toad/screens/settings.py and persisted through src/toad/settings.py.
Running it: The entry point is src/toad/main.py, so the command is toad after installation, or python -m toad from the repo root. The CLI is defined in src/toad/cli.py.
cd toad pip install -e . toad
The README doesn't document a first-run wizard or agent setup flow, so that's likely discovered in the UI itself.
Real-World Use
A developer working across multiple projects can launch Toad, pick an agent from the catalog (e.g., claude.com.toml), and interleave shell commands with agent prompts. For example: run git log --oneline in the embedded shell, reference a file with @src/toad/agent.py via the fuzzy picker, then ask the agent to refactor that file. Toad handles the agent protocol, renders the diff, and the shell state persists for the next command.
Code Health & Issues
Med - No test files detected - the entire src/ tree has no test_.py files, so the ACP protocol, shell integration, and UI logic are unverified. High regression risk. Med - No CI/CD pipeline - .github/ contains only issue templates and funding config, no workflow files. No automated build or test gate. Low - No dependency lockfile - only pyproject.toml is present, so builds are not reproducible. uv.lock or poetry.lock is missing. Low - Unusual project/calculator.py - a standalone calculator app in the root suggests a demo or leftover, not part of the main Toad application.
The codebase is otherwise well-structured: clear separation of concerns (protocol, widgets, screens, data), a schema-driven settings system, and a consistent file layout. The absence of tests is the main concern for a tool that wraps arbitrary agent protocols.
The Bottom Line
Toad is a well-architected terminal UI for AI agents, solving a real workflow problem with a genuinely useful shell integration. It's not production-ready for critical workflows—no tests, no CI, and the agent protocol layer is complex enough to need coverage. For a developer comfortable with early-stage tools, it's worth trying; for a team, wait for test coverage and a lockfile.