> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Extension Architecture

> How the Chrome Extension communicates with the Python CLI for browser automation

# Browser Extension Architecture

The PraisonAI browser automation uses a 3-layer architecture for AI-powered browser control.

## Communication Flow

```
Python CLI ──► Bridge Server ◄──► Chrome Extension
     │              │                    │
     │              │                    │
 start_session  observation/action      CDP
```

1. **CLI** sends `start_session` with goal
2. **Bridge Server** routes to **Extension**
3. **Extension** captures page state (screenshot, elements)
4. **Extension** sends `observation` to **Bridge**
5. **Bridge** processes with BrowserAgent (LLM decision)
6. **Bridge** returns `action` to **Extension**
7. **Extension** executes action via CDP
8. Loop continues until goal complete

## Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                     Python CLI                               │
│  praisonai browser launch "goal"                            │
└─────────────────────┬───────────────────────────────────────┘
                      │ WebSocket
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                  Bridge Server (FastAPI)                     │
│  - Routes messages CLI ↔ Extension                          │
│  - Hosts BrowserAgent for LLM decisions                     │
│  - WebSocket endpoint: ws://localhost:8765/ws               │
└─────────────────────┬───────────────────────────────────────┘
                      │ WebSocket
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                Chrome Extension                              │
│  - Background service worker                                │
│  - CDP debugger for page control                            │
│  - Captures screenshots, clickable elements                 │
│  - Executes click/type/scroll actions                       │
└─────────────────────────────────────────────────────────────┘
```

## Running the Browser Agent

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple usage (auto-selects engine)
praisonai browser launch "go to google and search for AI"

# Force extension mode
praisonai browser launch "go to google" --engine extension

# Force CDP mode (no extension required)
praisonai browser launch "go to google" --engine cdp

# Debug mode
praisonai browser launch "test" --debug
```

## Message Types

| Type            | Direction     | Description            |
| --------------- | ------------- | ---------------------- |
| `start_session` | CLI → Server  | Start new automation   |
| `observation`   | Ext → Server  | Page state snapshot    |
| `action`        | Server → Ext  | Next action to execute |
| `status`        | Server → Both | Session status updates |
| `stop_session`  | Any → Server  | End session            |

## Troubleshooting

### Extension Not Connecting

If you see "Extension did not connect after 15s":

1. **Check extension console**:
   * Go to `chrome://extensions/`
   * Find "PraisonAI Browser Agent"
   * Click "service worker" link
   * Look for errors

2. **Kill stale Chrome processes**:
   ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
   pkill -f "Google Chrome"
   ```

3. **Rebuild extension**:
   ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
   cd /path/to/praisonai-chrome-extension
   npm run build
   ```

4. **Check bridge server**:
   ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
   curl http://localhost:8765/health
   ```

### No Observations Sent

If session starts but times out:

* Check extension console for `[PraisonAI] onStartAutomation FATAL ERROR`
* CDP debugger may fail to attach
* Page may be a chrome:// URL (unsupported)

### Debug Mode

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai browser launch "test" --debug
```

This enables verbose logging and saves screenshots to `~/.praisonai/browser_screenshots/`.

## Performance Profiling

Track timing breakdown for each automation step:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Basic profiling with timing summary
praisonai browser launch "search for AI" --engine cdp --profile

# Deep profiling with cProfile trace
praisonai browser launch "search for AI" --engine cdp --deep-profile
```

### Sample Output

```
📊 Performance Profile
──────────────────────────────────────────────────────────────────────
Total Time: 24.2s | Steps: 3 | Avg: 8.1s/step

Step |    LLM | Screen | Action | Verify | Stable |  Total
   0 |   2.4s |   0.0s |   1.0s |   0.0s |   0.0s |   3.5s
   1 |   2.2s |   0.0s |   0.2s |   0.0s |   0.0s |   2.5s

Bottlenecks: LLM 51% | Verify 0% | Stable 0%
```

### Timing Breakdown

| Metric | Description                         |
| ------ | ----------------------------------- |
| LLM    | Time spent waiting for LLM decision |
| Screen | Screenshot capture time             |
| Action | CDP action execution time           |
| Verify | Action verification time            |
| Stable | Page stability wait time            |