Inspekt

A multi-framework element inspector for developers. Inspect an instrumented UI element to see its source, navigate the component tree, and take action.

• Framework adapters — React, Vue, Svelte, Solid, and a generic DOM fallback
• Bundler plugins — Vite, Webpack, Rspack, esbuild, and Rollup
• Docker-aware — auto-detects path mappings from docker-compose.yaml
• Component tree — full hierarchy with props, search, and highlighting
• Custom actions — open in IDE, copy path, open on GitHub, or add your own
• Chrome extension — global settings that sync across all your projects
• Agent integration — grab an element and hand it to Claude Code, Cursor, Codex, Gemini CLI, or Antigravity over MCP
• Small runtime — nothing runs when disabled; the core bundle is ~23 KB gzipped (its dependencies are external)

Quick Start

For published versions and exact publication dates, see the public Vite package registry metadata. Its versions and time fields are package history, separate from studio notes and the unreleased changes in this checkout. A publication date is not proof of successful operation on every platform.

npm install -D @aylith/inspekt-vite

// vite.config.ts
import { defineConfig } from 'vite';
import { inspekt } from '@aylith/inspekt-vite';

export default defineConfig({
  plugins: [
    // Keep your existing framework plugins here (for example react()).
    inspekt({
      editor: 'cursor',     // or 'vscode', 'webstorm', 'zed', ...
    }),
  ],
});

Start your existing dev script (usually npm run dev), open its reported URL, and use Ctrl+Alt+Click on an element. Ordinary clicks keep working. The popover should show the actual file and line; expand Show source for a snippet and use Copy path to take the reference back to your editor. Escape closes it.

The Vite route needs no Chrome extension, daemon or coding-agent setup. Keep the server local; editor launching requires your chosen editor to be installed.

Current Windows release limitation: a clean Windows test of published @aylith/[email protected] / @aylith/[email protected] found that normalized C:/... paths fall back to DOM-only inspection. The published plugin also uses the configured rather than actual server origin and leaves a dev-module link in production HTML. Corrections in this checkout are not a published package update. See the first-use verification procedure; other platforms and framework versions need their own acceptance checks.

Linux local-package proof (24 September 2026): from source revision 52623f4f4ebe66d6b63000ebb75cfab306da0fb3, locally packed core 0.4.0, CLI 0.1.0 and Vite 0.2.1 archives installed into a fresh isolated React 19/Vite 8 consumer. In system Chromium, an ordinary click still worked; Ctrl+Alt+Click identified the actual src/main.jsx:8:5:button, Show source returned that file's exact button line, and Copy Path returned its exact file:line. Reload, Escape, keyboard toggle, narrow dark/reduced-motion placement, a denied outside-root snippet request and a production build without the inspector also passed. The repeatable proof is scripts/vite-first-use-proof.mjs; its --local-tarballs mode now consumes core, CLI and Vite archives and accepts --temp-base, --playwright and --chromium for Linux. The core/CLI/Vite archive SHA-256 values were 4a03329ba5a8290276c17d1d462c1110cd55817cdccaaee052ef695f06dd9ff8, d7d14bfa9e9d4e91de22aacb796bdae5b057ce6b991aeef0a57fe45c5c3d39d0 and 5526dbd5fa739ce7471ee3c4353dc2dc7a0e4ae946e10e53649a6f7acd50cd4d. The full local test graph passed 21/21 tasks with a task-owned TMPDIR passed through Turbo's environment. This does not verify current npm registry bytes, Windows or macOS, other frameworks, editor/daemon/agent enrollment or an unaided first-time user; it is not a package publication or public release.

Keyboard Shortcuts

Shortcut	Action
Ctrl+Alt+Click	Inspect element (show popover with actions)
Shift+Alt+Click	Open file in IDE immediately
Ctrl+Alt+I	Toggle Inspekt on/off
Ctrl+Alt+O	Toggle overlay (component name badges)
Ctrl+Alt+T	Toggle component tree panel
Escape	Close popover / tree panel

On Mac, Cmd replaces Ctrl.

Packages

Package	Description
@aylith/inspekt	Published runtime, plugins and agent tools, with inspekt, inspekt-daemon, and inspekt-mcp commands; the source-built Chrome extension is separate
@aylith/inspekt-core	Runtime UI — overlay, popover, tree panel, highlighting. Pure vanilla JS/CSS in Shadow DOM
@aylith/inspekt-vite	Vite plugin — injects source location attributes at build time
@aylith/inspekt-bundlers	Webpack, Rspack, esbuild, and Rollup plugins (via unplugin)
@aylith/inspekt-cli	CLI utility — open files in IDE from terminal
@aylith/inspekt-chrome	Chrome extension — global settings and standalone inspector
@aylith/inspekt-daemon	Localhost HTTP server holding the grab queue the extension writes to
@aylith/inspekt-mcp	MCP server exposing the grab queue to agents over stdio
@aylith/inspekt-skill

Bundler Setup

Vite

import { inspekt } from '@aylith/inspekt-vite';

export default defineConfig({
  plugins: [inspekt()],
});

Webpack

import { webpack } from '@aylith/inspekt-bundlers';

module.exports = {
  plugins: [webpack()],
};

Rspack / Rsbuild

import { rspack } from '@aylith/inspekt-bundlers';

module.exports = {
  plugins: [rspack()],
};

esbuild

import { esbuild } from '@aylith/inspekt-bundlers';

await build({
  plugins: [esbuild()],
});

Plugin Options

inspekt({
  // Framework detection (auto-detected if omitted)
  framework: 'react',              // 'react' | 'vue' | 'svelte' | 'solid' | 'auto'

  // IDE to open files in
  editor: 'cursor',                // 'vscode' | 'cursor' | 'webstorm' | 'zed' | ...

  // Docker path mapping (auto-detect from docker-compose)
  dockerCompose: true,

  // Or manual mapping
  pathMapping: {
    '/app/': '/home/user/projects/my-app/',
  },

  // File filtering
  include: ['src/**/*.{tsx,jsx,vue,svelte}'],
  exclude: ['node_modules/**', '**/*.test.*'],
});

Docker Support

When your app runs in a Docker container, file paths point to container paths (/app/src/...). Inspekt fixes this automatically:

// Auto-detect from docker-compose.yaml volume mounts
inspekt({ dockerCompose: true });

// Or specify manually
inspekt({
  pathMapping: {
    '/app/': process.cwd() + '/',
  },
});

Custom Actions

Add your own actions to the inspector popover:

import { createInspekt } from '@aylith/inspekt-core';

const inspekt = createInspekt();

inspekt.registerAction({
  id: 'open-jira',
  label: 'Search Jira',
  icon: '<svg>...</svg>',
  handler(element) {
    window.open(`https://jira.example.com/search?q=${element.componentName}`);
  },
});

Events

inspekt.on('inspect', (element) => {
  console.log('Inspected:', element.filePath, element.componentName);
});

inspekt.on('action', (actionId, element) => {
  console.log('Action:', actionId, 'on', element.componentName);
});

Chrome Extension

The Chrome extension provides:

• Global settings — configure your IDE, theme, and shortcuts once for all projects
• Standalone mode — inject Inspekt into any page, even without a build plugin
• Per-site overrides — different settings for different projects
• Settings sync — chrome.storage.sync across devices

The Vite quick-start does not require this extension. There is no verified Chrome Store installer yet. For the optional source-built extension, use the repository-root dist/ directory after building, then load it unpacked in Chrome's developer mode.

Agent Integration

npx @aylith/inspekt setup generates a token, writes it to ~/.inspekt/config.json, and registers the Inspekt MCP server with every agent it finds installed (Claude Code, Cursor, Codex, Gemini CLI, Antigravity).

With the daemon running (inspekt-daemon), "Send to Agent" in the popover appends the grabbed element — file, line, component, surrounding source, page URL — to a shared queue. The agent reads it through the MCP tools grab_latest, list_grabs, get_grab, mark_grab_processed, clear_queue, and open_grab_in_editor, so "fix this button" resolves to a real file and line.

Every mutating daemon route requires the X-Inspekt-Token header. The token and handshake files are written owner-only.

Supported IDEs

VS Code, VS Code Insiders, Cursor, Windsurf, WebStorm, PhpStorm, PyCharm, IntelliJ IDEA, Sublime Text, Zed, Vim/Neovim, Emacs.

How It Works

1. Build time — The bundler plugin injects data-insp-path attributes onto every component's root element with the source file path, line, and column
2. Runtime — When you Ctrl+Alt+Click, Inspekt walks up the DOM to find the nearest data-insp-path, shows a popover with actions, and highlights the element
3. Component tree — Framework-specific adapters (React Fiber, Vue instances, Svelte context, Solid owner) build the full component hierarchy for the tree panel

All Inspekt UI renders inside Shadow DOM to prevent any style conflicts with your app.

Development

git clone https://github.com/aylith-labs/inspekt.git
cd inspekt
bun install
bun run build
bun run --filter 'inspekt-playground' dev

The checks CI runs, in order:

bun run lint            # biome check .
bun run typecheck
bun run test
bun run build
bun run verify:exports  # declared entrypoints resolve against the built output

License

MIT