> ## 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>

> Custom element API reference for <char-agent-shell>.

# `<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

```ts theme={null}
import '@mcp-b/char/shell-component'
```

```ts theme={null}
import { registerCharShell } from '@mcp-b/char/shell-component'
registerCharShell()
```

## Auth, open-state, and shell helpers

```ts theme={null}
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`](#method-setauth)
* [`connect`](#method-connect)
* [`disconnect`](#method-disconnect)
* [`setHostContext`](#method-sethostcontext)
* [`setOpen`](#method-setopen)
* [`toggleOpen`](#method-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()`](#method-setauth)               | `void`  | Convenience method for declarative wrappers. Applies auth when provided, otherwise clears auth.                                        |
| [`connect()`](#method-connect)               | `void`  | Connects shell authentication and starts availability health checks.                                                                   |
| [`disconnect()`](#method-disconnect)         | `void`  | Clears authentication and disconnects the inner `<char-agent>`.                                                                        |
| [`setHostContext()`](#method-sethostcontext) | `void`  | Merges and forwards host context to the inner `<char-agent>`. Shell-owned fields (`displayMode`, `availableDisplayModes`) are ignored. |
| [`setOpen()`](#method-setopen)               | `void`  | Sets shell open state.                                                                                                                 |
| [`toggleOpen()`](#method-toggleopen)         | `void`  | Toggles shell open state.                                                                                                              |

<a id="method-setauth" />

### `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`

<a id="method-connect" />

### `connect(options: ConnectOptions): void`

Connects shell authentication and starts availability health checks.

Parameters:

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

Returns: `void`

<a id="method-disconnect" />

### `disconnect(): void`

Clears authentication and disconnects the inner `<char-agent>`.

Returns: `void`

<a id="method-sethostcontext" />

### `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`

<a id="method-setopen" />

### `setOpen(open: boolean): void`

Sets shell open state.

Parameters:

* `open` (`boolean`): Next desired open state.

Returns: `void`

<a id="method-toggleopen" />

### `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](/reference/css-variables).

## CSS Parts

*None.*