The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Architecture
This package splits UI into atoms (presentation) and containers (runtime wiring), with a curated slot registry for overrides.
Atoms (src/atoms/**)
Presentational components. An atom:
- Does not import
@assistant-ui/*or TrueFoundry runtime hooks. - Receives data and callbacks as props.
- Owns Tailwind classes / markup for what it renders.
- Curated defaults live in
defaultSlots; its keys define the publicSlotOverridescontract. - Per-atom
AtomSlotsaugmentations verify internally thatdefaultSlotsincludes every registered atom. - Low-level primitives and dedicated chrome APIs remain direct imports.
Defaults are registered in src/theme/defaultSlots.ts.
Containers (src/containers/**)
Stateful glue. A container:
- Reads assistant-ui / TrueFoundry runtime hooks and primitives.
- Derives plain props and callbacks.
- Resolves public visual atoms with
useSlot("Name"); low-level primitives, providers, and dedicated brand/layout APIs are imported directly. - Avoids decorative styling beyond layout glue.
Slots (SlotsProvider)
function MyWelcome({ heading = 'Welcome' }: WelcomeScreenProps) {
return <h1>{heading}</h1>;
}
<SlotsProvider overrides={{ WelcomeScreen: MyWelcome }}>
<Thread />
</SlotsProvider>;
Nested providers fall through to parent overrides, then defaultSlots.
Quick start: TrueForgeUI mounts SlotsProvider outside the chat
provider. See customization.md for the keep-list.
Theming
Default atoms use CSS variables from the auto-injected stylesheet (scoped to
.aui-theme-root). Override colours via theme.tokens or host CSS on
.aui-theme-root / .aui-theme-root.dark.
Notifications
ToasterProvider shows success and error toasts. Descriptions from gateway
errors are truncated for display.
Analytics
AnalyticsProvider forwards product events to a host-supplied track sink.
The SDK never ships a vendor client (e.g. PostHog). Mount order inside
TrueForgeUI: under SlotsProvider / ServerProvider, wrapping
ToasterProvider so chrome and chat share one sink.
- Pass
analytics={{ track }}on<TrueForgeUI />, or mountAnalyticsProvideryourself around a custom compose tree. useTrackAnalytics()always returns a function (no-op when unset).- Event names live in
AnalyticsEvents(src/analytics/events.ts). - Prefer firing from containers that wrap atom callbacks so visual slot overrides keep tracking. Atom-owned chrome (settings, config trigger, share) may call the hook directly.