@lensmcp/nx-plugin

Nx plugin that wires LensMCP — the observability lens for coding agents — into your workspace.

LensMCP gives coding agents (Claude Code, Cursor, and other MCP clients) a live view into the app they are building: frontend events captured from a real Chrome session, backend traces from the running server, and deterministic build/verify reports. This plugin is the integration layer for Nx workspaces. Its executors run a host app or server under the lens, and its generators scaffold the wiring so you do not have to edit configs by hand.

In practice you run init once per workspace, run setup-vite / setup-nest once per project, then drive everything through the agent-dev, agent-build, and agent-verify targets the generators add for you.

Install

yarn add -D @lensmcp/nx-plugin

Then register the plugin and scaffold the workspace wiring with the init generator:

nx g @lensmcp/nx-plugin:init

This is also run for you by lensmcp install (the lensmcp CLI). init is idempotent — safe to re-run.

Generators

| Generator | Purpose | Invocation | | --- | --- | --- | | init | Install LensMCP into the host Nx workspace: register the plugin in nx.json, add the workspace-wide lensmcp config block, patch .gitignore, and prepare the .lensmcp runtime directory. | nx g @lensmcp/nx-plugin:init | | setup-vite | Wire LensMCP into a Vite project: add @lensmcp/vite-plugin to its vite.config.ts and add an agent-dev target. | nx g @lensmcp/nx-plugin:setup-vite | | setup-nest | Wire LensMCP into a NestJS project: register LensmcpModule.forRoot() in the AppModule and add an agent-dev target. | nx g @lensmcp/nx-plugin:setup-nest |

Options

init

| Option | Type | Default | Description | | --- | --- | --- | --- | | registerHostConfig | "auto" | "never" | "always" | auto | Whether to also append a lensmcp entry to the host agent's MCP client config (~/.claude/mcp.json, ~/.cursor/mcp.json, <workspace>/.mcp.json). auto patches existing files only and never modifies anything outside the workspace by default. | | skipFormat | boolean | false | Skip Prettier formatting of touched files. |

setup-vite / setup-nest

| Option | Type | Default | Description | | --- | --- | --- | --- | | project | string | (required) | Target Nx project. For setup-vite it must already have a vite.config.ts; for setup-nest it must have an app.module.ts and main.ts. | | skipFormat | boolean | false | Skip Prettier formatting of touched files. |

Executors

| Executor | Purpose | | --- | --- | | agent-dev | Start a project under the LensMCP lens — runs the dev server alongside a Chrome capture sidecar and the MCP server so agents observe the live app. | | agent-build | Run an instrumented production build that produces a bundle report and updates the baseline. | | agent-verify | Deterministic verification loop — typecheck, lint, then build — with a per-run report under .lensmcp/verifications/. |

agent-dev

Runs a host project (vite-react, nestjs, or nextjs) and attaches the lens. For Vite-React it starts the dev server and a Chrome sidecar pointed at the dev URL so frontend events are captured live.

| Option | Type | Default | Description | | --- | --- | --- | --- | | kind | "vite-react" | "nestjs" | "nextjs" | vite-react | Host project type. | | devTarget | string | — | Nx target that starts the host's dev server (e.g. web:serve). If omitted, the executor runs vite on the current project. | | projectRoot | string | — | Override the project root passed to Vite. Defaults to the running project's root. | | chrome | boolean | true | Launch a Chrome sidecar attached to the dev URL. | | headless | boolean | true | Run the Chrome sidecar headless. | | port | number | — | Override the dev port. Defaults to the project's vite.config.ts setting or 5173. | | openUrl | string | — | Override the URL Chrome navigates to. |

agent-build

| Option | Type | Default | Description | | --- | --- | --- | --- | | kind | "vite-react" | vite-react | Host project type. | | projectRoot | string | — | Override the project root passed to Vite. Defaults to the running project's root. | | updateBaseline | boolean | true | On success, write the resulting bundle report to .lensmcp/baseline/bundle.json. |

agent-verify

| Option | Type | Default | Description | | --- | --- | --- | --- | | kind | "vite-react" | vite-react | Host project type. | | projectRoot | string | — | Override the project root. Defaults to the running project's root. | | skipTypecheck | boolean | false | Skip the typecheck phase. | | skipLint | boolean | false | Skip the lint phase. | | skipBuild | boolean | false | Skip the build phase. |

Usage

The setup-vite / setup-nest generators add an agent-dev target for you. A Vite-React project's project.json ends up looking like this:

{
  "name": "web",
  "targets": {
    "agent-dev": {
      "executor": "@lensmcp/nx-plugin:agent-dev",
      "options": {
        "kind": "vite-react",
        "chrome": true,
        "port": 5173
      }
    }
  }
}

Then run the host under the lens:

# Serve the app + Chrome capture sidecar + MCP server
nx run web:agent-dev

# Non-headless Chrome on a custom port
nx run web:agent-dev --headless=false --port=4200

# Instrumented build that refreshes the bundle baseline
nx run web:agent-build

# Deterministic typecheck → lint → build, report under .lensmcp/verifications/
nx run web:agent-verify

For a NestJS host, set up the project and run its target the same way:

nx g @lensmcp/nx-plugin:setup-nest --project=api
nx run api:agent-dev --kind=nestjs

How it fits

@lensmcp/nx-plugin is the wiring layer; the actual capture happens through framework-specific packages it installs:

• Frontend — setup-vite adds @lensmcp/vite-plugin to your vite.config.ts. Combined with the Chrome sidecar that agent-dev launches, this streams real browser events into the lens.
• Backend — setup-nest registers LensmcpModule.forRoot() (from @lensmcp/node-instrumentation) in your NestJS AppModule, so server-side traces flow into the lens.

The plugin pairs with the rest of the LensMCP toolchain: the lensmcp CLI (which can run init for you via lensmcp install) and @lensmcp/cluster for the gateway/registry that routes traffic between agents and instrumented apps.

Part of LensMCP. Apache-2.0.