API reference

The SDK has two entry points:

@shappychat/chat: the browser entry point
@shappychat/chat/node: the Node entry point

Import the styles one time: import '@shappychat/chat/style.css'.

Mount the UI

Export	Description
`mountShappyChatDrawer(container, options)`	Mounts the full chat surface with header and launchers. Returns a `ShappyChatDrawer`. See Embed the chat.
`mountShappyChat(container, options)`	Mounts only the conversation and the message field. Returns `{ element, unmount }`.
`createShappyChatModelPicker(options)`	Creates the model menu. Methods: `open(anchor, runtime)` and `close()`.

`MountShappyChatOptions`

Option	Type	Description
`runtime`	`ShappyChatRuntime`	Required
`onModelSelect`	`(anchor?: HTMLElement) => void \| Promise<void>`	Shows the model button when set
`onError`	`(error: unknown) => void`	Called when an error occurs
`onBeforeSend`	`() => void \| Promise<void>`	Called before each message is sent
`enableAttachments`	`boolean`	Default `true`. The chat sends images only to a model that reads images. It sends documents as text to all models.
`showExecutionMode`	`boolean`	Shows the Auto, UI and MCP menu and its Shift + Tab shortcut. Default `false` (Auto).
`character`	`GhostCharacter`	The Shappy Ghost shown while a turn is in progress: `classic` (default), `sprout`, `bow`, `headphones`, `cap`, `wizard`, `blush`, `glasses`, `antenna`, `imp`, `snow` or `crown`. `GHOST_CHARACTERS` lists them with their colours.

Types

Type	Values
`ShappyChatPresentation`	`'drawer' \| 'floating' \| 'island' \| 'inline'`
`ShappyChatTheme`	`{ accent?, panel?, field?, ink?, ghost?: string; glow?: boolean }`
`ExecutionMode`	`'auto' \| 'ui' \| 'mcp'`

Runtimes

Export	Description
`RemoteShappyChatRuntime.connect({ url, token, conversationId })`	Connects to a conversation on Shappy Backend
`createShappyChatRuntime(options)`	Opens or creates a browser-local Pi Durable conversation, stored in IndexedDB. Options: `scope`, `conversationId?`, `model?`, `systemPrompt?`, `connections?`, `uiCursor?`, `getApiKey?`, `database?`, `onMoved?`. One window at a time writes a conversation. Opening it elsewhere asks the holding window to hand it over: an idle holder closes it and calls its `onMoved`, a holder still answering refuses.
`listBrowserConversations(scope)`	Lists the conversations stored in this browser for a scope, newest first
`DurableRuntime`	The runtime class behind `createShappyChatRuntime` and the Node runtime
`McpConnections`	A set of MCP connections. Use `add({ id, url, headers })`.
`discoverOpenAiModels(baseUrl, apiKey?)`	Lists the chat models of an OpenAI-compatible endpoint
`openAiCompatibleModel(id, baseUrl, name?)`	Describes one model on an OpenAI-compatible endpoint

Runtime methods

Method	Description
`getSnapshot()`	Returns the current state, including `conversationId`, `model`, `executionMode` and `activeExecutionMode`
`configure(input)`	Changes settings, for example `{ executionMode: 'ui' }`
`attachUi(adapter)`, `detachUi()`	Connects or removes UI tools (remote runtime)
`setHostTools(tools)`	Sets UI tools (browser-local runtime)
`close()`	Stops the updates of this client (remote runtime), or releases the conversation for other windows (browser-local runtime)

UI tools

Export	Description
`createDomAdapter({ root, cursor? })`	Finds marked controls in `root` and acts on them. Methods: `discover()`, `act(request)`, `register(id, handlers)`, `dispose()`.
`createUiCursor({ mode?, storageKey? })`	Creates the visible cursor. Methods: `setMode(mode)`, `dispose()`.
`createUiTools(executor)`	Turns a discover and act function into tools for a browser-local runtime
`AGENT_ID_ATTRIBUTE`	`'data-agent-id'`
`AGENT_DESCRIPTION_ATTRIBUTE`	`'data-agent-description'`
`EXECUTION_MODES`	The list of execution modes

Node entry point

Export	Description
`createNodeShappyChatRuntime(options)`	Creates a runtime with Pi Durable SQLite storage in `storageDirectory`. Returns `{ runtime, host, close }`.
`addStdioConnection(connections, config)`	Adds an MCP server that runs as a local process
`openNodeDurableHost(directory, getApiKey?)`	Opens the Pi Durable host for `directory/chat.sqlite` and claims it for this process. Returns `{ host, close }`.
`createRuntimeBridge(config)`	Serves a runtime over authenticated HTTP. Its optional `celld` setting connects to a bound cell host.
`CelldShappyChatRuntime.connect(options)`	Source Node export for a trusted celld connection. See Durable Chat.
`CelldRuntimeOptions`	`{ url, token, conversationId, scope, clientId? }`. Keep the service token in the backend.