onUI

Annotate Any UI for AI Agents

Lightweight browser extension (Chrome + Edge + Firefox) + local MCP bridge for annotation-first UI pair programming.

Powered by onLLM.dev.

> [!NOTE]

> `onUI` is now stable and production-ready.

Demo

Click the preview above to play the full demo video.

✨ Why onUI

• 🧩 No integration into app code
• 🎛️ Per-tab ON/OFF control (off by default)
• 🎯 In-page annotation dialog with intent + severity
• ✍️ Draw mode for region annotations (rectangle + ellipse)
• ⚙️ Compact toolbar with pop-out settings (output level + clear on copy)
• 👀 Visual markers and hover targeting
• 🧾 Export outputs in compact / standard / detailed / forensic formats
• 🛡️ Shadow DOM isolation for stable styling
• 🔌 Local MCP server + native bridge (no cloud backend required)

Install (Current)

Option A: Browser Extension Stores (recommended)

Chrome Web Store:

https://chromewebstore.google.com/detail/onui/hllgijkdhegkpooopdhbfdjialkhlkan?authuser=0&hl=en-GB

Microsoft Edge Add-ons:

https://microsoftedge.microsoft.com/addons/detail/onui/fkcmlckehjhcicihbnmhkadfhjhfnond

Option B: One-command installer from latest GitHub release

Use this if you want the latest version (store updates may lag) or for Firefox:

macOS/Linux:

curl -fsSL https://github.com/onllm-dev/onUI/releases/latest/download/install.sh | bash

macOS/Linux (Firefox artifact):

curl -fsSL https://github.com/onllm-dev/onUI/releases/latest/download/install.sh | bash -s -- --firefox

Windows (PowerShell):

irm https://github.com/onllm-dev/onUI/releases/latest/download/install.ps1 | iex

Windows (PowerShell, Firefox artifact):

iwr https://github.com/onllm-dev/onUI/releases/latest/download/install.ps1 -OutFile install.ps1; .\install.ps1 -Firefox

The installer handles extension install and can set up MCP in the same run.

When prompted with `Set up local MCP bridge now? [y/N]`, enter `y` to enable MCP.

Then load it in Chrome or Edge:

1. Open `chrome://extensions` or `edge://extensions`

2. Enable Developer mode

3. Click Load unpacked

4. Select `~/.onui/extensions/current` (or `%USERPROFILE%\.onui\extensions\current` on Windows)

> Chromium browsers require this final manual step for unpacked extensions.

Firefox (manual from release artifact):

1. Download `onui-firefox-add-ons-vX.Y.Z.zip` from the GitHub release page.

2. Extract it to a local folder.

3. Open `about:debugging#/runtime/this-firefox`.

4. Click Load Temporary Add-on...

5. Select the extracted `manifest.json`.

🧠 Usage

1. Open any supported website tab.

2. Click the onUI extension icon.

3. Enable `This Tab`.

4. Use the on-page launcher to open the compact toolbar.

5. Toggle Annotate mode for element targeting or Draw mode for region targeting.

6. Hold `Shift` and click multiple elements to batch-select targets.

7. Release `Shift` to open a shared annotation dialog for selected targets.

8. Save once to create one annotation per selected element (or one region annotation in draw flow).

9. Open toolbar Settings to choose output level and configure Clear on copy.

10. Copy exported output from the toolbar.

🔌 Local MCP Setup

Recommended path: use the same installer command above and answer `y` when prompted.

If you want to force MCP setup in non-interactive mode:

macOS/Linux (`--mcp`):

curl -fsSL https://github.com/onllm-dev/onUI/releases/latest/download/install.sh | bash -s -- --mcp

Windows (PowerShell, set env var before running installer):

$env:ONUI_INSTALL_MCP=1; irm https://github.com/onllm-dev/onUI/releases/latest/download/install.ps1 | iex

MCP setup now uses a prebuilt release bundle (no local build required), but still needs Node 20+.

Manual MCP setup from source is still supported:

pnpm build:mcp
pnpm setup:mcp
pnpm doctor:mcp

Manual JSON config for custom MCP routers/clients

If your MCP router uses an object-style `mcpServers` map, use this canonical entry:

{
  "mcpServers": {
    "onui-local": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/onUI/packages/mcp-server/dist/bin/onui-cli.js",
        "mcp"
      ]
    }
  }
}

Use an absolute path for `onui-cli.js` (relative paths are often rejected or resolved incorrectly by routers).

If your router uses a list/array schema instead of an object map, adapt the same command/args shape like this:

{
  "servers": [
    {
      "name": "onui-local",
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/onUI/packages/mcp-server/dist/bin/onui-cli.js",
        "mcp"
      ]
    }
  ]
}

> The list example above is a schema adaptation pattern, not a claim about any specific router's exact key names.

Setup/verification notes:

• Run `pnpm build:mcp` first so `packages/mcp-server/dist/bin/onui-cli.js` exists.
• Keep the server entry name as `onui-local`.
• Run `pnpm doctor:mcp` after wiring config to confirm local setup health.

• Auto-registers `onui-local` for Claude Code and Codex when those CLIs are installed.
• Browser support in this release: Chrome stable + Edge stable + Firefox stable (unpacked).
• `@onui/mcp-server` is workspace-local (`private: true`), so run setup/doctor from this repo.

See:

• `docs/mcp-setup.md`
• `docs/doctor.md`
• `docs/release.md`

Maintainer Build + Release

`app.sh` is the local release entrypoint (no CI/CD dependency).

Local validation + artifact packaging

./app.sh --build

This runs:

1. Prereq checks (Node 20+, pnpm, git, zip)

2. Build order: `@onui/core` -> `@onui/extension` -> `@onui/mcp-server`

3. MCP tests

4. MCP doctor smoke check (warnings allowed, errors fail)

5. Artifact packaging into `artifacts/vX.Y.Z/`

Artifacts:

1. `onui-extension-unpacked-vX.Y.Z.zip`

2. `onui-chrome-web-store-vX.Y.Z.zip` (manifest `key` stripped for CWS)

3. `onui-edge-add-ons-vX.Y.Z.zip` (manifest `key` stripped for Edge Add-ons)

4. `onui-firefox-add-ons-vX.Y.Z.zip`

5. `onui-mcp-bundle-vX.Y.Z.zip`

6. `install.sh`

7. `install.ps1`

8. `checksums.txt`

Local release + GitHub publish

./app.sh --release

Release gates:

1. Clean git tree

2. Current branch is `main`

3. `gh auth status` succeeds

Release actions:

1. Auto patch bump from root `package.json`

2. Sync version across extension + MCP runtime strings

3. Run full `--build`

4. Commit + tag `vX.Y.Z`

5. Push commit/tag

6. Create GitHub release with packaged assets

🛠️ Development

pnpm install
pnpm check
pnpm test:coverage

🗂️ Repository Structure

packages/
  core/        Shared annotation/report types + formatters
  extension/   Browser extension runtime (background/content/popup)
  mcp-server/  Local MCP server + native bridge setup/doctor tooling

⭐ Support

If onUI is useful to you, please star the repo:

https://github.com/onllm-dev/onUI

It helps other users discover the product.

Star History

📄 License

GPL-3.0