Skip to content

About

Select React components in a running app, persist the current UI selection, and feed that selection back into Claude Code without adding a custom MCP server.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🔎 React Agent Lens

Point at a live React UI, capture the exact components on screen, and send that context straight into Claude Code.

No manual file hunting. No vague prompts. No custom MCP server.

Live demo: https://chiItepin.github.io/agent-lens/

Screenshot 2026-03-07 at 11 27 36 a m

What it does

react-agent-lens gives you a tighter loop between the browser and your coding agent:

  • instruments JSX so rendered DOM nodes point back to source files
  • shows an in-browser overlay for selecting components
  • persists the current UI selection at app root
  • injects that selection into Claude Code through a UserPromptSubmit hook

What ships

  • Babel instrumentation for annotated DOM output
  • Overlay for interactive selection
  • Webpack and Vite dev-server integrations
  • A packaged UserPromptSubmit hook command: agent-lens-user-prompt-submit

Live demo

Try the Vite example on GitHub Pages:

The demo runs the real overlay and source mapping UI in the browser. Because GitHub Pages is static, it uses localStorage for selection persistence instead of the dev middleware and does not feed context into Claude Code.

Install

npm install react-agent-lens

Use the overlay

Render the overlay somewhere in your app during development:

import { AgentLensOverlay } from 'react-agent-lens/overlay';

export const App = () => {
  return (
    <>
      <YourApp />
      <AgentLensOverlay />
    </>
  );
};

Default shortcut: Alt+Shift+L

Webpack setup

Add the webpack plugin in development so Babel instrumentation and the dev middleware are both active:

const path = require('path');
const { AgentLensWebpackPlugin } = require('react-agent-lens/webpack');

module.exports = {
  plugins: [
    new AgentLensWebpackPlugin({
      root: path.resolve(__dirname, 'src'),
      // Optional: override where the selection file is written.
      // Useful when Claude runs from a different project root in a monorepo.
      // outputFilePath: path.resolve(__dirname, '..', '.agent-lens-selection.json'),
    }),
  ],
};

Key point: your app must already use babel-loader for React source files so the plugin can inject the react-agent-lens Babel transform.

outputFilePath is optional, but it matters in monorepos. The webpack dev middleware writes selections to that file, while the Claude hook reads $CLAUDE_PROJECT_DIR/.agent-lens-selection.json by default. If those resolve to different directories, the hook will not see the current selection unless you either:

  • write the selection file to the same directory Claude uses
  • pass the same custom file path to agent-lens-user-prompt-submit

Vite setup

Use the React plugin Babel option for JSX instrumentation and the react-agent-lens Vite plugin for the middleware:

import path from 'path';
import react from '@vitejs/plugin-react';
import agentLensBabelPlugin from 'react-agent-lens/babel';
import { agentLens } from 'react-agent-lens/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: [
          [
            agentLensBabelPlugin,
            {
              root: path.resolve(__dirname, 'src'),
            },
          ],
        ],
      },
    }),
    agentLens({
      root: __dirname,
      // Optional in single-package apps.
      // Recommended in monorepos when Claude runs from a different root.
      // outputFilePath: path.resolve(__dirname, '..', '.agent-lens-selection.json'),
    }),
  ],
});

outputFilePath controls where the Vite middleware persists .agent-lens-selection.json. This is important in monorepos because the hook command reads from $CLAUDE_PROJECT_DIR/.agent-lens-selection.json by default. If your Vite app lives in something like apps/web but Claude runs from the repo root, set outputFilePath to a location both sides agree on, or pass that same path to the hook command.

Claude hook setup

After installing react-agent-lens in your app, add a UserPromptSubmit hook in your consumer project's .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/node_modules/.bin/agent-lens-user-prompt-submit"
          }
        ]
      }
    ]
  }
}

The command reads .agent-lens-selection.json from the consumer app root by default and injects the selected UI elements into Claude's prompt context.

If your dev plugin writes to a custom outputFilePath, the hook must read that same file. In monorepos, this is often required.

You can also pass a custom path:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/node_modules/.bin/agent-lens-user-prompt-submit ./custom-selection.json"
          }
        ]
      }
    ]
  }
}

Example for a monorepo where the app is in apps/web and Claude runs from the repo root:

agentLens({
  root: __dirname,
  outputFilePath: path.resolve(__dirname, '..', '..', '.agent-lens-selection.json'),
});
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/node_modules/.bin/agent-lens-user-prompt-submit ./.agent-lens-selection.json"
          }
        ]
      }
    ]
  }
}

Selection file lifecycle

  • Selections are persisted to .agent-lens-selection.json at the app root where the dev server runs.
  • Removing a single selection updates the file.
  • Clearing all selections deletes the file.
  • Starting the webpack or Vite dev server deletes stale selection files before serving.

Typical flow

  1. Start your dev server with the webpack or Vite integration enabled.
  2. Toggle the overlay with Alt+Shift+L.
  3. Click UI elements to build a selection.
  4. Submit a prompt in Claude Code.
  5. The UserPromptSubmit hook injects the current selected UI context automatically.

Ignore the selection file

Add this to your consumer app .gitignore:

.agent-lens-selection.json

About

Select React components in a running app, persist the current UI selection, and feed that selection back into Claude Code without adding a custom MCP server.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages