# unbrowse-ai/unbrowse architecture

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

- Interactive diagram: https://gitdiagram.com/unbrowse-ai/unbrowse
- Repository: https://github.com/unbrowse-ai/unbrowse

## Overview

Unbrowse is an open-source client for a hosted website-capability service. Its main workflow is to discover a capability, run it, and wait for a verified result; when no capability matches, users can learn one from recordings or through the hosted agent workflow. The CLI and SDK expose these operations, while the repository also contains framework and editor integrations. Edges reflect README statements and shown source references; several integration internals were not sampled, so their detailed call paths are not expanded.

Main entry points: [`packages/cli/src/cli.ts`](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/cli.ts) (CLI commands), [`packages/sdk/src/client.ts`](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/client.ts) (REST client), [`packages/cli/src/cookies.ts`](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/cookies.ts) (Saved logins), [`plugins/dify/unbrowse_client.py`](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/dify/unbrowse_client.py) (Dify tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli["CLI commands<br/>[cli.ts]"]
  node_mcp_proxy["Local MCP proxy<br/>[mcp-proxy.ts]"]
end

subgraph group_sdk["SDK workflow"]
  node_sdk_client["REST client<br/>[client.ts]"]
  node_sdk_mcp["MCP client<br/>[mcp.ts]"]
  node_capabilities["Discover and registry<br/>[client.ts]"]
  node_run["Run and resume<br/>[client.ts]"]
  node_learning["Learn from recordings<br/>[client.ts]"]
end

subgraph group_local["Local credentials"]
  node_auth["OAuth and keys<br/>[auth.ts]"]
  node_cookie["Saved logins<br/>[cookies.ts]"]
  node_cookie_daemon["Cookie daemon<br/>[cookie-daemon.ts]"]
  node_sqlite[("Cookie database<br/>[sqlite.ts]")]
end

subgraph group_integrations["Agent integrations"]
  node_dify["Dify tools<br/>[unbrowse_client.py]"]
  node_eliza_client["ElizaOS MCP client<br/>[client.ts]"]
  node_eliza_ops["ElizaOS actions<br/>[unbrowse.ts]"]
  node_hermes["Hermes MCP client<br/>[client.py]"]
  node_langchain["LangChain tools<br/>[tools.py]"]
  node_langchain_client["LangChain MCP client<br/>[_client.py]"]
  node_llama_tools["LlamaIndex tools<br/>[base.py]"]
  node_llama_client["LlamaIndex MCP client<br/>[_client.py]"]
  node_n8n["n8n node<br/>[Unbrowse.node.ts]"]
  node_openclaw["OpenClaw plugin<br/>[plugin.ts]"]
  node_raycast["Raycast tools<br/>[unbrowse.ts]"]
  node_zed["Zed MCP server"]
end

node_user(("User or agent"))
node_hosted{{"Hosted Unbrowse"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"authenticates"| node_auth
node_cli -->|"calls"| node_sdk_client
node_cli -->|"starts"| node_mcp_proxy
node_cli -->|"manages logins"| node_cookie
node_cookie -->|"stores cookies"| node_sqlite
node_cookie_daemon -->|"uses"| node_cookie
node_sdk_client -->|"sends REST requests"| node_hosted
node_sdk_mcp -->|"calls hosted MCP"| node_hosted
node_sdk_client -->|"searches"| node_capabilities
node_sdk_client -->|"starts and resumes"| node_run
node_sdk_client -->|"fetches learned assets"| node_learning
node_user -->|"uses tools"| node_dify
node_dify -->|"calls MCP"| node_hosted
node_eliza_client -->|"calls MCP"| node_hosted
node_eliza_ops -->|"calls tools"| node_eliza_client
node_hermes -->|"calls MCP"| node_hosted
node_langchain -->|"uses"| node_langchain_client
node_langchain_client -->|"calls MCP"| node_hosted
node_llama_tools -->|"uses"| node_llama_client
node_llama_client -->|"calls MCP"| node_hosted
node_n8n -.->|"integrates Unbrowse"| node_hosted
node_openclaw -->|"calls hosted MCP"| node_hosted
node_raycast -->|"calls MCP"| node_hosted
node_zed -.->|"integrates MCP"| node_hosted

click node_cli "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/cli.ts"
click node_auth "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/auth.ts"
click node_cookie "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/cookies.ts"
click node_cookie_daemon "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/cookie-daemon.ts"
click node_sqlite "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/sqlite.ts"
click node_mcp_proxy "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/mcp-proxy.ts"
click node_sdk_client "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/client.ts"
click node_sdk_mcp "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/mcp.ts"
click node_capabilities "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/client.ts"
click node_run "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/client.ts"
click node_learning "https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/client.ts"
click node_dify "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/dify/unbrowse_client.py"
click node_eliza_client "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/elizaos/src/client.ts"
click node_eliza_ops "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/elizaos/src/unbrowse.ts"
click node_hermes "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/hermes/client.py"
click node_langchain "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/langchain/langchain_unbrowse/tools.py"
click node_langchain_client "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/langchain/langchain_unbrowse/_client.py"
click node_llama_tools "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/llamaindex/llama_index/tools/unbrowse/base.py"
click node_llama_client "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/llamaindex/llama_index/tools/unbrowse/_client.py"
click node_n8n "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/n8n/nodes/Unbrowse/Unbrowse.node.ts"
click node_openclaw "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/openclaw/src/plugin.ts"
click node_raycast "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/raycast/src/lib/unbrowse.ts"
click node_zed "https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/zed/src/mcp_server_unbrowse.rs"

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_cli,node_mcp_proxy,node_user toneBlue
class node_sdk_client,node_sdk_mcp,node_capabilities,node_run,node_learning toneAmber
class node_auth,node_cookie,node_cookie_daemon,node_sqlite toneMint
class node_dify,node_eliza_client,node_eliza_ops,node_hermes,node_langchain,node_langchain_client,node_llama_tools,node_llama_client,node_n8n,node_openclaw,node_raycast,node_zed toneRose
class node_hosted toneIndigo
```

## Components

### CLI

- [CLI commands](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/cli.ts): `packages/cli/src/cli.ts`
- [Local MCP proxy](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/mcp-proxy.ts): `packages/cli/src/mcp-proxy.ts`

### SDK workflow

- [REST client](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`
- [MCP client](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/mcp.ts): `packages/sdk/src/mcp.ts`
- [Discover and registry](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`
- [Run and resume](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`
- [Learn from recordings](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`

### Local credentials

- [OAuth and keys](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/auth.ts): `packages/cli/src/auth.ts`
- [Saved logins](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/cookies.ts): `packages/cli/src/cookies.ts`
- [Cookie daemon](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/cookie-daemon.ts): `packages/cli/src/cookie-daemon.ts`
- [Cookie database](https://github.com/unbrowse-ai/unbrowse/blob/main/packages/cli/src/sqlite.ts): `packages/cli/src/sqlite.ts`

### Agent integrations

- [Dify tools](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/dify/unbrowse_client.py): `plugins/dify/unbrowse_client.py`
- [ElizaOS MCP client](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/elizaos/src/client.ts): `plugins/elizaos/src/client.ts`
- [ElizaOS actions](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/elizaos/src/unbrowse.ts): `plugins/elizaos/src/unbrowse.ts`
- [Hermes MCP client](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/hermes/client.py): `plugins/hermes/client.py`
- [LangChain tools](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/langchain/langchain_unbrowse/tools.py): `plugins/langchain/langchain_unbrowse/tools.py`
- [LangChain MCP client](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/langchain/langchain_unbrowse/_client.py): `plugins/langchain/langchain_unbrowse/_client.py`
- [LlamaIndex tools](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/llamaindex/llama_index/tools/unbrowse/base.py): `plugins/llamaindex/llama_index/tools/unbrowse/base.py`
- [LlamaIndex MCP client](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/llamaindex/llama_index/tools/unbrowse/_client.py): `plugins/llamaindex/llama_index/tools/unbrowse/_client.py`
- [n8n node](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/n8n/nodes/Unbrowse/Unbrowse.node.ts): `plugins/n8n/nodes/Unbrowse/Unbrowse.node.ts`
- [OpenClaw plugin](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/openclaw/src/plugin.ts): `plugins/openclaw/src/plugin.ts`
- [Raycast tools](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/raycast/src/lib/unbrowse.ts): `plugins/raycast/src/lib/unbrowse.ts`
- [Zed MCP server](https://github.com/unbrowse-ai/unbrowse/blob/main/plugins/zed/src/mcp_server_unbrowse.rs): `plugins/zed/src/mcp_server_unbrowse.rs`

### Other components

- **User or agent**
- **Hosted Unbrowse**

## Connections

- User or agent → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → OAuth and keys: authenticates (evidence: `packages/cli/src/cli.ts`)
- CLI commands → REST client: calls (evidence: `packages/cli/src/cli.ts`)
- CLI commands → Local MCP proxy: starts (evidence: `packages/cli/src/cli.ts`)
- CLI commands → Saved logins: manages logins (evidence: `packages/cli/src/cli.ts`)
- Saved logins → Cookie database: stores cookies (evidence: `packages/cli/src/cookies.ts`)
- Cookie daemon → Saved logins: uses (evidence: `packages/cli/src/cookie-daemon.ts`)
- REST client → Hosted Unbrowse: sends REST requests (evidence: `packages/sdk/src/client.ts`)
- MCP client → Hosted Unbrowse: calls hosted MCP (evidence: `packages/sdk/src/mcp.ts`)
- REST client → Discover and registry: searches (evidence: `packages/sdk/src/client.ts`)
- REST client → Run and resume: starts and resumes (evidence: `packages/sdk/src/client.ts`)
- REST client → Learn from recordings: fetches learned assets (evidence: `packages/sdk/src/client.ts`)
- User or agent → Dify tools: uses tools (evidence: `README.md`)
- Dify tools → Hosted Unbrowse: calls MCP (evidence: `plugins/dify/unbrowse_client.py`)
- ElizaOS MCP client → Hosted Unbrowse: calls MCP (evidence: `plugins/elizaos/src/client.ts`)
- ElizaOS actions → ElizaOS MCP client: calls tools (evidence: `plugins/elizaos/src/unbrowse.ts`)
- Hermes MCP client → Hosted Unbrowse: calls MCP (evidence: `plugins/hermes/client.py`)
- LangChain tools → LangChain MCP client: uses (evidence: `plugins/langchain/langchain_unbrowse/tools.py`)
- LangChain MCP client → Hosted Unbrowse: calls MCP (evidence: `plugins/langchain/langchain_unbrowse/_client.py`)
- LlamaIndex tools → LlamaIndex MCP client: uses (evidence: `plugins/llamaindex/llama_index/tools/unbrowse/base.py`)
- LlamaIndex MCP client → Hosted Unbrowse: calls MCP (evidence: `plugins/llamaindex/llama_index/tools/unbrowse/_client.py`)
- n8n node → Hosted Unbrowse: integrates Unbrowse (evidence: `README.md`)
- OpenClaw plugin → Hosted Unbrowse: calls hosted MCP (evidence: `plugins/openclaw/src/plugin.ts`)
- Raycast tools → Hosted Unbrowse: calls MCP (evidence: `plugins/raycast/src/lib/unbrowse.ts`)
- Zed MCP server → Hosted Unbrowse: integrates MCP (evidence: `README.md`)
