---
description: "Mounts the floating devtools panel (launcher bottom-right, Alt+Shift+A) on a page."
---

# `installWebAgentsDevtools`

Mounts the floating devtools panel (launcher bottom-right, `Alt+Shift+A`) on a page. [`<WebAgentsProvider>`](/docs/reference/react/web-agents-provider) calls it for you in development, with its own cursor; reach for it on a page built on [`createWebAgents`](/docs/reference/core/create-web-agents) (no React of yours), or one line in a framework-neutral entry file. React still renders the panel, into its own root and shadow DOM.

## Import

```ts
import { installWebAgentsDevtools } from "@webmcp-agents/devtools";
import type { DevtoolsOptions } from "@webmcp-agents/devtools";
```

## Example

Start the tools and the agent cursor, then the panel: its Settings switches drive that cursor.

```ts title="src/devtools.ts"
import { createWebAgents } from "@webmcp-agents/core";
import { installWebAgentsDevtools } from "@webmcp-agents/devtools";

import { tools } from "@/tools";

// A page without <WebAgentsProvider>, which would install the panel
// itself. Start the cursor first: the Settings switches drive it.
createWebAgents({ tools, visuals: { spotlight: true } });

// Development only: guard the call with your framework's dev flag.
export const removeDevtools = installWebAgentsDevtools({
  initialSettings: { spotlight: true }, // match the cursor's options
  initialOpen: true,
});
```

Guard the call with your framework's development flag so a production bundle leaves the devtools out.

## Options

`installWebAgentsDevtools(options?)` takes `DevtoolsOptions`, shared by [`<WebAgentsDevtools>`](/docs/reference/devtools/web-agents-devtools) and [`webAgentsDevtoolsPlugin`](/docs/reference/devtools/web-agents-devtools-plugin).

| Name | Type | Default | Description |
|---|---|---|---|
| `visuals` | `DevtoolsVisuals \| null` | the started `createWebAgents` or provider's cursor ([`currentAgentVisuals()`](/docs/reference/core/current-agent-visuals)), else `null` | The agent cursor the Settings switches control (spotlight, yield to the user), for example the handle from `installAgentVisuals()`. Read when it installs. `null`, or nothing started, disables the switches. |
| `initialOpen` | `boolean` | `false` | Open the panel on load, unless the person closed it last time. |
| `initialSettings` | `Partial<DevtoolsSettings>` | not said | Starting settings, below what the person saved. Pass `spotlight` matching the visuals you installed, so the switch starts in sync. |
| `hotkey` | `string \| false` | `"Alt+Shift+A"` | Keyboard shortcut that toggles the panel. `false` for none. |
| `eventClient` | `boolean` | `true` | Post state and agent events to TanStack Devtools' event bus. A no-op unless TanStack devtools listen. |

`DevtoolsVisuals` is `Pick<AgentVisuals, "setSpotlight" | "setYieldToUser">`; the handle returned by core's `installAgentVisuals()` fits.

## Returns

A disposer `() => void`. It unmounts the panel, removes its host, destroys the store (restoring the previous `window.agent`) and stops the event-client bridge.

## Notes

- Installing twice logs a warning and returns the first disposer. Only one instance exists per page. The usual cause is an app's own call left from before the provider installed the panel itself: remove it, or pass `devtools={false}` to the provider.
- Without `document` (SSR) it does nothing and returns a no-op disposer.
- Settings the person changed are saved in `localStorage` (key `"web-agents-devtools"`) and win over `initialOpen` and `initialSettings`. Saved `spotlight` and `yieldToUser` values are applied to `visuals` on the next task after install.
- `hotkey` matches letters and digits by physical key and is ignored while typing in the page's own fields. Pressing it on the page counts as user input, so the cursor yields for a moment.
- Without `visuals` it takes the cursor of whatever has started by then: call it after `createWebAgents`, not before, or pass `visuals: agents.visuals`.
- It sets `window.agent` (`invoke`, `run`, `list`); see [`createDevtoolsStore`](/docs/reference/devtools/create-devtools-store#windowagent).
- React and React DOM are peer dependencies even for this entry.

## See also

- [Devtools](/docs/build/devtools), the page that teaches it
- [`<WebAgentsDevtools>`](/docs/reference/devtools/web-agents-devtools), the React component
- [`webAgentsDevtoolsPlugin`](/docs/reference/devtools/web-agents-devtools-plugin), the TanStack Devtools tab
- [`createDevtoolsStore`](/docs/reference/devtools/create-devtools-store), `DevtoolsSettings`, `DevtoolsVisuals`
- [`webAgentsEventClient`](/docs/reference/devtools/event-client), what `eventClient` posts
- [`installAgentVisuals`](/docs/reference/core/install-agent-visuals)