React Grab

react-grab — Browser element context for AI agents

Keyword: react-grab · grab · element context

>

Point at a live React UI element, capture the exact component/file/HTML context, and feed it

straight into Claude Code, Cursor, Copilot, Codex, Gemini, or an MCP workflow.

When to use this skill

• Install react-grab in a React project so agents can copy exact component context from the browser
• Choose between clipboard flow, MCP flow, and plugin/API flow for React element capture
• Fix react-grab setup issues like wrong load point, missing file paths, or empty MCP responses
• Add or remove an agent integration (claude-code, cursor, codex, gemini, mcp, etc.)
• Build a custom plugin or use the primitives API for a project-specific workflow

Do not use this skill for:

• Fresh-session browser automation, auth flows, or disposable browser verification → browser-harness
• Running-browser reuse with existing cookies/extensions/logins → playwriter
• Human feedback / annotation packets on rendered UI → agentation
• React performance diagnosis, rerender churn, hydration, bundle, or RSC/client-boundary work → react-best-practices
• General UI-system / token / component-library design work → design-system

Instructions

Step 1: Classify the request

Choose one primary mode before giving commands:

1. Clipboard install/use — user wants to hover, press Cmd/Ctrl+C, and paste context into an AI agent. 2. MCP workflow — user wants the agent to call a tool like get_element_context after browser selection. 3. Plugin/API workflow — user wants custom actions, lifecycle hooks, formatting, or primitives like freeze(). 4. Troubleshooting/removal — user wants to fix setup problems or remove the integration cleanly.

Step 2: Confirm prerequisites truthfully

Use the upstream project as source of truth:

• npx grab@latest init is the default install path.
• Upstream package.json currently requires Node.js >=22.
• The browser overlay is a development-only tool; never present it as a production feature.

If the user’s environment is older than Node 22, say so explicitly before giving the install path.

Step 3: Give the shortest correct path

Mode A — Clipboard install/use

Use this as the default path unless the user explicitly asks for MCP or plugins:

# At the project root
npx -y grab@latest init

Then explain the runtime flow: 1. Start the dev server. 2. Open the app in the browser. 3. Hover the target element. 4. Press Cmd+C (Mac) or Ctrl+C (Windows/Linux). 5. Paste the captured context into the AI agent.

Clipboard output should include:

• component name
• source file path
• line/column when available
• HTML snippet

If the user needs framework-specific setup, use references/install-and-routing.md.

Mode B — MCP workflow

When the user wants programmatic access from the agent instead of manual paste:

npx -y grab@latest add mcp

Explain the real flow clearly: 1. User selects or hovers the element in the browser overlay. 2. The MCP server exposes the latest selection. 3. The AI agent calls get_element_context. 4. The tool returns file path, component, stack, and HTML context.

If the user asks how this differs from clipboard flow:

• Clipboard is manual paste into chat.
• MCP is tool-based retrieval after selection.

Use references/agent-workflows.md for agent-specific install and routing guidance.

Mode C — Plugin/API workflow

When the user wants custom behavior, automation, or a deeper integration:

• Route installation and workflow choice first.
• Then point to:
• references/api.md for full API surface
• references/agent-workflows.md for practical plugin/MCP patterns

Common primitives to mention:

• getElementContext(element)
• freeze() / unfreeze()
• openFile(filePath, lineNumber?)
• registerPlugin(...)

Do not dump the full API unless the user asked for the deep path.

Mode D — Troubleshooting/removal

If the user wants fixes or teardown:

• Use references/troubleshooting.md for symptom-first triage.
• For removal, use upstream CLI removal commands:

npx -y grab@latest remove <agent>

Step 4: Keep the boundary sharp

Keep react-grab focused on React element context capture from the browser.

Route out when the user is actually asking for:

• general browser automation → browser-harness or playwriter
• UI review / visual annotation → agentation
• performance / profiling / hydration / bundle / RSC issues → react-best-practices
• reusable component-system design → design-system or ui-component-patterns

Step 5: Prefer reference docs over bloating the front door

After classifying the mode, load only the matching support doc:

• references/install-and-routing.md
• references/agent-workflows.md
• references/troubleshooting.md
• references/api.md

Keep the main answer short unless the user explicitly asks for the long path.

Examples

Example 1: install in a Next.js app and use clipboard flow

User: “Set up react-grab in my Next.js app so I can copy a component into Claude Code.”

Response shape: 1. Confirm Node 22+ prerequisite. 2. Use npx -y grab@latest init as the default path. 3. Explain dev-server → browser hover → Cmd/Ctrl+C → paste into Claude Code. 4. Only load framework-specific setup if auto-detect is not viable.

Example 2: MCP setup for agent tool access

User: “Install react-grab MCP so the agent can grab the selected button context.”

Response shape: 1. Confirm Node 22+ prerequisite. 2. Run npx -y grab@latest add mcp. 3. Explain that the browser selection happens first, then the agent calls get_element_context. 4. Route generic browser-control questions to browser-harness / playwriter if needed.

Example 3: custom plugin workflow

User: “Create a react-grab plugin that adds a Jira action to the context menu.”

Response shape: 1. Keep react-grab as the plugin/API lane. 2. Use registerPlugin(...) with an action and optional hooks. 3. Point to references/api.md for the full hook surface. 4. Keep the example focused on the requested action rather than reproducing the whole API.

Example 4: fix setup drift

User: “grab init keeps failing on my machine.”

Response shape: 1. Check Node version first and call out the Node 22+ requirement. 2. Confirm they are running from the project root. 3. Use references/troubleshooting.md for overlay/load/MCP/path failures. 4. Route unrelated framework build issues to the appropriate frontend skill.

Best practices

1. State the Node.js >=22 prerequisite truthfully before recommending install commands. 2. Default to `npx -y grab@latest init` unless the user explicitly needs manual framework setup. 3. Keep it dev-only — never imply this belongs in production builds. 4. Explain clipboard vs MCP clearly so users do not confuse paste-based and tool-based workflows. 5. Route broad browser or UI-review work out early instead of letting react-grab absorb adjacent skills. 6. Use support docs for depth instead of pasting long installation or API manuals into the main response.

References

• react-grab GitHub
• react-grab.com
• Install and routing guide
• Agent workflows
• Troubleshooting
• Full API reference
• Helper scripts — install.sh and add-agent.sh

react-grab agent workflows

The three practical workflows

1. Clipboard workflow

Best for: quick human-in-the-loop use with Claude Code, Cursor, Copilot Chat, Codex, or Gemini.

npx -y grab@latest init

Flow: 1. Start the app in development mode. 2. Hover the UI element in the browser. 3. Press Cmd+C (Mac) or Ctrl+C (Windows/Linux). 4. Paste the captured context into the coding agent.

Expected payload:

• component name
• file path
• line/column when available
• HTML snippet

Use this as the default path unless the user explicitly wants MCP.

2. MCP workflow

Best for: agent tool calls after browser selection.

npx -y grab@latest add mcp

Flow: 1. User selects or hovers an element in the browser. 2. The local MCP server stores/exposes the latest selection. 3. The agent calls get_element_context. 4. The tool returns structured context for the selected element.

Clarify this if needed:

• MCP does not replace the browser-side selection step.
• It replaces manual clipboard paste after selection.

3. Plugin/API workflow

Best for: project-specific customization, workflow automation, or custom actions.

Use when the user wants to:

• add a Jira/Figma/GitHub action to the context menu
• transform copied content before it hits the clipboard
• override open-file behavior
• freeze the page for hover-only or transient UI states
• integrate element capture into tests or custom scripts

Minimal plugin example:

import { registerPlugin } from "react-grab";

registerPlugin({
  name: "jira-action",
  actions: [
    {
      id: "jira",
      label: "Create Jira Ticket",
      shortcut: "J",
      onAction: async (context) => {
        await createJiraTicket({
          filePath: context.filePath,
          componentName: context.componentName,
          html: context.element.outerHTML,
        });
        context.hideContextMenu();
      },
    },
  ],
});

Agent-specific commands

npx -y grab@latest add claude-code
npx -y grab@latest add cursor
npx -y grab@latest add copilot
npx -y grab@latest add codex
npx -y grab@latest add gemini
npx -y grab@latest add opencode
npx -y grab@latest add amp
npx -y grab@latest add droid
npx -y grab@latest add mcp

Removal:

npx -y grab@latest remove <agent>

Boundary reminders

Use react-grab for exact React element context.

Route out when the user really wants:

• browser navigation, auth, screenshots, or scripted flow control → browser-harness or playwriter
• rendered-UI markup/annotation and review packets → agentation
• performance triage on the React app itself → react-best-practices

Common answer shapes

“I want to feed a selected button to Claude Code”

• confirm Node 22+
• recommend grab init
• explain clipboard flow

“I want the agent to pull the selected component without paste”

• confirm Node 22+
• recommend grab add mcp
• explain browser-selection-first, tool-call-second

“I need a custom context-menu action”

• stay in react-grab
• show registerPlugin(...)
• route full hook/API detail to references/api.md

react-grab API Reference

Full TypeScript API for react-grab v0.1.x

Source: https://github.com/aidenybai/react-grab

---

ReactGrabAPI

The primary API object — stored as window.__REACT_GRAB__ and returned by init().

interface ReactGrabAPI {
  // Activation control
  activate(): void;               // Show the overlay
  deactivate(): void;             // Hide the overlay
  toggle(): void;                 // Toggle visibility
  comment(): void;                // Enter prompt/comment mode
  isActive(): boolean;            // Is overlay currently shown?
  isEnabled(): boolean;           // Is react-grab enabled at all?
  setEnabled(enabled: boolean): void;

  // Toolbar state
  getToolbarState(): ToolbarState | null;
  setToolbarState(state: Partial<ToolbarState>): void;
  onToolbarStateChange(callback: (state: ToolbarState) => void): () => void;

  // Element operations
  copyElement(elements: Element | Element[]): Promise<boolean>;
  getSource(element: Element): Promise<SourceInfo | null>;
  getStackContext(element: Element): Promise<string>;
  getDisplayName(element: Element): string | null;

  // State
  getState(): ReactGrabState;
  setOptions(options: SettableOptions): void;

  // Plugin system
  registerPlugin(plugin: Plugin): void;
  unregisterPlugin(name: string): void;
  getPlugins(): string[];

  // Lifecycle
  dispose(): void;
}

Access the API

import { getGlobalApi } from "react-grab";
const api = getGlobalApi();  // Returns null if not initialized

---

init() — Configuration

import { init } from "react-grab";

init(options?: Options);

interface Options {
  enabled?: boolean;                   // Enable/disable entirely (default: true)
  activationMode?: ActivationMode;     // "toggle" | "hold" (default: "toggle")
  keyHoldDuration?: number;            // Duration in ms for "hold" mode
  allowActivationInsideInput?: boolean;
  maxContextLines?: number;            // Limit React component stack depth
  activationKey?: ActivationKey;       // string or (event: KeyboardEvent) => boolean
  getContent?: (elements: Element[]) => Promise<string> | string;
  freezeReactUpdates?: boolean;        // Pause React state while active (default: true)
}

type ActivationMode = "toggle" | "hold";
type ActivationKey = string | ((event: KeyboardEvent) => boolean);

Examples:

// Custom activation key
init({ activationKey: "g" }); // Cmd+G / Ctrl+G

// Hold mode (show while key is held)
init({ activationMode: "hold", keyHoldDuration: 500 });

// Custom content formatter
init({
  getContent: async (elements) => {
    const { generateSnippet } = await import("react-grab");
    const snippets = await generateSnippet(elements);
    return snippets.join("\n---\n");
  },
});

// Disable initially, enable later
init({ enabled: false });
getGlobalApi()?.setEnabled(true);

---

Primitives API

Standalone utilities available without the default overlay UI.

import { getElementContext, freeze, unfreeze, isFreezeActive, openFile }
  from "react-grab/primitives";
// or: from "react-grab/core"

getElementContext(element)

getElementContext(element: Element): Promise<ReactGrabElementContext>

Returns comprehensive context for any DOM element:

interface ReactGrabElementContext {
  element: Element;          // The DOM element itself
  htmlPreview: string;       // Compact HTML snippet
  stackString: string;       // React component stack as formatted string
  stack: StackFrame[];       // Parsed stack frames
  componentName: string | null;  // Nearest React component display name
  fiber: Fiber | null;       // React internal fiber
  selector: string | null;   // CSS selector for the element
  styles: string;            // Relevant computed CSS properties
}

interface StackFrame {
  functionName: string;
  fileName: string;
  lineNumber: number;
  columnNumber: number;
}

Example:

const button = document.querySelector('.submit-btn');
const context = await getElementContext(button);

console.log(context.componentName); // "SubmitButton"
console.log(context.selector);      // "button.submit-btn"
console.log(context.stackString);
// "  in SubmitButton (at Button.tsx:12:5)
//    in Form (at Form.tsx:30:3)"
console.log(context.stack[0]);
// { functionName: "SubmitButton", fileName: "Button.tsx", lineNumber: 12, columnNumber: 5 }

freeze() / unfreeze()

freeze(elements?: Element[]): void   // Halt React updates, pause animations
unfreeze(): void                      // Restore normal behavior
isFreezeActive(): boolean             // Check if freeze is active

Freeze pauses:

• React state updates (prevents re-renders)
• CSS transitions and animations
• Preserves :hover/:focus pseudo-states

openFile(filePath, lineNumber?)

openFile(filePath: string, lineNumber?: number): Promise<void>

Opens the file in your editor. Tries Vite/Next.js dev server endpoints first, falls back to vscode:// protocol URL.

generateSnippet(elements, options?)

generateSnippet(
  elements: Element[],
  options?: { maxLines?: number }
): Promise<string[]>

Takes an array of Elements and returns an array of formatted context strings.

---

Plugin API

Plugin interface

interface Plugin {
  name: string;
  theme?: DeepPartial<Theme>;
  options?: SettableOptions;
  actions?: PluginAction[];    // ContextMenuAction[] | ToolbarMenuAction[]
  hooks?: PluginHooks;
  setup?: (api: ReactGrabAPI, hooks: ActionContextHooks) => PluginConfig | void;
}

Register / unregister

import { registerPlugin, unregisterPlugin } from "react-grab";

registerPlugin(plugin: Plugin): void
unregisterPlugin(name: string): void

PluginHooks — all lifecycle hooks

interface PluginHooks {
  onActivate?: () => void;
  onDeactivate?: () => void;
  onElementHover?: (element: Element) => void;
  onElementSelect?: (element: Element) => boolean | void | Promise<boolean>;
  // return true from onElementSelect to cancel default copy behavior

  onDragStart?: (startX: number, startY: number) => void;
  onDragEnd?: (elements: Element[], bounds: DragRect) => void;

  onBeforeCopy?: (elements: Element[]) => void | Promise<void>;
  transformCopyContent?: (content: string, elements: Element[]) => string | Promise<string>;
  onAfterCopy?: (elements: Element[], success: boolean) => void;
  onCopySuccess?: (elements: Element[], content: string) => void;
  onCopyError?: (error: Error) => void;

  onStateChange?: (state: ReactGrabState) => void;
  onPromptModeChange?: (isPromptMode: boolean, context: PromptModeContext) => void;

  // Visual hooks
  onSelectionBox?: (visible: boolean, bounds: OverlayBounds | null, element: Element | null) => void;
  onDragBox?: (visible: boolean, bounds: OverlayBounds | null) => void;
  onGrabbedBox?: (bounds: OverlayBounds, element: Element) => void;
  onElementLabel?: (visible: boolean, variant: ElementLabelVariant, context: ElementLabelContext) => void;
  onCrosshair?: (visible: boolean, context: CrosshairContext) => void;
  onContextMenu?: (element: Element, position: { x: number; y: number }) => void;

  // Transform hooks
  onOpenFile?: (filePath: string, lineNumber?: number) => boolean | void;
  transformHtmlContent?: (html: string, elements: Element[]) => string | Promise<string>;
  transformAgentContext?: (context: AgentContext, elements: Element[]) => AgentContext | Promise<AgentContext>;
  transformActionContext?: (context: ActionContext) => ActionContext;
  transformOpenFileUrl?: (url: string, filePath: string, lineNumber?: number) => string;
  transformSnippet?: (snippet: string, element: Element) => string | Promise<string>;
}

Context Menu Action

interface ContextMenuAction {
  id: string;
  label: string;
  shortcut?: string;         // Keyboard shortcut label shown in UI
  target?: "context-menu";   // Omit to place in context menu (default)
  enabled?: boolean | ((context: ActionContext) => boolean);
  onAction: (context: ContextMenuActionContext) => void | Promise<void>;
  agent?: AgentOptions;
}

interface ContextMenuActionContext extends ActionContext {
  element: Element;
  elements: Element[];
  filePath?: string;
  lineNumber?: number;
  componentName?: string;
  tagName?: string;
  enterPromptMode?: (agent?: AgentOptions) => void;
  hideContextMenu: () => void;
  cleanup: () => void;
}

Toolbar Action

interface ToolbarMenuAction {
  id: string;
  label: string;
  shortcut?: string;
  target: "toolbar";         // Required — places in the floating toolbar
  enabled?: boolean | (() => boolean);
  isActive?: () => boolean;
  onAction: () => void | Promise<void>;
}

---

Theme API

interface Theme {
  enabled?: boolean;            // Toggle entire overlay (default: true)
  hue?: number;                 // Base color 0-360 HSL (default: 0 = red)
  selectionBox?: { enabled?: boolean };   // Hover highlight box
  dragBox?: { enabled?: boolean };        // Click-drag selection area
  grabbedBoxes?: { enabled?: boolean };   // Success flash on copy
  elementLabel?: { enabled?: boolean };   // Floating cursor label
  crosshair?: { enabled?: boolean };      // Crosshair overlay
  toolbar?: { enabled?: boolean };        // Floating activation toolbar
}

// Default values
const DEFAULT_THEME: Required<Theme> = {
  enabled: true,
  hue: 0,
  selectionBox: { enabled: true },
  dragBox: { enabled: true },
  grabbedBoxes: { enabled: true },
  elementLabel: { enabled: true },
  crosshair: { enabled: true },
  toolbar: { enabled: true },
};

---

ReactGrabState

Runtime state of the overlay:

interface ReactGrabState {
  isActive: boolean;                  // Overlay is showing
  isDragging: boolean;                // User is drag-selecting
  isCopying: boolean;                 // Copy in progress
  isPromptMode: boolean;              // AI prompt mode active
  isCrosshairVisible: boolean;
  isSelectionBoxVisible: boolean;
  isDragBoxVisible: boolean;
  targetElement: Element | null;      // Currently hovered element
  dragBounds: DragRect | null;
  grabbedBoxes: Array<{
    id: string;
    bounds: OverlayBounds;
    createdAt: number;
  }>;
  labelInstances: Array<{
    id: string;
    status: SelectionLabelStatus;
    tagName: string;
    componentName?: string;
    createdAt: number;
  }>;
  selectionFilePath: string | null;
  toolbarState: ToolbarState | null;
}

---

ToolbarState

interface ToolbarState {
  edge: "top" | "bottom" | "left" | "right";  // Which screen edge
  ratio: number;        // Position along edge (0-1)
  collapsed: boolean;   // Toolbar minimized
  enabled: boolean;     // Toolbar visible
}

---

SourceInfo

interface SourceInfo {
  filePath: string;
  lineNumber: number | null;
  componentName: string | null;
}

---

AgentProvider (custom AI backend)

Connect any AI service to react-grab's prompt mode:

interface AgentProvider<T = unknown> {
  send(context: AgentContext<T>, signal: AbortSignal): AsyncIterable<string>;
  resume?(sessionId: string, signal: AbortSignal, storage: AgentSessionStorage): AsyncIterable<string>;
  abort?(sessionId: string): Promise<void>;
  supportsResume?: boolean;
  supportsFollowUp?: boolean;
  dismissButtonText?: string;
  checkConnection?(): Promise<boolean>;
  getCompletionMessage?(): string | undefined;
  undo?(): Promise<void>;
  canUndo?(): boolean;
  redo?(): Promise<void>;
  canRedo?(): boolean;
}

interface AgentContext<T = unknown> {
  content: string[];    // Array of context strings (HTML + component stacks)
  prompt: string;       // User instruction
  options?: T;
  sessionId?: string;
}

Custom provider example:

const myProvider: AgentProvider = {
  send: async function*(context, signal) {
    const response = await fetch("/api/ai", {
      method: "POST",
      body: JSON.stringify({ context: context.content, prompt: context.prompt }),
      signal,
    });
    const reader = response.body!.getReader();
    const decoder = new TextDecoder();
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      yield decoder.decode(value);
    }
  },
  supportsFollowUp: true,
};

registerPlugin({
  name: "my-ai",
  actions: [{
    id: "ask-ai",
    label: "Ask My AI",
    onAction: (ctx) => {
      ctx.enterPromptMode?.({ provider: myProvider });
    },
  }],
});

---

TypeScript Types — Full Export List

export type {
  Options,
  SettableOptions,
  ReactGrabAPI,
  SourceInfo,
  Theme,
  ReactGrabState,
  ToolbarState,
  OverlayBounds,
  GrabbedBox,
  DragRect,
  Rect,
  DeepPartial,
  ElementLabelVariant,
  PromptModeContext,
  CrosshairContext,
  ElementLabelContext,
  AgentContext,
  AgentSession,
  AgentProvider,
  AgentSessionStorage,
  AgentOptions,
  AgentCompleteResult,
  ActivationMode,
  ContextMenuAction,
  ContextMenuActionContext,
  ToolbarMenuAction,
  PluginAction,
  ActionContext,
  ActionContextHooks,
  Plugin,
  PluginConfig,
  PluginHooks,
}

---

Package Structure

---

Built-in Plugins

import { commentPlugin, openPlugin } from "react-grab";

// commentPlugin — adds "Comment" action to context menu
// openPlugin — adds "Open in editor" action to context menu
registerPlugin(commentPlugin);
registerPlugin(openPlugin);

---

MCP Server (@react-grab/mcp)

The MCP server exposes one tool:

`get_element_context`

• Returns the most recently selected element's context from the browser overlay
• Context is consumed once then cleared (one-shot)
• Returns: { componentName, filePath, lineNumber, htmlPreview, stackString, selector }

Setup: npx -y grab@latest add mcp

Transport: Supports both stdio (for editor MCP clients) and HTTP (Streamable HTTP, default port configurable).

---

Source: https://github.com/aidenybai/react-grab · License: MIT

react-grab install and routing guide

Default installation path

Use the upstream CLI from the project root:

npx -y grab@latest init

Why this is the default:

• upstream README positions init as the primary install path
• it auto-detects framework/project shape
• it keeps the main skill from teaching too many manual snippets by default

Prerequisites

Before recommending install steps, confirm:

• Node.js >=22 (upstream package.json requirement)
• project root context (where next.config.*, vite.config.*, or equivalent lives)
• development-only usage; this should not ship to production

When to stay on the default path

Stay with grab init when the user says things like:

• “set up react-grab”
• “install it in my app”
• “I want to copy element context into Claude/Cursor/Codex/Gemini”
• “make the component picker work”

When to use framework-specific setup

Only drop to manual instructions when:

• grab init cannot detect the app correctly
• the user needs to patch a specific entry point
• the user is working inside a custom setup and asks for the exact insertion point

Next.js App Router

Add to app/layout.tsx:

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        {process.env.NODE_ENV === "development" && (
          <Script
            src="//unpkg.com/react-grab/dist/index.global.js"
            crossOrigin="anonymous"
            strategy="beforeInteractive"
          />
        )}
      </head>
      <body>{children}</body>
    </html>
  );
}

Next.js Pages Router

Add to pages/_document.tsx:

import Script from "next/script";
import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        {process.env.NODE_ENV === "development" && (
          <Script
            src="//unpkg.com/react-grab/dist/index.global.js"
            crossOrigin="anonymous"
            strategy="beforeInteractive"
          />
        )}
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Vite

Add to the entry path or top-level module loaded in development:

if (import.meta.env.DEV) {
  import("react-grab");
}

Webpack

Install the package if needed, then gate it to development:

npm install --save-dev react-grab

if (process.env.NODE_ENV === "development") {
  import("react-grab");
}

Routing boundaries

Use react-grab when the real need is React element context capture.

Route elsewhere when the real need is:

• fresh disposable browser automation → browser-harness
• running-browser reuse / existing auth state → playwriter
• rendered UI review / annotation packets → agentation
• React performance / hydration / RSC / bundle issues → react-best-practices
• component-system / token / UI-architecture work → design-system or ui-component-patterns

Quick decision table

react-grab troubleshooting

First checks

Before deeper debugging, verify:

• Node.js is >=22
• install happened from the project root
• the app is running in development mode
• the overlay is loaded before the relevant React tree renders

Symptom → likely cause → fix

Quick commands

# Check Node version
node --version

# Retry default install from project root
npx -y grab@latest init

# Add MCP workflow
npx -y grab@latest add mcp

# Remove an integration
npx -y grab@latest remove <agent>

When to escalate out of react-grab

Escalate when the issue is really about:

• full browser automation, auth state, navigation, screenshots, or replay → browser-harness / playwriter
• visual review packets, layout comments, rendered annotations → agentation
• React performance, hydration, bundle size, or rerender churn → react-best-practices

Truthfulness rule

Do not keep repeating the local helper-script story if upstream has moved. For prerequisite disputes, prefer the current upstream raw sources:

• README.md for install shape
• package.json for runtime requirements