DevTools

Instrumentation and React hooks for inspecting model cache, vector database stats, inference queue metrics, pipeline execution traces, and live event streams in LocalMode applications.

Overview

@localmode/devtools provides headless instrumentation (enableDevTools()) plus React hooks (@localmode/devtools/react) that give you full visibility into your local AI application at runtime — all without any telemetry or data leaving your device. The hooks are the primary integration path: subscribe to any slice of the observability bridge and render it in your own UI, with your own styling.

What you can observe

• Models — Cached models, load times, status
• VectorDB — Collections, document counts, search stats
• Queue — Live inference queue: pending, active, completed, latency
• Pipeline — Step execution traces with timings
• Events — Live event stream with filtering
• Device — WebGPU, WASM, Chrome AI, WebNN capabilities
• Storage — Storage quota usage

Installation

pnpm add -D @localmode/devtools

Quick Start

Enable instrumentation once, then subscribe to any data domain with a hook:

import { enableDevTools } from '@localmode/devtools';
import { useDevToolsQueueStats, useDevToolsEvents } from '@localmode/devtools/react';

if (process.env.NODE_ENV === 'development') {
  enableDevTools();
}

function Observability() {
  const queues = useDevToolsQueueStats();
  const events = useDevToolsEvents({ types: ['vectordb'], limit: 50 });

  return (
    <div>
      {Object.entries(queues).map(([name, stats]) => (
        <p key={name}>{name}: {stats.pending} pending, {stats.active} active</p>
      ))}
      {events.map((e) => (
        <p key={e.id}>{e.type}</p>
      ))}
    </div>
  );
}

If you only want instrumentation without any UI, calling enableDevTools() alone is enough — data is written to the bridge and you can inspect window.__LOCALMODE_DEVTOOLS__ directly.

React Hooks

@localmode/devtools/react exports nine hooks — one per bridge data domain — all built on useSyncExternalStore with version-keyed immutable snapshots:

Guarantees shared by all hooks:

• Subscribe on mount, fully unsubscribe on unmount — no leaks
• SSR-safe — no window access during server render; inert values on the server
• Inert when devtools is absent — referentially stable fallback values; no errors in production builds
• Late-enable attachment — a hook mounted before enableDevTools() attaches once the bridge appears, no remount needed
• Immutable snapshots — slice hooks return fresh copies per notification; they never alias the bridge's mutable objects

How It Works

enableDevTools() subscribes to existing observability hooks in @localmode/core:

• globalEventBus for VectorDB and embedding events
• queue.on('stats') for inference queue metrics
• onProgress callbacks for pipeline step traces
• getStorageQuota() for storage usage
• detectCapabilities() for device features

Data is written to window.__LOCALMODE_DEVTOOLS__. The React hooks read this bridge directly via subscribe() for instant, non-polling updates. Zero core changes needed — DevTools is a pure read-only visualization layer.

DevToolsWidget (removed in v3.0.0)

See Data Domains for the six domains the bridge collects — each maps 1:1 to a /react hook, a ui/devtools primitive, and a tab of the drawer.

Requirements

• @localmode/core ^1.0.0 (peer dependency)
• react >=18.0.0 (peer dependency, only for the /react hooks)

Composed Block