Agentic React is a monorepo for React runtime inspection and local-dev MCP integrations. The packages are published under the @agentic-react namespace.
@agentic-react/core: bundler-agnostic browser runtime, React selection toolkit, and MCP primitives.@agentic-react/vite: Vite adapter for local dev.@agentic-react/webpack: Webpack adapter for local dev.@agentic-react/next: Next.js adapter for local dev.
For full local-dev features, install the adapter for your bundler. The adapter depends on @agentic-react/core internally, so app users do not need to import both packages.
Run the release automation smoke test locally with:
pnpm run test:release-smokeThe test does not publish to npm or call GitHub. It reads
.github/workflows/release.yml, creates temporary git fixtures, and uses fake
pnpm and gh commands for the release automation branches.
It protects the release regressions fixed in this workflow:
- pending changeset detection ignores
.changeset/README.md, runsversion-packagesonly when a real changeset Markdown file exists, commitschore: version packages, and pushes that commit back tomain - the release workflow remains a
mainpush workflow and keeps publish order as version, build, publish, tag push, GitHub release creation - package tags created during publishing are pushed with
git push origin --tags - GitHub releases are selected from tags that point at
HEADand filtered to@agentic-react/*, so stale package tags and non-package tags do not create releases
pnpm install @agentic-react/vite -D// vite.config.ts
import { defineConfig } from 'vite';
import AgenticReact from '@agentic-react/vite';
export default defineConfig({
plugins: [AgenticReact()],
});The Vite adapter injects the core browser runtime, attaches the runtime bridge to the dev server, and exposes MCP over:
http://localhost:<vite-port>/mcp
pnpm install @agentic-react/webpack -D// webpack.config.mjs
import withAgenticReactWebpack from '@agentic-react/webpack';
export default (env, argv) =>
withAgenticReactWebpack(config, { mode: argv.mode });The Webpack adapter prepends a generated runtime entry, attaches the runtime bridge to webpack-dev-server, and exposes MCP at:
http://localhost:<webpack-dev-server-port>/mcp
pnpm install @agentic-react/next -D// next.config.mjs
import withAgenticReactNext from '@agentic-react/next';
export default withAgenticReactNext(nextConfig);The Next adapter injects the browser runtime through Next's Webpack config and starts a local bridge server. By default MCP is available at:
http://127.0.0.1:51426/mcp
Use @agentic-react/core directly when you only need browser-side selection/runtime APIs and do not need local source-file lookup or MCP dev-server wiring.
pnpm install @agentic-react/coreimport { createSelectionToolkit } from '@agentic-react/core';
const toolkit = createSelectionToolkit();
toolkit.enable();Runtime-only mode can inspect the live browser tree, but it cannot read or edit local files. Source lookup and local MCP transport are the adapter layer's job.
@agentic-react/core runs in the browser and can select elements, inspect React fibers, highlight components, format selection context, and expose window.__AGENTIC_REACT__ / window.__AGENTIC_REACT_TOOLS__.
Bundler adapters add local-dev capabilities that the runtime cannot know on its own:
- inject the core runtime automatically
- attach a local MCP Streamable HTTP
/mcpendpoint - bridge MCP calls from Node to the browser runtime
- provide local source-root context for source lookup
- keep dev-only tooling out of production bundles
The selection overlay includes a tuning modal for turning visual adjustments into prompt text. Configure it through the adapter toolkit option, or at runtime with window.__AGENTIC_REACT__.setToolkitConfig().
import type { ToolkitConfig } from '@agentic-react/vite';
// Import ToolkitConfig from the adapter package you use.
const toolkit: ToolkitConfig = {
enabled: true,
defaultVisible: true,
defaultExpanded: false,
position: 'bottom-right',
offset: { x: 20, y: 20 },
accentColor: '#111827',
zIndex: 2147483000,
iconUrl: '/agentic-react-logo.png',
tuningModal: {
classNames: {
surface: 'my-tuning-surface',
panel: 'my-tuning-panel',
control: 'my-tuning-control',
},
styles: {
panel: { border: '1px solid rgba(15, 23, 42, 0.18)' },
targetTag: { background: '#f8fafc', color: '#0f172a' },
},
tokens: {
panelRadius: '14px',
controlRadius: '10px',
primaryButtonBackground: '#0f766e',
primaryButtonColor: '#ffffff',
panelShadow: '0 24px 72px rgba(15, 118, 110, 0.22)',
},
},
};tuningModal.classNames adds classes to modal slots. tuningModal.styles applies inline style objects to the same slots. Supported slots are root, surface, panel, arrow, title, body, targetTag, customPromptForm, customPromptInput, customPromptButton, sectionTitle, row, label, controlWrap, control, colorInput, numberInput, stepperButton, select, textarea, suffix, and closeButton.
tuningModal.tokens maps camelCase token names to CSS variables prefixed with --agentic-react-tuning-. For example, panelRadius becomes --agentic-react-tuning-panel-radius, and primaryButtonBackground becomes --agentic-react-tuning-primary-button-background. Built-in controls currently read tokens such as panelBackground, panelBorder, panelRadius, panelShadow, panelColor, controlBorder, controlRadius, controlBackground, controlColor, labelColor, sectionColor, primaryButtonBorder, primaryButtonBackground, primaryButtonColor, secondaryButtonBackground, and secondaryButtonColor.
Adapters pass the config as:
// Vite
AgenticReact({ toolkit });
// Webpack
withAgenticReactWebpack(config, { mode: 'development' }, { toolkit });
// Next.js
withAgenticReactNext(nextConfig, { toolkit });For structural extensions, register a browser-side tuning modal extension. Slot renderers can add custom DOM before fields, after fields, or in the footer. wrapModal receives the modal surfaceElement and panelElement, which lets design systems add wrappers, data attributes, observers, portals, or cleanup-aware behavior around the rendered modal.
const unregister = window.__AGENTIC_REACT__?.registerTuningModalExtension({
id: 'design-system-audit',
beforeFields({ container, context }) {
const badge = document.createElement('div');
badge.textContent = `Editing ${context.tagName}`;
badge.className = 'agentic-design-system-badge';
container.appendChild(badge);
},
wrapModal({ surfaceElement, actions }) {
surfaceElement.dataset.designSystem = 'acme';
const onTransitionEnd = () => actions.requestReposition();
surfaceElement.addEventListener('transitionend', onTransitionEnd);
return () => {
surfaceElement.removeEventListener('transitionend', onTransitionEnd);
};
},
});Concrete playground example:
// playground/agentic-react-vite-playground/vite.config.js
AgenticReact({
toolkit: {
iconUrl: '/agentic-react-logo.png',
tuningModal: {
classNames: {
surface: 'vite-playground-tuning-surface',
panel: 'vite-playground-tuning-panel',
control: 'vite-playground-tuning-control',
},
tokens: {
panelRadius: '14px',
controlRadius: '10px',
primaryButtonBackground: '#0f766e',
primaryButtonColor: '#ffffff',
panelShadow: '0 24px 72px rgba(15, 118, 110, 0.22)',
},
styles: {
surface: {
filter: 'drop-shadow(0 18px 40px rgba(15, 118, 110, 0.16))',
},
panel: {
border: '1px solid rgba(15, 118, 110, 0.22)',
},
targetTag: {
background: '#ecfeff',
color: '#0f766e',
},
sectionTitle: {
color: '#0f766e',
},
},
},
},
});Adapters accept browser-side custom tools. Import shared types from the adapter package you use:
import type { ToolResultValue } from '@agentic-react/vite';
export default function logMessage(args: { message: string }): ToolResultValue {
return {
success: true,
message: `Received: ${args.message}`,
};
}import { defineConfig } from 'vite';
import AgenticReact from '@agentic-react/vite';
import { z } from 'zod';
import logMessage from './src/tools/logMessage';
export default defineConfig({
plugins: [
AgenticReact({
customTools: [
{
name: 'log-message',
description: 'Log a message in the browser runtime',
schema: z.object({ message: z.string() }),
clientFunction: logMessage,
},
],
}),
],
});pnpm run build
pnpm run playground:vite
pnpm run playground:webpack
pnpm run playground:next
pnpm run playground:nx-mfFor e2e automation, Playwright uses fixed local ports configured in the playground package configs.
This project is inspired by vite-plugin-vue-mcp.
MIT