import { TrueForgeUI } from "@truefoundry/trueforge-ui";
Properties
TrueForgeServerConfig
required
Where the chat gets its data. Either a built-in config object or a ready AgentUIServer.
Show TrueForgeServerConfig
"trueforge"
Omit entirely to pass an AgentUIServer object directly — there is no "custom" wrapper.
"trueforge" loads the Harness adapter (plugins/trueforge-agent-server-adapter). See
Quickstart.
string
TrueForge / Harness API root. Used when type is "trueforge". Defaults to '/'.
string
Bearer token for @truefoundry/trueforge-sdk when type is "trueforge". Prefer fetch for
cookie / OIDC hosts.
typeof fetch
Custom fetch for type: "trueforge" (cookie sessions, auth interceptors).
Pins the UI to one named agent. name is required; selection controls are hidden.
variant
Users pick from saved agents. New chat is disabled in this mode only.
variant
Users assemble an ad-hoc agent.
variant
Both surfaces. The default.
defaultAgentSpec seeds a new draft and is picked up on new chat, not on clear chat. See
Agent modes.
ThemeConfig
Preset, color mode, tokens, branding, and content class names.
Show ThemeConfig
"trueforge" | "claude" | "chatgpt" | "gemini"
default:"\"trueforge\""
Base token palette.
"light" | "dark" | "system"
Omit for uncontrolled — the SDK resolves system and persists the user’s choice to
localStorage under aui-theme-preference. Passing a value makes it controlled and turns
setTheme into a no-op.
Partial<SemanticTokens>
Per-token overrides, merged over the preset and applied as inline styles.
Show SemanticTokens
string
sidebarBg, sidebarText, topbarBg, primaryBg, secondaryBg, border, fontFamily
(maps to --font-agent-ui).
Optional. Omit it to use the built-in TrueForge wordmark in expanded chrome and
square mark in compact surfaces. When set, choose mode first, then pass the
fields that mode requires.
Show BrandConfig
"icon-title" | "icon-only" | "logo"
Chrome look. icon-title shows name beside the square mark; icon-only
and logo keep name for alt only.
string
Required. Accessible image label (alt / aria-label). Also shown as title
text beside the square icon when mode is icon-title.
string | BrandLogoConfig
Square image used in collapsed and compact surfaces. Optional for
icon-title (default mark); required for icon-only and logo.
string | BrandLogoConfig
Wider image used when mode is logo. Falls back to icon in
BrandLogo if needed. Required for mode: "logo".
string
Wraps configured brand images in a same-tab link.
Show BrandLogoConfig
string
Source used when the resolved mode is light.
string
Source used when the resolved mode is dark.
string
Mode-agnostic source, used when neither light nor dark is set.
A single configured mode is used for both modes, so { light } alone never renders a
missing image. Use BrandLogo with variant="icon" or variant="logo" in custom
layouts. To render a component rather than an image, override its slot through
overrides.
IconMap
Replace registry icons by name. Values are Lucide components, React nodes, render
functions, or SVGR components.
Replace any built-in component. Partial<AtomSlots>, derived from the SDK’s default slot
table — so editor autocomplete lists the overridable names. See
Slot overrides.
string
Passed to the layout component, and to the loading and error states. Typically
"h-full min-h-0". To style the theme wrapper instead, use theme.className.
string
Open an existing session on mount instead of starting fresh.
RuntimeAdapters
Runtime adapter overrides. Attachments default to trueForgeAttachmentAdapter.
(error: unknown) => void
Called when the server fails to resolve or the runtime raises an error.
Behavior notes
The component mounts every provider it needs, so you do not have to wrap it in anything.Switching agents, starting a new draft, or clearing the chat resets the conversation — the
current transcript is cleared so that one agent’s messages do not carry into another’s context.
Persisted sessions remain available through the thread list.
If window.location.search contains screenType=mcp-auth, the component renders only the
OAuth completion screen and no layout. See MCP OAuth.