@mitverse/mitbar-web

mitbar-web is a browser bar you add to any website. When enabled, it stays visible and talks to the agent WebSocket at agent.mitverse.com (or a URL you set). Every message includes the page URL and title. The bar provides Build, Deploy, and Send (chat) actions.

Requirements

• A WebSocket endpoint for the bar (e.g. agent.mitverse.com at /api/v1/agent/ws). Default URL: wss://agent.mitverse.com/api/v1/agent/ws.
• Optionally, the backend can require a JWT for the WebSocket when MITBAR_WS_REQUIRE_AUTH is set.

Installation

From npm

npm install @mitverse/mitbar-web

From this repo (local / monorepo)

cd mitbar-web
npm install
npm run build

Then in your app (e.g. devops or agent):

{
  "dependencies": {
    "@mitverse/mitbar-web": "file:../mitbar-web"
  }
}

Usage

You can use the bar in two ways: script tag (standalone) or ESM (bundled app, e.g. Vite/React).

Option 1: Script tag (standalone)

Load the UMD bundle and enable the bar with data attributes on the script tag. The bar auto-initializes when the script loads.

<script
  src="https://your-cdn.com/path/to/mitbar.umd.cjs"
  data-mitbar-enabled="true"
  data-mitbar-gateway-ws-url="wss://agent.mitverse.com/api/v1/agent/ws"
></script>

Or set a global config before the script:

<script>
  window.__MITBAR_CONFIG__ = {
    enabled: true,
    gatewayWsUrl: 'wss://agent.mitverse.com/api/v1/agent/ws',
    token: 'YOUR_JWT'   // optional; use when backend sets MITBAR_WS_REQUIRE_AUTH
  };
</script>
<script src="https://your-cdn.com/path/to/mitbar.umd.cjs"></script>

• Script-tag auto-init only runs when the script element has data-mitbar-enabled="true" (or "1"). That way, when the package is bundled and imported by your app, it does not auto-init; your app calls init() once with gatewayWsUrl and optional getToken, so the single WebSocket connection includes the token when required.

Option 2: ESM (Vite / React app)

Import and call init() once inside your protected layout (after the user is logged in) so the bar appears on all authenticated pages. You must call init() when using the package as a dependency; it does not auto-init in this case.

import { init } from '@mitverse/mitbar-web';

// Inside your Layout component (e.g. in a useEffect):
init({
  enabled: true,
  gatewayWsUrl: import.meta.env.VITE_MITBAR_GATEWAY_WS_URL || 'wss://agent.mitverse.com/api/v1/agent/ws',
  getToken: () => localStorage.getItem('token'),  // optional; required when backend sets MITBAR_WS_REQUIRE_AUTH
});

• enabled – true to show the bar.
• gatewayWsUrl – WebSocket URL. Use env VITE_MITBAR_GATEWAY_WS_URL or the default above.
• token – Optional static JWT (e.g. from a variable). Prefer getToken when the token can change (e.g. after login).
• getToken – Optional function that returns the app’s JWT (e.g. () => localStorage.getItem('token')). Use when the backend requires auth (MITBAR_WS_REQUIRE_AUTH); the bar will add ?token=<JWT> to the WebSocket URL.
• agentApiBaseUrl – Optional. When set together with getToken, the Mitbar logo becomes a button that opens a task list panel. Tasks are fetched directly from the agent backend (no agent frontend involved): GET {agentApiBaseUrl}/conversations?source=mitbar&limit=50 with Authorization: Bearer <token>.

When token or getToken() returns a non-empty string, the client connects to gatewayWsUrl?token=<JWT>. If the backend requires auth and you omit the token, the connection will be closed with code 4401.

Task list (direct to agent backend)

mitbar-web is a standalone app. The task list (Mitbar logo click) is implemented entirely inside mitbar-web and talks directly to the agent backend:

• Endpoint: GET {agentApiBaseUrl}/conversations?source=mitbar&limit=50
• Auth: Authorization: Bearer <token> (from getToken() or token)
• No agent frontend is involved; the bar and task list do not use any code from the agent repo.

Example with task list enabled:

init({
  enabled: true,
  gatewayWsUrl: 'wss://agent.mitverse.com/api/v1/agent/ws',
  getToken: () => localStorage.getItem('token'),
  agentApiBaseUrl: 'https://agent.mitverse.com/api/v1/agent',  // enables task list panel
});

Environment variables

When building your app (e.g. Vite), you can set:

| Variable | Description | |----------|-------------| | VITE_MITBAR_GATEWAY_WS_URL | WebSocket URL for the bar (e.g. wss://agent.mitverse.com/api/v1/agent/ws). Used by Vite apps. | | VITE_AGENT_API_BASE_URL | Agent backend base URL for the task list (e.g. https://agent.mitverse.com/api/v1/agent). Used when passing agentApiBaseUrl from env. | | MITBAR_GATEWAY_WS_URL | Alternative build-time default when bundled. |

Message format

• The bar sends over WebSocket: { text, pageUrl, pageTitle, action: 'chat' | 'build' | 'deploy' }.
• The gateway uses this payload and forwards to the agent (e.g. script-writer); responses are streamed back to the bar.

Build

npm run build

Output in dist/:

• mitbar.es.js – ESM (for bundlers)
• mitbar.umd.cjs – UMD (script tag / CDN)

Deploy

Build and serve dist/ from your CDN or static host. If gatewayWsUrl is not set, the bar uses wss://agent.mitverse.com/api/v1/agent/ws. Ensure the WebSocket endpoint is reachable and that your origin is allowed by the backend (CORS / WebSocket origin). When the backend requires auth, pass token or getToken so the connection URL includes the JWT.