Documentation Index
Fetch the complete documentation index at: https://docs.usechar.com/llms.txt
Use this file to discover all available pages before exploring further.
<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()
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.
