`<char-agent-shell>`

<char-agent-shell> custom element. Opinionated host shell that composes a persistent inner <char-agent> and owns responsive mode policy plus host layout orchestration. This shell does not render chat controls, prompts, or composer UI. Visible assistant UI is always iframe-owned. Policy:

closed to pip
open desktop to inline
open narrow viewport to fullscreen

Registration and import

import '@mcp-b/char/shell-component'

import { registerCharShell } from '@mcp-b/char/shell-component'
registerCharShell()

Auth, open-state, and shell helpers

const shell = document.querySelector('char-agent-shell')

shell?.setAuth({ publishableKey, idToken }) // convenience wrapper
shell?.setOpen(true)                   // controlled open state
shell?.setHostContext({ locale: 'en-US' })
shell?.toggleOpen()

setAuth
connect
disconnect
setHostContext
setOpen
toggleOpen

Attributes

Attribute	Type	Default	Description
`api-base`	`string`	`https://app.usechar.ai`	Forwarded API base override for the inner element.
`enable-debug-tools`	`boolean`	`false`	Forwarded debug-tool toggle for the iframe runtime.
`open`	`boolean`	`false`	Open state for policy-resolved layout behavior.

Properties

Property	Type	Description
`apiBase`	`string \| undefined`	React-friendly property form of `api-base`.
`open`	`boolean`	Current open/closed state for shell layout policy.

Methods

Method	Returns	Summary
`setAuth()`	`void`	Convenience method for declarative wrappers. Applies auth when provided, otherwise clears auth.
`connect()`	`void`	Connects shell authentication and starts availability health checks.
`disconnect()`	`void`	Clears authentication and disconnects the inner `<char-agent>`.
`setHostContext()`	`void`	Merges and forwards host context to the inner `<char-agent>`. Shell-owned fields (`displayMode`, `availableDisplayModes`) are ignored.
`setOpen()`	`void`	Sets shell open state.
`toggleOpen()`	`void`	Toggles shell open state.

`setAuth(options: ConnectOptions | null): void`

Convenience method for declarative wrappers. Applies auth when provided, otherwise clears auth. Parameters:

options (ConnectOptions | null): Auth payload to connect, or null to disconnect.

Returns: void

`connect(options: ConnectOptions): void`

Connects shell authentication and starts availability health checks. Parameters:

options (ConnectOptions): Authentication payload (publishableKey + optional idToken).

Returns: void

`disconnect(): void`

Clears authentication and disconnects the inner <char-agent>. Returns: void

`setHostContext(hostContext: CharHostContext): void`

Merges and forwards host context to the inner <char-agent>. Shell-owned fields (displayMode, availableDisplayModes) are ignored. Parameters:

hostContext (CharHostContext): Partial host context patch to forward.

Returns: void

`setOpen(open: boolean): void`

Sets shell open state. Parameters:

open (boolean): Next desired open state.

Returns: void

`toggleOpen(): void`

Toggles shell open state. Returns: void

Events

Event	Detail	Description
`char-shell-open-change`	`{ open: boolean }`	Emitted when the shell open state changes.
`char-initialized`	`void`	Forwarded from the inner `<char-agent>` runtime.
`char-close`	`void`	Forwarded when embedded UI requests close.
`char-error`	`CharErrorDetail`	Forwarded bridge/runtime errors.
`char-size-changed`	`CharSizeChangedDetail`	Forwarded embedded content size updates.
`char-request-display-mode`	`CharRequestDisplayModeDetail`	Forwarded mode-change requests from the iframe.
`char-open-link`	`CharOpenLinkDetail`	Bubbled link-open request from the inner element.

Slots

None.

CSS Custom Properties

Forwards styling to the inner <char-agent>. See CSS Variables Reference.

CSS Parts

None.

API Reference

SDK Reference

Agent Reference

MCP Reference

Security Reference

Auth

OAuth

Subscriptions

End Users

Users

Organizations

Organization Skills

User Scripts

Directories

Plan Tiers

Threads

Usage Analytics

Identity Providers

Governance

GitHub Apps

Publishable Keys

OAuth Discovery

<char-agent-shell>

`<char-agent-shell>`

Registration and import

Auth, open-state, and shell helpers

Attributes

Properties

Methods

`setAuth(options: ConnectOptions | null): void`

`connect(options: ConnectOptions): void`

`disconnect(): void`

`setHostContext(hostContext: CharHostContext): void`

`setOpen(open: boolean): void`

`toggleOpen(): void`

Events

Slots

CSS Custom Properties

CSS Parts

​<char-agent-shell>

​Registration and import

​Auth, open-state, and shell helpers

​Attributes

​Properties

​Methods

​setAuth(options: ConnectOptions | null): void

​connect(options: ConnectOptions): void

​disconnect(): void

​setHostContext(hostContext: CharHostContext): void

​setOpen(open: boolean): void

​toggleOpen(): void

​Events

​Slots

​CSS Custom Properties

​CSS Parts

`<char-agent-shell>`

Registration and import

Auth, open-state, and shell helpers

Attributes

Properties

Methods

`setAuth(options: ConnectOptions | null): void`

`connect(options: ConnectOptions): void`

`disconnect(): void`

`setHostContext(hostContext: CharHostContext): void`

`setOpen(open: boolean): void`

`toggleOpen(): void`

Events

Slots

CSS Custom Properties

CSS Parts