Directory Structure
Relevant source files
The following files were used as context for generating this wiki page:
The project directory structure is organized to facilitate an AI-powered browser automation platform with a Gradio-based web interface. It separates core logic, agent customizations, utility functions, and deployment configurations into distinct modules. This organization allows the system to support multiple LLM providers, persistent browser sessions, and advanced "Deep Research" capabilities.
Core Application Components
The root directory contains the entry point for the web application and deployment orchestration files.
Entry Points and Deployment
webui.py: The main entry point that launches the Gradio user interface and manages the global state of the browser and agents.docker-compose.yml: Defines the containerized environment, including environment variables for API keys, display settings, and VNC access.supervisord.conf: Manages multiple background processes within the Docker container, such as Xvfb (virtual frame buffer), noVNC, and the persistent browser instance.
Sources: webui.py:46-52, docker-compose.yml:1-35, supervisord.conf:1-10
The diagram above illustrates how the core configuration files manage the application's lifecycle and background services.
Source Code Organization (src/)
The src/ directory contains the specialized logic for agent behavior, browser interaction, and general utilities.
Agent Module (src/agent/)
This module extends the base browser-use agent capabilities.
custom_agent.py: ImplementsCustomAgent, which extends the standard agent to handle DeepSeek-R1 logic, specialized planning, and custom step information tracking.custom_prompts.py: DefinesCustomSystemPromptandCustomAgentMessagePromptto structure JSON responses and provide visual context to the LLM.custom_views.py: Contains data structures likeCustomAgentStepInfoandCustomAgentOutputfor managing agent state and memory.
Sources: src/agent/custom_agent.py:49-140, src/agent/custom_prompts.py:15-50, src/agent/custom_views.py:7-20
Utilities Module (src/utils/)
Provides shared logic for LLM management, file operations, and complex research workflows.
utils.py: Contains theget_llm_modelfactory and helper functions for encoding images and capturing screenshots.deep_research.py: Orchestrates the "Deep Research" feature, which involves iterative searching, content extraction via Jina Reader, and final report generation.default_config_settings.py: Manages the application's configuration state, allowing settings to be saved and loaded from.pklfiles.
Sources: src/utils/utils.py:31-130, src/utils/deep_research.py:36-150, src/utils/default_config_settings.py:8-35
Asset and Temporary Storage
The system utilizes specific directories for managing output and runtime data.
| Directory | Purpose | Managed By |
|---|---|---|
./tmp/record_videos | Stores .mp4 and .webm recordings of browser sessions. | webui.py, src/utils/default_config_settings.py |
./tmp/traces | Stores Playwright trace files for debugging agent actions. | webui.py, test_browser_use.py |
./tmp/agent_history | Saves JSON-formatted logs of agent steps and final results. | webui.py, src/agent/custom_agent.py |
./tmp/deep_research/ | Root for iterative research data, including raw results and final markdown reports. | src/utils/deep_research.py |
./assets/ | Static assets like logos and example images for the UI and documentation. | README.md, tests/test_llm_api.py |
Sources: webui.py:93-100, src/utils/deep_research.py:38-41, src/utils/default_config_settings.py:27-32, src/utils/utils.py:228-235
Component Relationship Diagram
This diagram demonstrates the flow of control from the Gradio UI through the logic modules down to utility functions and local storage.
Sources: webui.py:126-150, src/utils/deep_research.py:145-160, src/agent/custom_agent.py:165-180
Conclusion
The project's directory structure is highly modular, separating deployment configuration from the core AI logic. By centralizing agent customizations in src/agent and general utilities in src/utils, the architecture supports complex features like multi-iteration research and persistent browser sessions while remaining deployable via standard containerization tools.
Sources: README.md, supervisord.conf