# suchi-bits/agent-browser architecture

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

- Interactive diagram: https://gitdiagram.com/suchi-bits/agent-browser
- Repository: https://github.com/suchi-bits/agent-browser

## Overview

agent-browser is a Rust browser-automation CLI for AI agents. Its principal workflow is command-line input → command parsing → daemon connection → browser control over CDP → structured output; README capabilities include interaction, snapshots, screenshots, chat, and runtime streaming. The repository also includes a dashboard, installation and diagnostics, and an evaluation runner. Some runtime wiring is unsampled, so those connections are omitted or marked unverified rather than inferred.

Main entry points: [`cli/src/main.rs`](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/main.rs) (CLI entry), [`evals/run.ts`](https://github.com/suchi-bits/agent-browser/blob/main/evals/run.ts) (Eval runner), [`cli/src/native/stream/mod.rs`](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/stream/mod.rs) (Runtime streaming), [`cli/src/native/actions.rs`](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/actions.rs) (Browser actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and setup"]
  node_entry["CLI entry<br/>[main.rs]"]
  node_parser["Command parser<br/>[commands.rs]"]
  node_flags["CLI options<br/>[flags.rs]"]
  node_output["Result formatting<br/>[output.rs]"]
  node_connection["Daemon connection<br/>[connection.rs]"]
  node_installer["Browser installer<br/>[install.rs]"]
  node_doctor["Diagnostics<br/>[mod.rs]"]
  node_chat["AI chat<br/>[chat.rs]"]
  node_skills["Agent skills<br/>[skills.rs]"]
end

subgraph group_runtime["Browser runtime"]
  node_daemon["Native daemon<br/>[daemon.rs]"]
  node_actions["Browser actions<br/>[actions.rs]"]
  node_state["Session state<br/>[state.rs]"]
  node_cdp["CDP transport<br/>[client.rs]"]
  node_discovery["Browser discovery<br/>[discovery.rs]"]
  node_chrome["Chrome control<br/>[chrome.rs]"]
  node_storage["Page storage<br/>[storage.rs]"]
end

subgraph group_stream["Streaming and dashboard"]
  node_streaming["Runtime streaming<br/>[mod.rs]"]
  node_stream_chat["Stream chat<br/>[chat.rs]"]
  node_stream_http["Stream HTTP<br/>[http.rs]"]
  node_stream_loop["CDP stream loop<br/>[cdp_loop.rs]"]
  node_dashboard["Dashboard UI<br/>[page.tsx]"]
end

subgraph group_eval["Evaluation"]
  node_eval_runner["Eval runner<br/>[run.ts]"]
  node_eval_claude["Claude provider<br/>[claude.ts]"]
  node_eval_codex["Codex provider<br/>[codex.ts]"]
  node_judge["Eval judge<br/>[judge.ts]"]
  node_reporter["Eval reporting<br/>[reporter.ts]"]
end

node_user(("Agent or user"))
node_browser["Chrome browser"]
node_model["AI model gateway"]

node_user -->|"runs commands"| node_entry
node_entry -->|"parses commands"| node_parser
node_entry -->|"sends commands"| node_connection
node_entry -->|"reads options"| node_flags
node_entry -.->|"formats results"| node_output
node_entry -.->|"installs browser"| node_installer
node_entry -.->|"runs diagnostics"| node_doctor
node_entry -.->|"starts chat"| node_chat
node_entry -.->|"loads skills"| node_skills
node_browser -->|"downloaded by"| node_installer
node_connection -.->|"connects to"| node_daemon
node_daemon -.->|"dispatches actions"| node_actions
node_actions -.->|"controls browser"| node_cdp
node_chrome -->|"discovers browsers"| node_discovery
node_chrome -.->|"uses transport"| node_cdp
node_actions -.->|"uses session state"| node_state
node_storage -->|"evaluates storage"| node_cdp
node_chat -->|"uses chat stream"| node_stream_chat
node_streaming -->|"starts stream loop"| node_stream_loop
node_streaming -->|"provides chat stream"| node_stream_chat
node_streaming -->|"provides HTTP"| node_stream_http
node_streaming -.->|"serves dashboard"| node_dashboard
node_user -.->|"runs evaluations"| node_eval_runner
node_eval_runner -->|"selects provider"| node_eval_claude
node_eval_runner -->|"selects provider"| node_eval_codex
node_eval_runner -->|"evaluates response"| node_judge
node_eval_runner -->|"reports results"| node_reporter
node_eval_claude -->|"calls gateway"| node_model
node_eval_codex -->|"calls gateway"| node_model

click node_entry "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/main.rs"
click node_parser "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/commands.rs"
click node_flags "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/flags.rs"
click node_output "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/output.rs"
click node_connection "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/connection.rs"
click node_installer "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/install.rs"
click node_doctor "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/doctor/mod.rs"
click node_chat "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/chat.rs"
click node_skills "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/skills.rs"
click node_daemon "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/daemon.rs"
click node_actions "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/actions.rs"
click node_state "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/state.rs"
click node_cdp "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/cdp/client.rs"
click node_discovery "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/cdp/discovery.rs"
click node_chrome "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/cdp/chrome.rs"
click node_storage "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/storage.rs"
click node_streaming "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/stream/mod.rs"
click node_stream_chat "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/stream/chat.rs"
click node_stream_http "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/stream/http.rs"
click node_stream_loop "https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/stream/cdp_loop.rs"
click node_dashboard "https://github.com/suchi-bits/agent-browser/blob/main/packages/dashboard/src/app/page.tsx"
click node_eval_runner "https://github.com/suchi-bits/agent-browser/blob/main/evals/run.ts"
click node_eval_claude "https://github.com/suchi-bits/agent-browser/blob/main/evals/lib/claude.ts"
click node_eval_codex "https://github.com/suchi-bits/agent-browser/blob/main/evals/lib/codex.ts"
click node_judge "https://github.com/suchi-bits/agent-browser/blob/main/evals/lib/judge.ts"
click node_reporter "https://github.com/suchi-bits/agent-browser/blob/main/evals/lib/reporter.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_entry,node_parser,node_flags,node_output,node_connection,node_installer,node_doctor,node_chat,node_skills,node_user,node_browser toneBlue
class node_daemon,node_actions,node_state,node_cdp,node_discovery,node_chrome,node_storage toneAmber
class node_streaming,node_stream_chat,node_stream_http,node_stream_loop,node_dashboard toneMint
class node_eval_runner,node_eval_claude,node_eval_codex,node_judge,node_reporter toneRose
class node_model toneIndigo
```

## Components

### CLI and setup

- [CLI entry](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/main.rs): `cli/src/main.rs`
- [Command parser](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/commands.rs): `cli/src/commands.rs`
- [CLI options](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/flags.rs): `cli/src/flags.rs`
- [Result formatting](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/output.rs): `cli/src/output.rs`
- [Daemon connection](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/connection.rs): `cli/src/connection.rs`
- [Browser installer](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/install.rs): `cli/src/install.rs`
- [Diagnostics](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/doctor/mod.rs): `cli/src/doctor/mod.rs`
- [AI chat](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/chat.rs): `cli/src/chat.rs`
- [Agent skills](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/skills.rs): `cli/src/skills.rs`

### Browser runtime

- [Native daemon](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/daemon.rs): `cli/src/native/daemon.rs`
- [Browser actions](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/actions.rs): `cli/src/native/actions.rs`
- [Session state](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/state.rs): `cli/src/native/state.rs`
- [CDP transport](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/cdp/client.rs): `cli/src/native/cdp/client.rs`
- [Browser discovery](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/cdp/discovery.rs): `cli/src/native/cdp/discovery.rs`
- [Chrome control](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/cdp/chrome.rs): `cli/src/native/cdp/chrome.rs`
- [Page storage](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/storage.rs): `cli/src/native/storage.rs`

### Streaming and dashboard

- [Runtime streaming](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/stream/mod.rs): `cli/src/native/stream/mod.rs`
- [Stream chat](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/stream/chat.rs): `cli/src/native/stream/chat.rs`
- [Stream HTTP](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/stream/http.rs): `cli/src/native/stream/http.rs`
- [CDP stream loop](https://github.com/suchi-bits/agent-browser/blob/main/cli/src/native/stream/cdp_loop.rs): `cli/src/native/stream/cdp_loop.rs`
- [Dashboard UI](https://github.com/suchi-bits/agent-browser/blob/main/packages/dashboard/src/app/page.tsx): `packages/dashboard/src/app/page.tsx`

### Evaluation

- [Eval runner](https://github.com/suchi-bits/agent-browser/blob/main/evals/run.ts): `evals/run.ts`
- [Claude provider](https://github.com/suchi-bits/agent-browser/blob/main/evals/lib/claude.ts): `evals/lib/claude.ts`
- [Codex provider](https://github.com/suchi-bits/agent-browser/blob/main/evals/lib/codex.ts): `evals/lib/codex.ts`
- [Eval judge](https://github.com/suchi-bits/agent-browser/blob/main/evals/lib/judge.ts): `evals/lib/judge.ts`
- [Eval reporting](https://github.com/suchi-bits/agent-browser/blob/main/evals/lib/reporter.ts): `evals/lib/reporter.ts`

### Other components

- **Agent or user**
- **Chrome browser**
- **AI model gateway**

## Connections

- Agent or user → CLI entry: runs commands (evidence: `README.md`)
- CLI entry → Command parser: parses commands (evidence: `cli/src/main.rs`)
- CLI entry → Daemon connection: sends commands (evidence: `cli/src/main.rs`)
- CLI entry → CLI options: reads options (evidence: `cli/src/main.rs`)
- CLI entry → Result formatting: formats results (evidence: `cli/src/main.rs`)
- CLI entry → Browser installer: installs browser (evidence: `cli/src/main.rs`)
- CLI entry → Diagnostics: runs diagnostics (evidence: `cli/src/main.rs`)
- CLI entry → AI chat: starts chat (evidence: `cli/src/main.rs`)
- CLI entry → Agent skills: loads skills (evidence: `cli/src/main.rs`)
- Chrome browser → Browser installer: downloaded by (evidence: `README.md`)
- Daemon connection → Native daemon: connects to
- Native daemon → Browser actions: dispatches actions
- Browser actions → CDP transport: controls browser
- Chrome control → Browser discovery: discovers browsers (evidence: `cli/src/native/cdp/chrome.rs`)
- Chrome control → CDP transport: uses transport
- Browser actions → Session state: uses session state
- Page storage → CDP transport: evaluates storage (evidence: `cli/src/native/storage.rs`)
- AI chat → Stream chat: uses chat stream (evidence: `cli/src/chat.rs`)
- Runtime streaming → CDP stream loop: starts stream loop (evidence: `cli/src/native/stream/mod.rs`)
- Runtime streaming → Stream chat: provides chat stream (evidence: `cli/src/native/stream/mod.rs`)
- Runtime streaming → Stream HTTP: provides HTTP (evidence: `cli/src/native/stream/mod.rs`)
- Runtime streaming → Dashboard UI: serves dashboard
- Agent or user → Eval runner: runs evaluations
- Eval runner → Claude provider: selects provider (evidence: `evals/run.ts`)
- Eval runner → Codex provider: selects provider (evidence: `evals/run.ts`)
- Eval runner → Eval judge: evaluates response (evidence: `evals/run.ts`)
- Eval runner → Eval reporting: reports results (evidence: `evals/run.ts`)
- Claude provider → AI model gateway: calls gateway (evidence: `evals/lib/claude.ts`)
- Codex provider → AI model gateway: calls gateway (evidence: `evals/lib/codex.ts`)
