ai-dom-agent (Frontend)

Frontend package for AI DOM Agent.
Provides a floating widget that lets users control the DOM with natural language.

Why do I need the backend?

The frontend widget does not contain AI models.
When you enter a command, the widget captures the current page’s HTML and sends it to the backend (ai-dom-agent-backend).
The backend uses an AI provider (OpenAI by default, or DeepSeek/Ollama if configured) to parse the command + HTML and return structured JSON actions (click, fill, scroll, etc.).
The widget then executes these actions on the page.

👉 Without the backend running, the widget cannot generate or run commands.

Install

npm install ai-dom-agent

Usage

React

import { initAgentWidget } from 'ai-dom-agent';

useEffect(() => {
  initAgentWidget({ backendUrl: 'http://localhost:4000' });
}, []);

Vue

import { initAgentWidget } from 'ai-dom-agent';

initAgentWidget({ backendUrl: 'http://localhost:4000' });

Plain HTML

<script type="module">
  import { initAgentWidget } from 'ai-dom-agent';
  initAgentWidget({ backendUrl: 'http://localhost:4000' });
</script>

Config

initAgentWidget(options)

• backendUrl — required (default: http://localhost:4000)
• buttonLabel — optional, floating button text
• defaultCommand — optional, prefill input

Backend Setup (Required)

Install the backend package:

npm install ai-dom-agent-backend

Create a .env file in the backend project:

OPENAI_API_KEY=your_api_key_here
PORT=4000

Run the backend:

npm run dev

Now the frontend widget can connect to it at http://localhost:4000.

Build

npm run build