How parsaghaffari/browserbee works
Project type and purpose
• BrowserBee is an open-source Chrome extension that embeds a lightweight AI agent in the browser.
• Its purpose is to let end users control the browser via natural-language instructions, using an LLM (Anthropic, OpenAI, Gemini, Ollama) for planning and Playwright (via playwright-crx) under the hood for browser automation.
File structure
• Top-level:
• public/ – static assets & extension entry pages (manifest.json, options.html, sidepanel.html)
• src/ – all extension source code, organized by feature/context
• docs/ – Docusaurus-based documentation site
• .github/, README.md, ROADMAP.md, etc. – project governance and CI
• Under src/:
• src/background/ – background script (Chrome extension background context)
• src/agent/ – the core AI agent modules (ExecutionEngine, MemoryManager, PromptManager, ToolManager, etc.)
• src/models/providers/ – adapters to various LLM APIs
• src/sidepanel/ + src/options/ – React-based UI for the side panel and options page
• src/tracking/ – local memory & token tracking (defaultMemories.json, memoryService.ts, tokenTrackingService.ts)
• src/types/ – TypeScript declarations (including Playwright CRX types)
README for additional insights
• Confirms:
• Entirely in-browser except outbound LLM API calls
• Uses Playwright-CRX for browser automation
• Tracks token usage and price
• Stores “memories” in local storage/IndexedDB for future reuse
• Requests user approval for sensitive actions
Main components
a. User Interface Context (Chrome Extension UI)
• Side Panel (React components under src/sidepanel)
• Options Page (src/options)
• Communication hook: useChromeMessaging (chrome.runtime.sendMessage / onMessage)
b. Background Context (src/background)
• messageHandler & agentController
• streamingManager (for LLM response streaming)
• configManager (loads/saves user API keys)
• tabManager (keeps track of open tabs & reattachment logic)
c. Agent Core (src/agent)
• ExecutionEngine (dispatches prompts → LLM → tool calls)
• PromptManager (formats instructions + memory)
• MemoryManager (save, lookup, delete memories via memoryService)
• TokenManager (tracks tokens via tokenTrackingService)
• ToolManager (orchestrates calls to browser_navigate, browser_click, etc.)
• ErrorHandler / approvalManager
d. Tool Layer
• Playwright-CRX adapter (in browser) for CDP commands
• Tool modules: navigationTools, interactionTools, mouseTools, keyboardTools, observationTools, tabTools, memoryTools
e. Model Providers (src/models/providers)
• openai.ts, anthropic.ts, gemini.ts, ollama.ts + factory.ts
• External HTTP APIs or local RPC (for Ollama)
f. Storage & Tracking (src/tracking)
• defaultMemories.json, memoryService.ts (IndexedDB or localStorage)
• tokenTrackingService (metrics & cost computation)
Relationships and data flows
• User types instruction → SidePanel UI
• UI sends a message to Background → messageHandler routes to agentController
• Controller invokes ExecutionEngine
• ExecutionEngine:
1. PromptManager builds a prompt (including lookupMemories)
2. Sends to ModelProvider → receives response stream → streamingManager emits tokens back to UI
3. Parses LLM response into tool calls → ToolManager invokes Playwright-CRX methods via CDP
4. Observes results via observation tools → loops or finalizes
5. MemoryManager may save a new memory after “reflect and learn”
6. TokenManager logs usage
• ConfigManager provides API keys/config to ModelProviders
• TabManager and PageContextManager handle which tab the agent is attached to
Architectural patterns and principles
• Extension multi-context pattern (UI <→> background scripts)
• Modular “agent core” separated from UI, tools, and model adapters
• Factory pattern for LLM provider selection
• Observer pattern for streaming token events
• Command pattern for each browser tool call
Detail
• Major modules in src/agent, src/background, src/models/providers, src/sidepanel
• Flows: User → UI → Background → LLM → Tools → Browser → UI
• Don’t omit the memory lookup/save cycle nor token tracking