harness-fe

Features

• Source-Aware Instrumentation — Injects data-morphix-loc and data-morphix-comp attributes into JSX / Vue elements (via build plugin OR @harness-fe/react-jsx jsxImportSource), giving AI agents precise file:line:column references for every UI element.

• MCP Gateway — Connects AI agents (Claude, Cursor, Kiro) to browser + server runtimes via WebSocket / HTTP. Solo mode auto-spawns a shared loopback gateway; team mode (harness --governed) adds RBAC tokens, project→agent binding, and audit. Bidirectional command/event communication with a unified timeline per page-load.

• Browser Runtime + Overlay — A lightweight browser SDK that captures console / network / errors / DOM (rrweb), exposes an in-page "H" overlay so users can file annotated screenshots (arrow + text on a snapdom-captured PNG), and surfaces a "My reports" view to manage their submissions. The overlay is extensible — add custom action buttons via registerOverlayPlugin to send the current scene/logs to your own system (issue tracker, Slack, webhook). See docs/overlay-plugins.md.

• Server-Side Capture (Next.js) — @harness-fe/node-runtime collects Server Component errors, Route Handler / Server Action durations, and uncaught Node exceptions. <HarnessScript> is a Server Component that uses React cache() to bind the same sessionId across SSR and the client runtime — one refresh = one sessions/{id}/timeline.jsonl.

• Edge Runtime Compatible — When Next emits an Edge worker bundle the SDK auto-switches to an HTTP-batch transport (POST /events on the gateway) so Cloudflare Workers / Vercel Edge routes flow into the same gateway as Node routes.

• Visitor Identity — Anonymous, stable per-browser identifier (localStorage) + optional userId from the app's auth layer. Lets agents build a real user journey across refreshes, tabs, and same-origin iframes.

• Annotated Feedback Loop — Users file tasks through the overlay; the screenshot's arrow + text annotations are flattened into the PNG so vision models read the annotations directly off pixels. Agents fetch the image via tasks_get_attachment as a native MCP image-content block.

• Multi-Bundler & Multi-Framework — Stable on Vite + React, Webpack + React, Vite/Webpack + Vue 3, Next.js (App + Pages Router, webpack + Turbopack). Any React 17+ toolchain via @harness-fe/react-jsx jsxImportSource.

• Zero Production Overhead — All instrumentation, WebSocket / HTTP connections, the overlay, and the Node SDK are gated behind NODE_ENV === 'development'.

Related MCP server: Kaboom Browser AI Devtools MCP

How It Works

Harness-FE uses a three-layer architecture to connect AI agents with your running application:

graph LR
    Agent["🤖 AI Agent<br/>(Claude / Kiro)"]
    GW["⚡ Gateway<br/>(harness)"]
    Plugin["🔧 Build Plugin<br/>(Vite / Webpack)"]
    Runtime["🌐 Runtime Client<br/>(Browser)"]

    Agent <-->|stdio or HTTP-MCP| GW
    GW <-->|WebSocket /ws| Plugin
    GW <-->|WebSocket /ws| Runtime

Data flow: Bundler transforms source → Browser renders instrumented DOM → Runtime captures state → Gateway relays to AI Agent → Agent sends commands back through the same path.

Supported Environments

Getting Started

In a hurry? Jump to the 90-second Quickstart.

Prerequisites

• Node.js >= 20

• pnpm >= 8 (recommended), npm >= 9, or yarn >= 1.22

Installation

pnpm (recommended):

pnpm add -D @harness-fe/vite @harness-fe/runtime

npm:

npm install -D @harness-fe/vite @harness-fe/runtime

yarn:

yarn add -D @harness-fe/vite @harness-fe/runtime

Which path are you on?

Whichever path: install the skill first (npx @harness-fe/skill install) so your agent knows how to use harness-fe without you spelling out each tool. See docs/agent-setup.md.

Quick start — Vite + React (6 steps)

1. Install packages:

   pnpm add -D @harness-fe/vite @harness-fe/runtime

2. Configure Vite — add the plugin to your vite.config.ts:

   import { defineConfig } from 'vite';
   import react from '@vitejs/plugin-react';
   import { harnessFE } from '@harness-fe/vite';
   export default defineConfig({ plugins: [react(), harnessFE()] });

3. Install the agent skill (recommended — do this first) — teach your agent how to drive harness-fe so you don't have to hand-hold it:

   npx @harness-fe/skill install      # auto-detects Claude Code / Cursor / Kiro

   The skill drops a curated playbook (mental model + tool catalog + decision flows) into your IDE. Your agent then knows which tool to reach for from a plain-English bug report — you describe the problem, it drives the app.

4. Wire the MCP server — add harness-fe to your agent's .mcp.json (solo / local — no token, trusted on loopback):

   {
     "mcpServers": {
       "harness-fe": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@harness-fe/cli", "mcp"]
       }
     }
   }

   harness mcp auto-spawns a shared gateway on 127.0.0.1:47729 and proxies MCP traffic to it. Multiple IDE windows share the same gateway automatically. Sharing across a team? Use governed mode instead. Phone / second-machine debugging: docs/lan-mode.md.

5. Start your dev server — pnpm dev.

6. Describe a problem to your agent — "the increment button does nothing" — and it uses the skill + tools to inspect console/network, locate the source (file:line), fix, and verify. The agent that built it never leaves.

Adopting in legacy Vue projects? See docs/vue2-compat.md — the plugin will never break your build, but you may want to dry-run first to see which files miss out on source-aware tagging.

Embedding in Electron / Tauri / multi-window hosts? See docs/electron.md for how to make every renderer share one sessionId so the agent gets a unified cross-window timeline.

Quick start — Next.js (App or Pages Router)

For Next.js the recommended path is plugin-less (via react-jsx for source tagging + next for SSR session continuity). Two file touches.

1. Install:

   pnpm add -D @harness-fe/next @harness-fe/react-jsx @harness-fe/runtime @harness-fe/node-runtime

2. tsconfig.json — enable the source-tag JSX runtime:

   { "compilerOptions": { "jsxImportSource": "@harness-fe/react-jsx" } }

3. next.config.mjs — wrap with withHarness():

   import { withHarness } from '@harness-fe/next/config';
   export default withHarness({/* …your config… */}, { projectId: 'my-app' });

4. app/layout.tsx — drop in the Server Component (yes, no 'use client' needed):

   import { HarnessScript } from '@harness-fe/next';
   import { getCurrentUser } from '@/lib/auth';
   export default async function RootLayout({ children }) {
       const user = await getCurrentUser().catch(() => null);
       return (
           <html><body>
               <HarnessScript
                   projectId="my-app"
                   userId={user?.id}
                   buildId={process.env.NEXT_PUBLIC_GIT_SHA}
               />
               {children}
           </body></html>
       );
   }

5. pnpm dev. Two peer connected lines should show in the gateway log per refresh — one role=node-runtime, one role=runtime-client, same sessionId.

Optional — structured logs with @harness-fe/log

For explicit logs (instead of relying on auto-captured console.*), use the isomorphic logger. Same import works in Server Components, Route Handlers, Server Actions, and Client Components — events from both server and client land in the same session timeline.

pnpm add @harness-fe/log

import { log } from '@harness-fe/log';

// Anywhere — Server Component, Route Handler, Client Component, shared util
log.info('Cart loaded', { items: items.length });
log.scope('checkout').warn('Stripe latency high', { ms: latency });
log.error('Webhook failed', err);

Agents can ask "show me all log.warn(...) in this session" because log events are tagged app-log — distinct from auto-captured server-log / browser console. See packages/log/README.md for details.

User feedback (in-page overlay)

When the runtime loads in dev a discreet "H" mark appears bottom-right. Clicking opens the info card. From there users can:

• Copy snapshot — markdown block with project / build / session / tab / url ready to paste to an agent.

• Report a problem — picks an element → snapdom captures it with 32 px context → user draws arrows + text → flattened PNG ships as part of a task.submit event. Vision-capable agents read the annotations directly off the pixels.

• My reports — list of this visitor's tasks across all sessions: status, agent's resolution note, inline edit, copy-for-agent, delete with two-click confirm.

Packages

Documentation

• VISION.md — Why this project exists; the three deployment directions that drive the roadmap

• docs/agent-setup.md — ⭐ Connect your agent: install the skill first, then wire .mcp.json (solo or governed)

• docs/gateway-team-mode.md — Share one gateway across a team: governed mode, scope RBAC, project→agent binding, audit

• ARCHITECTURE.md — Package responsibilities, data flow diagrams, sessionId resolution chain, and protocol reference

• docs/architecture/sandbox.md — The @harness-fe/sandbox lib (browser API patching + interceptor middleware) — design + safety contract + 9-channel matrix

• ROADMAP.md — Milestones, organised by mission direction

• docs/troubleshooting.md — Events not showing? sessionId mismatch? Where do timeline files live? Start here

• CONTRIBUTING.md — Development setup, commit conventions, and PR process

License

MIT © 2026 MorphixAI