# adityabelgaonkar05/browsy architecture

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

- Interactive diagram: https://gitdiagram.com/adityabelgaonkar05/browsy
- Repository: https://github.com/adityabelgaonkar05/browsy

## Overview

Browsy combines a Chrome sidebar assistant with local browser control shared by terminal MCP agents. Sidebar chat loads local settings/history, sends turns through context management and a streaming provider, and routes requested browser tools through the extension background to Chrome. Terminal agents use MCP tools and a local native-messaging/IPC bridge to reach the same extension browser tools. The graph preserves setup/diagnostics and bridge transport layers; unsampled MCP and UI internals are represented at their exact enclosing paths, with documented links cited to the README.

Main entry points: [`packages/native-bridge/src/host.ts`](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/native-bridge/src/host.ts) (Native host), [`apps/extension/chat/engine.ts`](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/chat/engine.ts) (Turn engine), [`apps/extension/browser-tools/dispatcher.ts`](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/browser-tools/dispatcher.ts) (Tool dispatcher), [`apps/extension/sidebar/chat.tsx`](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/sidebar/chat.tsx) (Chat sidebar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sidebar["Sidebar chat"]
  node_sidebar_ui["Chat sidebar<br/>[chat.tsx]"]
  node_chat_state[("Chat state<br/>[storage.ts]")]
  node_chat_engine["Turn engine<br/>[engine.ts]"]
  node_context["Context manager<br/>[context.ts]"]
  node_provider["AI providers<br/>[provider.ts]"]
end

subgraph group_browser["Browser control"]
  node_background["Extension background<br/>[index.ts]"]
  node_native_connection["Native connection"]
  node_dispatcher["Tool dispatcher<br/>[dispatcher.ts]"]
  node_controller["Chrome controller"]
  node_shared_tools["Browser tool contracts<br/>[browser-tools.ts]"]
end

subgraph group_terminal["Terminal agent access"]
  node_mcp["MCP server<br/>[index.ts]"]
  node_mcp_tools["MCP tool definitions<br/>[tools.ts]"]
  node_cli["CLI commands<br/>[index.ts]"]
  node_agent_setup["Agent setup<br/>[agents.ts]"]
  node_installation["Bridge installation<br/>[installation.ts]"]
end

subgraph group_bridge["Local bridge"]
  node_bridge_client["IPC client<br/>[client.ts]"]
  node_bridge_host["Native host<br/>[host.ts]"]
  node_framing["Frame codec<br/>[framing.ts]"]
  node_windows_transport["Windows pipe relay<br/>[windows.ts]"]
end

node_user(("Chrome user"))
node_ai_service(("AI endpoint"))
node_chrome(("Chrome tabs"))
node_agent(("Terminal agent"))

node_user -->|"asks"| node_sidebar_ui
node_sidebar_ui -->|"loads and saves"| node_chat_state
node_sidebar_ui -->|"runs turn"| node_chat_engine
node_chat_engine -->|"builds context"| node_context
node_chat_engine -->|"streams completion"| node_provider
node_provider -->|"sends requests"| node_ai_service
node_chat_engine -->|"requests tools"| node_background
node_background -->|"dispatches tools"| node_dispatcher
node_dispatcher -->|"executes actions"| node_controller
node_controller -->|"controls tabs"| node_chrome
node_dispatcher -->|"uses contracts"| node_shared_tools
node_agent -->|"invokes tools"| node_mcp
node_mcp -->|"uses definitions"| node_mcp_tools
node_mcp -->|"sends requests"| node_bridge_client
node_bridge_client -->|"uses local IPC"| node_bridge_host
node_bridge_host -->|"forwards browser calls"| node_native_connection
node_native_connection -->|"routes browser tools"| node_dispatcher
node_bridge_client -->|"encodes frames"| node_framing
node_bridge_host -->|"writes frames"| node_framing
node_bridge_host -->|"uses on Windows"| node_windows_transport
node_agent -->|"runs setup"| node_cli
node_cli -->|"configures agent"| node_agent_setup
node_cli -->|"installs bridge"| node_installation
node_installation -->|"registers host"| node_bridge_host

click node_sidebar_ui "https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/sidebar/chat.tsx"
click node_chat_state "https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/chat/storage.ts"
click node_chat_engine "https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/chat/engine.ts"
click node_context "https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/chat/context.ts"
click node_provider "https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/providers/provider.ts"
click node_background "https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/background/index.ts"
click node_native_connection "https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/background/native-connection.ts"
click node_dispatcher "https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/browser-tools/dispatcher.ts"
click node_controller "https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/browser-tools/chrome-controller.ts"
click node_shared_tools "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/shared/src/browser-tools.ts"
click node_mcp "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/mcp/src/index.ts"
click node_mcp_tools "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/mcp/src/tools.ts"
click node_cli "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/cli/src/index.ts"
click node_agent_setup "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/cli/src/agents.ts"
click node_installation "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/cli/src/installation.ts"
click node_bridge_client "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/native-bridge/src/client.ts"
click node_bridge_host "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/native-bridge/src/host.ts"
click node_framing "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/native-bridge/src/framing.ts"
click node_windows_transport "https://github.com/adityabelgaonkar05/browsy/blob/main/packages/native-bridge/src/windows.ts"

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 node_sidebar_ui,node_chat_state,node_chat_engine,node_context,node_provider,node_user toneBlue
class node_background,node_native_connection,node_dispatcher,node_controller,node_shared_tools toneAmber
class node_mcp,node_mcp_tools,node_cli,node_agent_setup,node_installation toneMint
class node_bridge_client,node_bridge_host,node_framing,node_windows_transport toneRose
class node_ai_service,node_chrome,node_agent toneIndigo
```

## Components

### Sidebar chat

- [Chat sidebar](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/sidebar/chat.tsx): `apps/extension/sidebar/chat.tsx`
- [Chat state](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/chat/storage.ts): `apps/extension/chat/storage.ts`
- [Turn engine](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/chat/engine.ts): `apps/extension/chat/engine.ts`
- [Context manager](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/chat/context.ts): `apps/extension/chat/context.ts`
- [AI providers](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/providers/provider.ts): `apps/extension/providers/provider.ts`

### Browser control

- [Extension background](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/background/index.ts): `apps/extension/background/index.ts`
- [Native connection](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/background/native-connection.ts): `apps/extension/background/native-connection.ts`
- [Tool dispatcher](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/browser-tools/dispatcher.ts): `apps/extension/browser-tools/dispatcher.ts`
- [Chrome controller](https://github.com/adityabelgaonkar05/browsy/blob/main/apps/extension/browser-tools/chrome-controller.ts): `apps/extension/browser-tools/chrome-controller.ts`
- [Browser tool contracts](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/shared/src/browser-tools.ts): `packages/shared/src/browser-tools.ts`

### Terminal agent access

- [MCP server](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/mcp/src/index.ts): `packages/mcp/src/index.ts`
- [MCP tool definitions](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/mcp/src/tools.ts): `packages/mcp/src/tools.ts`
- [CLI commands](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/cli/src/index.ts): `packages/cli/src/index.ts`
- [Agent setup](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/cli/src/agents.ts): `packages/cli/src/agents.ts`
- [Bridge installation](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/cli/src/installation.ts): `packages/cli/src/installation.ts`

### Local bridge

- [IPC client](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/native-bridge/src/client.ts): `packages/native-bridge/src/client.ts`
- [Native host](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/native-bridge/src/host.ts): `packages/native-bridge/src/host.ts`
- [Frame codec](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/native-bridge/src/framing.ts): `packages/native-bridge/src/framing.ts`
- [Windows pipe relay](https://github.com/adityabelgaonkar05/browsy/blob/main/packages/native-bridge/src/windows.ts): `packages/native-bridge/src/windows.ts`

### Other components

- **Chrome user**
- **AI endpoint**
- **Chrome tabs**
- **Terminal agent**

## Connections

- Chrome user → Chat sidebar: asks
- Chat sidebar → Chat state: loads and saves (evidence: `apps/extension/sidebar/chat.tsx`)
- Chat sidebar → Turn engine: runs turn (evidence: `apps/extension/sidebar/chat.tsx`)
- Turn engine → Context manager: builds context (evidence: `apps/extension/chat/engine.ts`)
- Turn engine → AI providers: streams completion (evidence: `apps/extension/chat/engine.ts`)
- AI providers → AI endpoint: sends requests
- Turn engine → Extension background: requests tools
- Extension background → Tool dispatcher: dispatches tools (evidence: `apps/extension/background/index.ts`)
- Tool dispatcher → Chrome controller: executes actions (evidence: `apps/extension/background/index.ts`)
- Chrome controller → Chrome tabs: controls tabs
- Tool dispatcher → Browser tool contracts: uses contracts (evidence: `apps/extension/browser-tools/dispatcher.ts`)
- Terminal agent → MCP server: invokes tools
- MCP server → MCP tool definitions: uses definitions (evidence: `packages/mcp/src/index.ts`)
- MCP server → IPC client: sends requests (evidence: `packages/mcp/src/index.ts`)
- IPC client → Native host: uses local IPC
- Native host → Native connection: forwards browser calls
- Native connection → Tool dispatcher: routes browser tools (evidence: `apps/extension/background/native-connection.ts`)
- IPC client → Frame codec: encodes frames (evidence: `packages/native-bridge/src/client.ts`)
- Native host → Frame codec: writes frames (evidence: `packages/native-bridge/src/host.ts`)
- Native host → Windows pipe relay: uses on Windows (evidence: `packages/native-bridge/src/host.ts`)
- Terminal agent → CLI commands: runs setup
- CLI commands → Agent setup: configures agent (evidence: `packages/cli/src/index.ts`)
- CLI commands → Bridge installation: installs bridge (evidence: `packages/cli/src/index.ts`)
- Bridge installation → Native host: registers host (evidence: `packages/cli/src/installation.ts`)
