nanobrowser

Nanobrowser decomposes user natural language requests into structured task plans using a Planner agent, then executes those plans through a Navigator agent that performs granular browser actions. The system uses a message-passing architecture (chrome-extension/src/background/index.ts) where the background script routes commands between agents, maintains execution state, and coordinates action sequencing. The Planner generates step-by-step workflows while the Navigator translates those steps into concrete browser interactions, enabling complex multi-step automation without requiring users to write code.

Nanobrowser abstracts LLM provider differences through a factory pattern (createChatModel in chrome-extension/src/background/agent/helper.ts) that maps 11+ providers (OpenAI, Anthropic, Gemini, Ollama, Groq, Cerebras, Azure, OpenRouter, DeepSeek, Grok, Llama) to LangChain chat model implementations. Users configure providers and models via the Options page UI, which persists settings to the storage layer (packages/storage/lib/settings/llmProviders.ts). At runtime, the factory instantiates the correct LangChain ChatModel class with provider-specific parameters (API keys, endpoints, deployment names), enabling seamless provider switching without code changes.

Nanobrowser manages browser contexts and pages through Puppeteer, maintaining a reference to the current active page and browser instance. The system handles page lifecycle events (navigation, load, close) and maintains DOM snapshots for agent decision-making. The Browser Context and Page Management layer (referenced in Architecture Overview) abstracts Puppeteer's API, providing a simplified interface for agents to query page state, execute JavaScript, and interact with the DOM. This enables agents to understand the current page context before executing actions, reducing errors from stale DOM references.

The Executor (chrome-extension/src/background/agent/executor.ts) manages task execution lifecycle, maintaining state for in-progress tasks and coordinating between the Planner and Navigator agents. It tracks task progress, captures execution logs, and handles errors or task cancellation. The executor maintains a queue of pending actions and executes them sequentially, updating task state after each action. This enables users to monitor task progress through the UI and provides a foundation for resuming interrupted tasks. The executor also captures detailed logs of agent decisions and action results, enabling post-execution analysis and debugging.

The Options page (pages/options/src/components/ModelSettings.tsx) provides a user-friendly interface for configuring LLM providers, assigning models to agents, and setting domain firewall rules. The UI is built with React and communicates with the storage layer to persist settings. Users can add/remove providers, test API credentials, and preview available models for each provider. The Options page also includes language selection and other extension-wide settings. All configuration changes are immediately persisted to extension storage and take effect on the next task execution.

The Navigator agent executes browser actions (click, type, scroll, extract text) by translating natural language or planner directives into Puppeteer commands that interact with the live DOM. The system uses Puppeteer integration (chrome-extension/src/background/agent/agents/navigator.ts) with anti-detection measures to avoid triggering bot-detection systems on target websites. Actions are executed against the current browser context and page, with real-time DOM snapshots captured to inform subsequent action decisions. The action system maintains a registry of supported actions (click, fill form, navigate, extract data) that the Navigator can invoke with structured parameters.

Nanobrowser maintains a persistent chat history stored in the extension's local storage (packages/storage/lib/settings/types.ts) that records user messages, agent responses, and execution logs. The Side Panel Interface displays this history with a replay system that allows users to re-execute previous tasks or inspect what actions were taken. Users can bookmark favorite conversations or task templates, which are stored separately in the Favorites storage layer. The chat history system captures not just text but also metadata (timestamps, agent decisions, action sequences), enabling users to audit automation decisions and reuse successful workflows.

The Side Panel Interface includes a speech-to-text input system that converts user voice commands into text task descriptions, which are then processed by the Planner agent. The system uses the browser's Web Speech API to capture audio and transcribe it into natural language, which is passed to the LLM for task decomposition. This enables hands-free task specification — users can describe complex workflows verbally without typing, and the system converts speech into structured task plans.

Nanobrowser implements a firewall system (referenced in Storage and State Management) that restricts which domains the automation agents can access. Users can configure allowed/blocked domains in the Options page, and the background script enforces these restrictions before executing navigation or action commands. This prevents accidental or malicious automation from accessing sensitive sites (e.g., banking, email) without explicit user approval. The firewall operates at the action execution layer — blocked domains are rejected before Puppeteer commands are sent to the browser.

Nanobrowser allows users to assign different LLM models to different agents (Planner and Navigator) through the Model Settings interface (pages/options/src/components/ModelSettings.tsx). The agentModels storage (packages/storage/lib/settings/agentModels.ts) maintains a mapping of agent names to model configurations, enabling users to use a fast/cheap model for the Navigator (which makes many decisions) and a more capable model for the Planner (which requires complex reasoning). At runtime, the agent factory instantiates each agent with its assigned model, allowing fine-grained control over LLM resource allocation.

The background script (chrome-extension/src/background/index.ts) implements a message routing system that handles communication between the Side Panel UI, content scripts, and agent executors. It uses Chrome extension message passing APIs (chrome.runtime.onMessage, chrome.runtime.connect) to establish persistent ports for long-running tasks and route messages between components. The routing system maintains a registry of active ports and task executors, ensuring that responses from agents are delivered back to the correct UI component. This architecture enables asynchronous task execution — the UI can dispatch a task and continue responding to user input while agents work in the background.

Nanobrowser is organized as a TypeScript monorepo using pnpm workspaces, with separate packages for storage (packages/storage), shared utilities, and the main Chrome extension module (chrome-extension). The storage package provides a unified interface for persisting settings, chat history, and agent configurations. The extension module contains the background script, content scripts, UI components (Side Panel, Options page), and agent implementations. This modular structure enables code reuse across components and simplifies testing — storage logic can be tested independently of UI logic, and agents can be tested without the full extension context.

Nanobrowser includes an internationalization system that enables the UI (Side Panel, Options page) to be displayed in multiple languages. The i18n system uses language-specific resource files to provide translations for UI strings, and the extension detects the user's browser language to select the appropriate language. Users can also manually override the language in the Options page. This enables Nanobrowser to be accessible to non-English speakers without requiring separate builds or installations.