How batrachianai/toad works
Toad is a Python terminal application built on top of the Textual TUI framework. Architecturally, it sits between a human user, local shell access, and one or more external AI coding agents. The repo is organized around that split: a UI layer, an agent/protocol layer, local system integration, and persistence/session management.
Main entry points and runtime shape:
• src/toad/__main__.py and src/toad/cli.py provide the command-line entrypoint.
• src/toad/app.py is the top-level application coordinator for the interactive UI.
• The README also exposes a serve mode, so the same app can run as a terminal UI or via Textual’s web server transport.
• Makefile, pyproject.toml, and .python-version indicate a standard Python package workflow, likely with a pinned modern Python runtime.
High-level subsystem boundaries:
1. UI and screen navigation
• The src/toad/screens/ package contains the main application screens and modal flows:
- main.py for the primary chat/agent workspace
- settings.py, store.py, sessions.py, session_resume_modal.py, agent_modal.py, action_modal.py, permissions.py, command_edit_modal.py
• These screens are backed by .tcss files, so layout/styling is a first-class part of the architecture.
• The app is built from reusable widgets in src/toad/widgets/, which encapsulate the major UI regions:
- conversation display, agent response/thought rendering, prompt editor, shell terminal, diffs, session tabs, file pickers, menus, side bar, status/flash/throbber components, and specialized controls for slash commands and tool calls.
• This separation suggests the main app is assembled from composable views rather than a monolithic screen.
2. Agent integration layer
• The src/toad/acp/ package is the protocol-facing layer for talking to coding agents using the Agent Client Protocol.
- protocol.py, api.py, messages.py, prompt.py, and agent.py define the agent communication model.
- encode_tool_call_id.py suggests tool calls are tracked and encoded explicitly across requests/responses.
• src/toad/agents.py, src/toad/agent.py, and src/toad/agent_schema.py appear to normalize agent definitions and capabilities.
• src/toad/data/agents/*.toml contains agent metadata for many providers and products, such as Claude, OpenAI, Gemini, Copilot, Cursor, Goose, OpenHands, and others.
• This indicates Toad does not hardcode a single backend; instead it loads agent definitions from packaged data and speaks to them through a common protocol boundary.
3. Conversation and prompt construction
• src/toad/prompt/, src/toad/prompt/extract.py, and src/toad/prompt/resource.py support prompt composition.
• src/toad/conversation_markdown.py, src/toad/messages.py, src/toad/option_content.py, and src/toad/answer.py help transform agent/user content into renderable or transportable forms.
• src/toad/slash_command.py indicates command-style prompt augmentation.
• The prompt flow appears to combine:
- typed user text
- file references
- markdown-rich formatting
- optional slash commands
- resource extraction/attachment
• The UI widgets prompt, highlighted_textarea, slash_complete, path_search, directory_input, and project_directory_tree support this input pipeline.
4. Local shell and command execution
• One of the core differentiators in Toad is that it embeds a real shell session rather than just spawning isolated commands.
• src/toad/shell.py and src/toad/shell_read.py provide shell execution and output capture.
• src/toad/widgets/shell_terminal.py, terminal.py, and terminal_tool.py are the UI-facing shell surfaces.
• The README emphasizes persistent working directory and environment state, interactive commands, tab completion, and full-color output.
• This makes the shell an independent subsystem, not just a tool invocation helper, and it feeds results back into the agent conversation as structured terminal output.
5. Filesystem, path, and fuzzy navigation
• Toad has extensive filesystem-aware UX:
- src/toad/fuzzy.py, fuzzy_index.py, path_filter.py, path_complete.py, paths.py, directory.py, directory_suggester.py, directory_watcher.py, format_path.py, conversation_markdown.py
- internal helpers like _path_fuzzy_search.py, _path_match.py, and path_complete.py
• The UI exposes these through file pickers and tree views:
- widgets/path_search.py, widgets/project_directory_tree.py, widgets/condensed_path.py, widgets/directory_input.py
• This subsystem supports the @file workflow described in the README, where files can be searched and inserted into prompts quickly.
• It also supports project directory awareness, which is important because the current working directory is treated as the agent’s workspace context.
6. Session, history, and persistence
• src/toad/session_tracker.py, history.py, db.py, and settings.py point to local persistence of sessions, preferences, and prior conversation state.
• The README’s session resume feature maps directly to screens/session_resume_modal.py and the session widgets (session_grid_select, session_tabs, session_summary).
• This suggests a persistent state boundary that stores:
- active and historical agent sessions
- UI settings
- possibly conversation transcripts or session metadata
• src/toad/settings_schema.py and src/toad/agent_schema.py imply schema-driven configuration rather than free-form config files.
7. Rendering and terminal-native presentation
• src/toad/ansi/ contains ANSI parsing and styling helpers, which is important for capturing and faithfully rendering shell output in a terminal UI.
• src/toad/visuals/columns.py and widgets like diff_view.py, markdown_note.py, agent_thought.py, agent_response.py, tool_call.py, question.py, welcome.py, and version.py indicate a rich rendering layer for structured conversation content.
• src/toad/ansi/_stream_parser.py suggests streamed terminal output is parsed incrementally, which is important for live shell feedback and agent streaming responses.
Important data flows:
• User input flow:
- The user types in the main prompt/editor widget.
- The app may expand file references, slash commands, or path completions.
- Prompt content is transformed into the agent protocol format and sent through the ACP layer.
• Agent response flow:
- Agent messages stream back through ACP.
- The UI converts those into markdown, thought/response blocks, tool calls, and action prompts.
- Tool calls may trigger shell execution or permissions flows before results are reinjected into the conversation.
• Shell feedback flow:
- Commands run in the embedded shell preserve state across invocations.
- Output is captured as ANSI/terminal data, rendered in the UI, and may be attached back to the agent context.
- Interactive or colorized output is treated as a first-class UI artifact.
• File/context flow:
- The project directory is the root context for browsing, fuzzy search, and file insertion.
- Directory watchers and path helpers keep the UI responsive to filesystem changes.
- Selected files are turned into prompt resources rather than merely pasted text.
• Session persistence flow:
- Active session state is tracked locally.
- Users can resume previous sessions via modal selection.
- Settings and agent/store metadata are also persisted or bundled for reuse.
External boundaries and integrations:
• External AI agents are reached via ACP and are represented by packaged TOML definitions under src/toad/data/agents/.
• The application relies on the local terminal environment and platform tools such as clipboard support utilities on Linux.
• Images and sounds under src/toad/data/ are runtime assets used by the UI for feedback and polish.
• The serve mode introduces a web-hosted presentation boundary, but it still uses the same core app and state model.
In architectural terms, Toad is best drawn as:
• a Textual-based presentation layer on top,
• a central application/controller layer in the middle,
• and three major outbound domains underneath: agent protocol backends, a persistent local shell, and local persistence/filesystem services.
That combination is what makes Toad more than an agent chat UI: it is an integrated terminal workspace where agent conversations, shell work, file navigation, and session history all share one coordinated state model.
Main entry points: main.py Main screen · app.py App · conversation.py Widgets · shell.py Shell
Components 17
UI
Textual screens and reusable widgets for the interactive terminal workspace
- CLI · Command-line startup and mode selection
src/toad/cli.py - App · Top-level application controller
src/toad/app.py - Main screen · Primary chat and workspace screen
src/toad/screens/main.py - Modals · Agent, action, permissions, settings, store, and session flows
src/toad/screens/settings.py - Widgets · Conversation, prompt, shell, diff, session, and tool-call widgets
src/toad/widgets/conversation.py - Styles · Screen and app styling for the Textual interface
src/toad/screens/main.tcss
Agent layer
Protocol, agent definitions, and prompt/message shaping
- ACP · Agent Client Protocol API, messages, prompt, and transport model
src/toad/acp/protocol.py - Agents · Packaged agent definitions and schema normalization
src/toad/data/agents/claude.com.toml - Prompts · Prompt composition, resources, extraction, and slash commands
src/toad/prompt/extract.py - Messages · Conversation, answers, and transportable message forms
src/toad/messages.py
Local runtime
Shell execution, ANSI streaming, and filesystem navigation
- Shell · Embedded local shell execution and captured output
src/toad/shell.py - ANSI · ANSI parsing and streamed terminal rendering helpers
src/toad/ansi/_stream_parser.py - Paths · Fuzzy search, path completion, directory watching, and formatting
src/toad/fuzzy.py - File pickers · Path search, directory tree, and project directory selection widgets
src/toad/widgets/project_directory_tree.py
State
Sessions, settings, history, and persistence
- Sessions · Session tracking and resume support
src/toad/session_tracker.py - Storage · Database, history, and settings persistence
src/toad/db.py - Settings schema · Structured settings and configuration model
src/toad/settings_schema.py
Connections 19
- CLI → App: launches · CLI starts the application coordinator
- App → Main screen: opens · App loads the primary workspace screen
- App → Modals: navigates · App switches to settings, agent, permissions, and resume flows
- Main screen → Widgets: composes · Primary screen is built from reusable widgets
- App → Styles: applies · Textual styles shape the UI
- Main screen → ACP: sends prompts · User input is transformed and sent to agent protocol backends
- ACP → Agents: resolves agents · Protocol layer uses packaged agent metadata
- Main screen → Prompts: builds input · Prompt editor, file attachments, and slash commands form agent input
- Prompts → Messages: formats · Prompt builder produces structured message content
- Main screen → Shell: runs commands · Workspace shell executes local commands with persistent state
- Shell → ANSI: streams output · Shell output is parsed and rendered as ANSI/terminal content
- Main screen → Paths: discovers files · Workspace uses fuzzy path search and completion
- Paths → File pickers: feeds · Filesystem navigation powers file picker widgets
- Main screen → Sessions: tracks · Active work is attached to session state
- Sessions → Storage: persists · Session history and metadata are stored locally
- Storage → Settings schema: constrains · Persisted configuration follows schema definitions
- Modals → Sessions: resumes · Session resume modal restores prior work
- Widgets → Shell: renders · Terminal and shell result widgets present execution output
- Widgets → Messages: renders · Conversation widgets display agent and user content