OpenMax
Free Trial

Devtools

The Chat SDK 3.0 Devtools — a read-only overlay that shows, for every open conversation, its window in the message store, the change log, sends, local storage, the realtime connection and the latest store events. Its own entry, not in your bundle unless you import it.

Devtools

Devtools is a read-only panel floating over the page, for developing and testing an SDK integration. When a message goes missing, shows up twice, lands out of order, or does not come back after a reconnect, open it and you see what the message store thinks right now, without adding logs or reproducing the bug a second time. The idea is the same as React Query Devtools: a separate entry, and you decide in which environments it is imported and how it opens.

What it is

  • One entry in the SDK. The panel ships with @openmaxai/chat-sdk, under the @openmaxai/chat-sdk/devtools entry. Import it only from there; there is nothing else to install.
  • Not in your bundle unless you import it. No other @openmaxai/chat-sdk entry references it; if your code does not import @openmaxai/chat-sdk/devtools, your bundle contains none of the panel's code.
  • You pick the environments and how it opens. The panel does not look at NODE_ENV and does not decide whether it is running in production: which environments import it, and which shortcut or URL parameter opens it, is decided in your host.
  • Read-only. The panel reads only through the store's public inspection API: it never writes to the store, sends no requests and does not touch local storage, so mounting, opening or closing it changes nothing about how chat behaves. See Read-only guarantee.

Install and import

The panel comes with @openmaxai/chat-sdk; there is nothing else to install. Put ChatDevtools anywhere inside ChatProvider. It reads the store and the realtime connection of that provider's host:

app.tsx

import { ChatDevtools } from "@openmaxai/chat-sdk/devtools";
import { ChatProvider } from "@openmaxai/chat-sdk/react";

export function App() {
  return (
    <ChatProvider host={host}>
      <Chat />
      <ChatDevtools />
    </ChatProvider>
  );
}

Written like this, the panel ends up in the bundle of every environment. To have it only outside production, see Enable it outside production only below.

Once mounted, ChatDevtools starts closed: it only adds a keyboard listener to the page and draws nothing.

Enable it outside production only

Use a dynamic import() behind a constant that is known at build time. When the constant is false the bundler drops the whole branch, import() included, so the production bundle has none of the panel's code, and the URL parameter and the shortcut do nothing.

chat-devtools-slot.tsx

import { lazy, Suspense } from "react";

// Build-time constant: the literal false in production builds, so the branch below is removed.
const devtoolsEnabled = process.env.NODE_ENV !== "production";

const ChatDevtools = devtoolsEnabled
  ? lazy(() =>
      import("@openmaxai/chat-sdk/devtools").then((m) => ({ default: m.ChatDevtools })),
    )
  : null;

export function ChatDevtoolsSlot() {
  if (!ChatDevtools) return null;
  return (
    <Suspense fallback={null}>
      <ChatDevtools shortcut="Alt+Shift+D" urlParam="chat-devtools" />
    </Suspense>
  );
}

app.tsx

<ChatProvider host={host}>
  <Chat />
  <ChatDevtoolsSlot />
</ChatProvider>

Use a constant your build tool replaces at build time (NEXT_PUBLIC_* in Next.js, import.meta.env.* in Vite). A value known only at run time (say, a flag read from your API) works too, but then the panel's code stays in your bundle, as a chunk split off by import() and loaded on demand.

How to open it

How Default Notes
Shortcut Alt+Shift+D Press once to open, again to close. Change it with shortcut, turn it off with false. Works while focus is in an input too
URL parameter chat-devtools When the page URL has ?chat-devtools=1, the panel opens on load. Rename it with urlParam, turn it off with false. Read once, at load
You control it — Pass open and onOpenChange and decide when it opens (say, a switch on a settings page). The shortcut and the URL parameter then call onOpenChange

Once open, the panel floats in a corner of the page, does not block clicks on the chat, and can be collapsed to a small button.

What it shows

At the top is a conversation picker: it lists the open conversations right now (the ones gap-fill follows) and selects the most recently opened one. You can also pick a conversation the store loaded and has since closed (only its watermark is left then). Below, sections show the state of the selected conversation, then the global storage, the realtime connection and the event log. The panel refreshes when the data changes, at most once per frame.

Window

The conversation's loaded range in memory.

Shows Notes
seq range The first and last seq the range covers, and whether there is older / newer
Count Server messages in the range, and the limit (500). Local messages do not count; they are under Sends
Watermark The highest seq received without a gap
Gaps seq stretches the store knows it does not have: between the end of the range and the watermark (a late window, or the message at the watermark was deleted), or after the watermark, from a push that arrived but could not be attached. "None" when there are none
Gap-fill Running now (and whether another run is queued after it); the last gap-fill's trigger, outcome (caughtUp, reloaded and so on), number of rounds and how long ago

Change log

Progress of catching up on changes from the change log.

Shows Notes
Local change watermark The last change applied in this conversation
Server head The latest change number last read from the server. Higher than the local change watermark means changes are still missing
Early numbers Change numbers that arrived ahead of a jump in the pushes, waiting for the ones before them
Last catch-up Outcome, how many change-log rounds, how many messages were fetched by id, how many were gone, and whether the server said "too old" (tooOld; the latest window was swapped in, or the local segment dropped)

Sends

Shows Notes
Local messages Messages that are sending, failed, blocked, or confirmed but not yet matched with the server's copy: client_msg_id, state, and the server message id once matched
Changes in flight Messages with your own reaction, edit or recall still pending, and those whose request succeeded and are waiting for the server's copy to bring the new content

Local storage

Shows Notes
Storage IndexedDB, memory, or a ChatStorage of your own; when IndexedDB is configured but memory is in use, the reason (another tab holds the lock, the browser has no Web Locks, IndexedDB would not open)
Tab lock Whether this tab holds the lock on local data
Encryption Whether encryption at rest is on
Approximate size The browser's estimate of storage used by the site and its quota (the whole site, not only chat), read when the panel opens and refreshable by hand
Writes Writes queued and not done yet, the reason and time of the last failed write, how many conversations were evicted for quota
This conversation Whether the range is being written locally, and the seq range of the local segment

Realtime

Shows Notes
Connection state What the SDK sees of the connection: idle (no chat view has subscribed yet, so the adapter has not been asked to connect), started (the adapter was asked to connect; it does not report whether it is connected right now or reconnecting), closed (the host was disposed), or off (the adapter has no realtime channel)
Connection status (later) The same value as useConnectionStatus (connected, reconnecting and so on) and whether gap-fill keeps failing, once that hook exists Planned
Last frame When the adapter last handed the SDK an inbound signal. Heartbeats are not signals, so on a quiet conversation this ages even while the connection is fine
Last signal The last realtime signal the gap-fill scheduler got (new messages, reconnected, a jump in change numbers) and which conversation it was for

Event log

The latest 50 store events, newest first. Each is one dispatch (type, conversation, the message ids and seq involved, and who sent it: your code, gap-fill, the thread loader or a read-back from local data) with the change it made to the range; gap-fill starting and ending, local data being opened, cleared, or failing to write are in it too. You can filter by conversation.

The Copy button copies the 50 entries to the clipboard as JSON, ready to paste into an issue. By default it leaves out message text and attachment names and keeps fields like ids, seq and states; pass includeMessageContent to include the text. Recording starts when the panel mounts and goes on while it is closed, so when you open it you see what happened before.

Read-only guarantee

  • Reads only the store's public inspection API. Everything the panel gets is a copy of a snapshot. It does not call dispatch, the gap-fill scheduler or the thread loader, calls no ChatStorage method, and makes no network request.
  • Does not change how chat behaves. Mounting, opening, closing or unmounting the panel leaves messages, gap-fill, local storage and the realtime connection behaving exactly as without it. The inspection API's own guarantees: Inspection API · Guarantees.
  • Leaves nothing behind. The panel writes nothing to localStorage, sessionStorage, IndexedDB or cookies, and is closed again after a reload (unless the URL parameter is there).
  • Copy goes to the clipboard only. The panel uploads nothing.

Hosts without the SDK

A host that uses @openmaxai/chat-store directly, without ChatProvider, imports ChatDevtoolsPanel from @openmaxai/chat-sdk/devtools and passes the store in. For the realtime section pass connection; without it the section is hidden:

store-devtools.tsx

import { ChatDevtoolsPanel } from "@openmaxai/chat-sdk/devtools";

<ChatDevtoolsPanel
  store={store}
  connection={() => ({ status: socket.status, lastFrameAt: socket.lastFrameAt })}
/>;

API

ChatDevtools

Import from @openmaxai/chat-sdk/devtools; must be inside ChatProvider.

Prop Type Default Description
shortcut string | false "Alt+Shift+D" Shortcut to open and close, keys joined with +; modifiers are Ctrl, Alt, Shift, Meta, and Mod is Meta on macOS and Ctrl elsewhere. Keys are matched by physical position (event.code), so input methods and keyboard layouts do not matter. false adds no listener
urlParam string | false "chat-devtools" Opens on load when the URL has this parameter (with the value 1 or true). false does not read it
defaultOpen boolean false Uncontrolled: whether it starts open
open boolean — Controlled: whether it is open
onOpenChange (open: boolean) => void — Called when the shortcut, the URL parameter or the panel's close button wants to change whether it is open
position "bottom-right" | "bottom-left" | "top-right" | "top-left" "bottom-right" Which corner it floats in
includeMessageContent boolean false Show and copy message text and attachment names in the event log

ChatDevtoolsPanel

Import from @openmaxai/chat-sdk/devtools; needs no ChatProvider. Takes every prop of ChatDevtools, plus:

Prop Type Description
store ChatStore Required. A store made by createChatStore
connection () => { status: string; lastFrameAt?: number } Optional. Reads the realtime connection's state and the time of its last frame (a millisecond timestamp). Called whenever the panel refreshes, so it must be cheap and free of side effects

Entry and package

Entry What is in it Depends on
@openmaxai/chat-sdk/devtools ChatDevtools, which takes the store and the connection from ChatProvider; ChatDevtoolsPanel, which takes the store you pass in Reads the store only through @openmaxai/chat-store/inspect; peer react 19

The panel's styles ship with the entry and apply only inside the panel's own root element. There is no CSS to import, and your theme variables do not affect it.

FAQ

What happens when a user presses the shortcut in production? With the pattern in Enable it outside production only, the production bundle has no panel code and nothing happens. With a plain static import, anyone who presses the shortcut can open it; the panel is read-only, but it shows message ids and conversation ids.

Does the panel slow chat down? While closed, it appends one entry to a 50-entry ring buffer per store event and redraws nothing. While open, it redraws at most once per frame. The cost on the store's side: Inspection API · Guarantees.

Can it see another tab's data? No. It shows the store in this tab; when another tab holds the lock on local data, this one shows "memory (another tab holds the lock)".