# lockerdocx/firefox-ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/lockerdocx/firefox-ai-agent
- Repository: https://github.com/lockerdocx/firefox-ai-agent

## Overview

This is a local Firefox AI agent: a user submits a goal in the sidebar, the extension relays it to the Python host, and the host routes it to browser interaction or a broader tool loop. Browser missions observe a live tab, ask a model for a constrained action, execute it, and repeat; broader missions use tools such as web search, file/document operations, and terminal commands. The README documents permissions, model configuration, optional Laya routing, and isolated Neko browsing. Some of those subsystem links are based on README descriptions rather than sampled implementation excerpts.

Main entry points: [`extension/background.js`](https://github.com/lockerdocx/firefox-ai-agent/blob/main/extension/background.js) (Extension bridge), [`jev_ultrafast/firefox.py`](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/firefox.py) (Firefox host), [`jev_ultrafast/orchestrator.py`](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/orchestrator.py) (Mission routing), [`jev_ultrafast/agent.py`](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/agent.py) (Browser agent loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Firefox interface"]
  node_sidebar["Agent sidebar<br/>[sidebar.js]"]
  node_background["Extension bridge<br/>[background.js]"]
  node_snapshot["Page snapshot<br/>[snapshot.js]"]
  node_content["Tab actions<br/>[content.js]"]
end

subgraph group_runtime["Host runtime"]
  node_host["Firefox host<br/>[firefox.py]"]
  node_router["Mission routing<br/>[orchestrator.py]"]
  node_agent["Browser agent loop<br/>[agent.py]"]
  node_browser["Browser driver<br/>[browser.py]"]
end

subgraph group_decision["Decision and models"]
  node_laya["Local router<br/>[laya_local.py]"]
  node_skills["Skill selection<br/>[skills.py]"]
  node_model["Action policy<br/>[model.py]"]
  node_providers["Model providers<br/>[providers.py]"]
  node_parameters["Model settings<br/>[parameters.py]"]
end

subgraph group_tools["Tools and safeguards"]
  node_toolbox["Tool registry<br/>[tools.py]"]
  node_permissions["Permission checks<br/>[permissions.py]"]
  node_audit["Audit records<br/>[permissions.py]"]
end

subgraph group_integrations["Browser integrations"]
  node_neko["Neko browser<br/>[neko.py]"]
end

node_user(("User"))
node_firefox(("Firefox tab"))
node_website(("Web pages"))
node_modelservice(("Model APIs"))
node_localengine(("Laya engine"))

node_user -->|"submits goal"| node_sidebar
node_sidebar -->|"sends request"| node_background
node_background -->|"relays messages"| node_host
node_host -->|"routes mission"| node_router
node_host -->|"starts browser run"| node_agent
node_router -.->|"tries local route"| node_laya
node_laya -.->|"classifies mission"| node_localengine
node_router -->|"selects skill"| node_skills
node_router -->|"runs tool loop"| node_toolbox
node_toolbox -->|"checks access"| node_permissions
node_permissions -->|"records decisions"| node_audit
node_toolbox -->|"requests reasoning"| node_providers
node_agent -->|"observes and acts"| node_browser
node_agent -->|"requests action"| node_model
node_model -->|"resolves model"| node_providers
node_providers -->|"sends inference"| node_modelservice
node_background -->|"requests snapshot"| node_snapshot
node_background -->|"dispatches action"| node_content
node_snapshot -->|"reads page"| node_firefox
node_content -->|"executes action"| node_firefox
node_browser -->|"uses bridge"| node_background
node_browser -.->|"can drive instead"| node_neko
node_sidebar -->|"updates model settings"| node_background
node_host -->|"loads settings"| node_parameters
node_agent -->|"interacts through tab"| node_website

click node_sidebar "https://github.com/lockerdocx/firefox-ai-agent/blob/main/extension/sidebar/sidebar.js"
click node_background "https://github.com/lockerdocx/firefox-ai-agent/blob/main/extension/background.js"
click node_snapshot "https://github.com/lockerdocx/firefox-ai-agent/blob/main/extension/snapshot.js"
click node_content "https://github.com/lockerdocx/firefox-ai-agent/blob/main/extension/content.js"
click node_host "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/firefox.py"
click node_router "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/orchestrator.py"
click node_agent "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/agent.py"
click node_browser "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/browser.py"
click node_laya "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/laya_local.py"
click node_skills "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/skills.py"
click node_model "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/model.py"
click node_providers "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/providers.py"
click node_parameters "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/parameters.py"
click node_toolbox "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/tools.py"
click node_permissions "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/permissions.py"
click node_audit "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/permissions.py"
click node_neko "https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/neko.py"

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,node_background,node_snapshot,node_content,node_user toneBlue
class node_host,node_router,node_agent,node_browser toneAmber
class node_laya,node_skills,node_model,node_providers,node_parameters,node_modelservice toneMint
class node_toolbox,node_permissions,node_audit toneRose
class node_neko,node_firefox,node_website,node_localengine toneIndigo
```

## Components

### Firefox interface

- [Agent sidebar](https://github.com/lockerdocx/firefox-ai-agent/blob/main/extension/sidebar/sidebar.js): `extension/sidebar/sidebar.js`
- [Extension bridge](https://github.com/lockerdocx/firefox-ai-agent/blob/main/extension/background.js): `extension/background.js`
- [Page snapshot](https://github.com/lockerdocx/firefox-ai-agent/blob/main/extension/snapshot.js): `extension/snapshot.js`
- [Tab actions](https://github.com/lockerdocx/firefox-ai-agent/blob/main/extension/content.js): `extension/content.js`

### Host runtime

- [Firefox host](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/firefox.py): `jev_ultrafast/firefox.py`
- [Mission routing](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/orchestrator.py): `jev_ultrafast/orchestrator.py`
- [Browser agent loop](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/agent.py): `jev_ultrafast/agent.py`
- [Browser driver](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/browser.py): `jev_ultrafast/browser.py`

### Decision and models

- [Local router](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/laya_local.py): `jev_ultrafast/laya_local.py`
- [Skill selection](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/skills.py): `jev_ultrafast/skills.py`
- [Action policy](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/model.py): `jev_ultrafast/model.py`
- [Model providers](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/providers.py): `jev_ultrafast/providers.py`
- [Model settings](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/parameters.py): `jev_ultrafast/parameters.py`

### Tools and safeguards

- [Tool registry](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/tools.py): `jev_ultrafast/tools.py`
- [Permission checks](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/permissions.py): `jev_ultrafast/permissions.py`
- [Audit records](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/permissions.py): `jev_ultrafast/permissions.py`

### Browser integrations

- [Neko browser](https://github.com/lockerdocx/firefox-ai-agent/blob/main/jev_ultrafast/neko.py): `jev_ultrafast/neko.py`

### Other components

- **User**
- **Firefox tab**
- **Web pages**
- **Model APIs**
- **Laya engine**

## Connections

- User → Agent sidebar: submits goal
- Agent sidebar → Extension bridge: sends request
- Extension bridge → Firefox host: relays messages
- Firefox host → Mission routing: routes mission
- Firefox host → Browser agent loop: starts browser run
- Mission routing → Local router: tries local route
- Local router → Laya engine: classifies mission
- Mission routing → Skill selection: selects skill
- Mission routing → Tool registry: runs tool loop
- Tool registry → Permission checks: checks access
- Permission checks → Audit records: records decisions
- Tool registry → Model providers: requests reasoning
- Browser agent loop → Browser driver: observes and acts
- Browser agent loop → Action policy: requests action
- Action policy → Model providers: resolves model
- Model providers → Model APIs: sends inference
- Extension bridge → Page snapshot: requests snapshot
- Extension bridge → Tab actions: dispatches action
- Page snapshot → Firefox tab: reads page
- Tab actions → Firefox tab: executes action
- Browser driver → Extension bridge: uses bridge
- Browser driver → Neko browser: can drive instead
- Agent sidebar → Extension bridge: updates model settings
- Firefox host → Model settings: loads settings
- Browser agent loop → Web pages: interacts through tab