# Hook Explorer

> Discover and live-preview CopilotKit render hooks without leaving VS Code.

You have a file that calls `useCopilotAction`, `useRenderTool`, `useCoAgentStateRender`, or any of the other render-capable CopilotKit hooks, and you want to iterate on the `render` prop (tweak the layout, test different statuses, feed different args) without running the full chat loop. The Hook Explorer is a sidebar and inline-CodeLens UI inside the [VS Code extension](/agent-spec/vs-code-extension) that does exactly that.

By the end of this page you'll have:

- Every CopilotKit hook call in your workspace listed in a sidebar.
- A live preview panel for any render hook, with auto-generated form controls driven by the hook's declared parameters.
- A one-click `▶️ Preview Component` CodeLens above every hook call in your editor.

## Prerequisites [#prerequisites]

- The [CopilotKit VS Code extension](/agent-spec/vs-code-extension) installed.
- `@copilotkit/react-core` or `@copilotkit/react-core/v2` imported somewhere in your workspace.

<Callout type="info">
  The Hook Explorer runs entirely against your source files: no runtime, no API keys, no agent run required.
</Callout>

## Explore and preview [#explore-and-preview]

<Steps>

<Step>
### Open the Hook Explorer [#open-the-hook-explorer]

Click the CopilotKit icon in the Activity Bar and expand the **CopilotKit Hooks** sidebar (first of the three views). You'll see every CopilotKit hook call in your workspace, grouped by hook name. Each row shows the action/tool name (or `line:N` for nameless hooks like `useLangGraphInterrupt`) alongside the file path and line.
</Step>

<Step>
### Preview a render hook [#preview-a-render-hook]

Click any row under a render hook (`useCopilotAction`, `useRenderTool`, …) to open the preview panel in an editor pane. Your component mounts in the preview panel. Use the controls on the left (or on top at narrow widths) to drive your `render` prop:

- **Status**: `inProgress` / `executing` / `complete`.
- **Args / parameters**: form built from your hook's `parameters` array (V1) or Zod / Standard Schema (V2). Missing fields, enum options, nested objects and arrays all work.
- **Result**: editable once status is `complete`.
- **Hook-specific extras**: `nodeName` for `useCoAgentStateRender`, `toolCallId` for `useRenderTool`, an event-value editor for interrupts.

The rendered output sits inside a labeled frame on the right (or below) so it's unmistakably "the component your `render` returned."
</Step>

<Step>
### Edit and re-render [#edit-and-re-render]

Save the file. The extension re-scans the file, rebundles the preview, and re-captures. Your form values are preserved wherever the field names and types still match the new schema.
</Step>

</Steps>

### Other ways to open a hook [#other-ways-to-open-a-hook]

- **Jump to source**: Each sidebar row has a `</>` button on hover. The button opens the file at the line of the hook call. For data hooks, which have no preview, the row click opens the source.
- **Inline CodeLens**: Open any `.ts` or `.tsx` file that calls a render hook. A `▶️ Preview Component` CodeLens sits above each hook call. Click it to open the same preview panel.

## Hook coverage [#hook-coverage]

Every render-capable CopilotKit hook is discoverable and previewable:

| Hook | Source | Preview shape |
|---|---|---|
| `useCopilotAction` | `@copilotkit/react-core` | action (`args`, `status`, `result`) |
| `useCopilotAuthenticatedAction_c` | `@copilotkit/react-core` | action |
| `useCoAgentStateRender` | `@copilotkit/react-core` | coagent-state (`state`, `status`, `nodeName`) |
| `useLangGraphInterrupt` | `@copilotkit/react-core` | interrupt (`event`, `resolve`) |
| `useRenderTool` | `@copilotkit/react-core/v2` | render-tool (`parameters`, `status`, `toolCallId`) |
| `useRenderToolCall` | `@copilotkit/react-core/v2` | render-tool |
| `useDefaultRenderTool` | `@copilotkit/react-core/v2` | render-tool |
| `useLazyToolRenderer` | `@copilotkit/react-core` | render-tool |
| `useFrontendTool` | `@copilotkit/react-core/v2` | render-tool |
| `useComponent` | `@copilotkit/react-core/v2` | render-tool |
| `useDefaultTool` | `@copilotkit/react-core` | action |
| `useHumanInTheLoop` | `@copilotkit/react-core/v2` | action |
| `useInterrupt` | `@copilotkit/react-core/v2` | interrupt |
| `useRenderCustomMessages` | `@copilotkit/react-core/v2` | custom-messages (`message`) |
| `useRenderActivityMessage` | `@copilotkit/react-core/v2` | activity-message (`message`) |

Data hooks (`useCopilotReadable`, `useCoAgent`, `useAgent`, `useCopilotChat`, etc.) appear in the sidebar for navigation but have no preview. The row click opens the source.

Imported render components work too: if your `render` prop is a reference to a component defined in a sibling file (instead of an inline arrow), Rolldown walks the import chain and the preview binds to the actual component.

## Behavior notes [#behavior-notes]

- **Auto-recovery**: If a render prop throws, the preview panel shows an error screen. When you pick a different hook in the sidebar, the preview panel resets.
- **Controls persist**: your last-used args, status, and result are stored in VS Code workspace state per hook, so they're restored next time you open the same preview.
- **Styles flow through**: Tailwind classes in your `render` prop work via the Tailwind browser CDN loaded into the preview panel. Local `.css` imports are collected by the bundler and injected as a `<style>` tag on each load.

## Limitations [#limitations]

- **Barrel-file re-exports aren't resolved**: import hooks directly from `@copilotkit/react-core` or `@copilotkit/react-core/v2`. If you re-export through your own index file, the scanner won't pick up the call sites.
- **Non-CopilotKit providers**: if your component requires `<ThemeProvider>`, Redux, Auth, or another custom provider to render, the mount will throw. Isolate the hook into a provider-free component for preview, or stub the provider in the preview-only path.
- **Agent state typing**: `useCoAgentStateRender` state has no runtime schema (types live in TypeScript only), so the state control falls back to a raw-JSON editor.
- **Dynamic action names**: if `useCopilotAction({ name: someVariable })` uses a non-literal name, the sidebar labels the entry `(dynamic) · file:line` until the runtime capture resolves it.

<Callout type="info">
  Need to see the live AG-UI event stream while the agent is actually running? Hook Explorer is the offline, render-first tool. The [AG-UI Event Inspector](/agent-spec/troubleshooting/event-inspector) is the runtime, events-first complement.
</Callout>
