# batrachianai/toad architecture

> Architecture diagram of the GitHub repository batrachianai/toad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/batrachianai/toad
- Repository: https://github.com/batrachianai/toad

## Overview

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: [`src/toad/screens/main.py`](https://github.com/batrachianai/toad/blob/HEAD/src/toad/screens/main.py) (Main screen), [`src/toad/app.py`](https://github.com/batrachianai/toad/blob/HEAD/src/toad/app.py) (App), [`src/toad/widgets/conversation.py`](https://github.com/batrachianai/toad/blob/HEAD/src/toad/widgets/conversation.py) (Widgets), [`src/toad/shell.py`](https://github.com/batrachianai/toad/blob/HEAD/src/toad/shell.py) (Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "UI"
  cli["CLI<br/>entrypoint<br/>[cli.py]"]
  main_app["App<br/>coordinator<br/>[app.py]"]
  main_screen["Main screen<br/>[main.py]"]
  modal_screens["Modals<br/>screen set<br/>[settings.py]"]
  widgets["Widgets<br/>ui components<br/>[conversation.py]"]
  styles["Styles<br/>tcss<br/>[main.tcss]"]
end

subgraph "Agent layer"
  acp["ACP<br/>protocol layer<br/>[protocol.py]"]
  agent_defs["Agents<br/>agent registry<br/>[claude.com.toml]"]
  prompting["Prompts<br/>prompt builder<br/>[extract.py]"]
  messages["Messages<br/>content model<br/>[messages.py]"]
end

subgraph "Local runtime"
  shell["Shell<br/>runtime<br/>[shell.py]"]
  ansi["ANSI<br/>stream parser<br/>[_stream_parser.py]"]
  paths["Paths<br/>fs navigation<br/>[fuzzy.py]"]
  directory_ui["File pickers<br/>fs ui"]
end

subgraph "State"
  sessions["Sessions<br/>state model<br/>[session_tracker.py]"]
  storage[("Storage<br/>persistence<br/>[db.py]")]
  settings_schema["Settings schema<br/>[settings_schema.py]"]
end

cli -->|"launches"| main_app
main_app -->|"opens"| main_screen
main_app -->|"navigates"| modal_screens
main_screen -->|"composes"| widgets
main_app -->|"applies"| styles
main_screen -->|"sends prompts"| acp
acp -->|"resolves agents"| agent_defs
main_screen -->|"builds input"| prompting
prompting -->|"formats"| messages
main_screen -->|"runs commands"| shell
shell -->|"streams output"| ansi
main_screen -->|"discovers files"| paths
paths -->|"feeds"| directory_ui
main_screen -->|"tracks"| sessions
sessions -->|"persists"| storage
storage -->|"constrains"| settings_schema
modal_screens -->|"resumes"| sessions
widgets -->|"renders"| shell
widgets -->|"renders"| messages

click cli "https://github.com/batrachianai/toad/blob/main/src/toad/cli.py"
click main_app "https://github.com/batrachianai/toad/blob/main/src/toad/app.py"
click main_screen "https://github.com/batrachianai/toad/blob/main/src/toad/screens/main.py"
click modal_screens "https://github.com/batrachianai/toad/blob/main/src/toad/screens/settings.py"
click widgets "https://github.com/batrachianai/toad/blob/main/src/toad/widgets/conversation.py"
click styles "https://github.com/batrachianai/toad/blob/main/src/toad/screens/main.tcss"
click acp "https://github.com/batrachianai/toad/blob/main/src/toad/acp/protocol.py"
click agent_defs "https://github.com/batrachianai/toad/blob/main/src/toad/data/agents/claude.com.toml"
click prompting "https://github.com/batrachianai/toad/blob/main/src/toad/prompt/extract.py"
click messages "https://github.com/batrachianai/toad/blob/main/src/toad/messages.py"
click shell "https://github.com/batrachianai/toad/blob/main/src/toad/shell.py"
click ansi "https://github.com/batrachianai/toad/blob/main/src/toad/ansi/_stream_parser.py"
click paths "https://github.com/batrachianai/toad/blob/main/src/toad/fuzzy.py"
click directory_ui "https://github.com/batrachianai/toad/blob/main/src/toad/widgets/project_directory_tree.py"
click sessions "https://github.com/batrachianai/toad/blob/main/src/toad/session_tracker.py"
click storage "https://github.com/batrachianai/toad/blob/main/src/toad/db.py"
click settings_schema "https://github.com/batrachianai/toad/blob/main/src/toad/settings_schema.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class cli,main_app,main_screen,modal_screens,widgets,styles toneBlue
class acp,agent_defs,prompting,messages toneAmber
class shell,ansi,paths,directory_ui toneMint
class sessions,storage,settings_schema toneRose
```

## Components

### UI

Textual screens and reusable widgets for the interactive terminal workspace

- [CLI](https://github.com/batrachianai/toad/blob/HEAD/src/toad/cli.py): entrypoint · Command-line startup and mode selection · `src/toad/cli.py`
- [App](https://github.com/batrachianai/toad/blob/HEAD/src/toad/app.py): coordinator · Top-level application controller · `src/toad/app.py`
- [Main screen](https://github.com/batrachianai/toad/blob/HEAD/src/toad/screens/main.py): screen · Primary chat and workspace screen · `src/toad/screens/main.py`
- [Modals](https://github.com/batrachianai/toad/blob/HEAD/src/toad/screens/settings.py): screen set · Agent, action, permissions, settings, store, and session flows · `src/toad/screens/settings.py`
- [Widgets](https://github.com/batrachianai/toad/blob/HEAD/src/toad/widgets/conversation.py): ui components · Conversation, prompt, shell, diff, session, and tool-call widgets · `src/toad/widgets/conversation.py`
- [Styles](https://github.com/batrachianai/toad/blob/HEAD/src/toad/screens/main.tcss): tcss · Screen and app styling for the Textual interface · `src/toad/screens/main.tcss`

### Agent layer

Protocol, agent definitions, and prompt/message shaping

- [ACP](https://github.com/batrachianai/toad/blob/HEAD/src/toad/acp/protocol.py): protocol layer · Agent Client Protocol API, messages, prompt, and transport model · `src/toad/acp/protocol.py`
- [Agents](https://github.com/batrachianai/toad/blob/HEAD/src/toad/data/agents/claude.com.toml): agent registry · Packaged agent definitions and schema normalization · `src/toad/data/agents/claude.com.toml`
- [Prompts](https://github.com/batrachianai/toad/blob/HEAD/src/toad/prompt/extract.py): prompt builder · Prompt composition, resources, extraction, and slash commands · `src/toad/prompt/extract.py`
- [Messages](https://github.com/batrachianai/toad/blob/HEAD/src/toad/messages.py): content model · Conversation, answers, and transportable message forms · `src/toad/messages.py`

### Local runtime

Shell execution, ANSI streaming, and filesystem navigation

- [Shell](https://github.com/batrachianai/toad/blob/HEAD/src/toad/shell.py): runtime · Embedded local shell execution and captured output · `src/toad/shell.py`
- [ANSI](https://github.com/batrachianai/toad/blob/HEAD/src/toad/ansi/_stream_parser.py): stream parser · ANSI parsing and streamed terminal rendering helpers · `src/toad/ansi/_stream_parser.py`
- [Paths](https://github.com/batrachianai/toad/blob/HEAD/src/toad/fuzzy.py): fs navigation · Fuzzy search, path completion, directory watching, and formatting · `src/toad/fuzzy.py`
- [File pickers](https://github.com/batrachianai/toad/blob/HEAD/src/toad/widgets/project_directory_tree.py): fs ui · Path search, directory tree, and project directory selection widgets · `src/toad/widgets/project_directory_tree.py`

### State

Sessions, settings, history, and persistence

- [Sessions](https://github.com/batrachianai/toad/blob/HEAD/src/toad/session_tracker.py): state model · Session tracking and resume support · `src/toad/session_tracker.py`
- [Storage](https://github.com/batrachianai/toad/blob/HEAD/src/toad/db.py): persistence · Database, history, and settings persistence · `src/toad/db.py`
- [Settings schema](https://github.com/batrachianai/toad/blob/HEAD/src/toad/settings_schema.py): schema · Structured settings and configuration model · `src/toad/settings_schema.py`

## Connections

- 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
