The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Customizing the UI
Every curated feature atom is resolved through useSlot. Override via
SlotsProvider; nested providers fall through to parents / defaults.
Primitives (Button, IconButton, Dialog, …) are direct imports — not
slots — so style them via theme tokens / CSS, or fork the host layout.
import { SlotsProvider, Thread } from '@truefoundry/trueforge-ui';
function MyWelcome({ heading }: { heading?: string }) {
return <p className="px-4 py-6 text-center text-lg">{heading ?? 'What are we building today?'}</p>;
}
<SlotsProvider overrides={{ WelcomeScreen: MyWelcome }}>
<Thread />
</SlotsProvider>;
Theme object
Prefer theme={{ preset, mode, tokens, brand, icons, className, classNames }}
over hacking third-party CSS:
<TrueForgeUI
layout="sidebar"
theme={{
preset: 'claude',
mode: 'dark',
tokens: { primary: '#e11d48' },
brand: { mode: 'logo', name: 'Acme', icon: '/brand/icon.svg', logo: '/brand/wordmark.svg' },
icons: { send: MySendSvg },
classNames: {
markdown: 'prose max-w-none',
inlineCode: 'font-semibold',
syntaxHighlighter: { root: 'rounded-lg', lineNumber: 'opacity-60' },
openui: { root: 'my-openui', scope: 'p-2' },
monaco: { root: 'h-64', editor: 'rounded-lg', monacoTheme: 'vs-dark' },
},
}}
/>
Presets: trueforge (default), claude, chatgpt, gemini — stylistic
homages, not product replicas. Host CSS still works on .aui-root /
.aui-markdown / .aui-syntax-highlighter / .aui-openui / .aui-monaco.
Slot coverage
Public override surface (primitives stay theme/CSS — not slots):
- Layout / composer:
Accordion,AccordionSummary,AccordionDetails,ComposerShell,ComposerLeftSection,ComposerRightSection,ComposerSendButton,DraftComposerLeftSection,DraftComposerRightSection,DraftCompositeSelector,DraftModelSelector,ThreadRootShell,ThreadViewportShell,ThreadComposerAreaShell,MessageGroup,ScrollToBottomButton,MessageListSkeleton,WelcomeScreen - Messages / content:
AssistantMessageBubble,UserMessageBubble,UserMessageEdit,UserMessageActionBar,MessageActionBar,MessageErrorBanner,MessageIndicator,MessageTimestamp,Markdown,SyntaxHighlighter,OpenUiFenceBlock,SandboxArtifactDownload,ChatFileDownload,MonacoEditorCore,CodeEditor - Thread list:
ThreadListShell,ThreadListNewButton,ThreadListRow,ThreadListRowSkeleton,ThreadListEmptyState,HistoryLoader,AgentsLibrary,AgentsLibraryButton,SessionsBrowserButton,SaveAgentButton,SelectAgentEmptyState,ClearChatButton,ShareChatButton - Agent details / sessions:
AgentDetailsPage,AgentDetailsHeader,AgentDetailsTabs,AgentDetailsUnavailable,AgentOverview,AgentOverviewCard,AgentSessions,AgentSessionsFilters,SessionsPage,AgentMetrics,AgentMetricsView,AgentMetricsTimeRangeFilter,AgentMetricCard,AgentMetricChart,AgentSessionListRow,AgentSessionDetailHeader,AgentSessionMetricsStrip,AgentSessionTimelineContainer,AgentSessionEventTimeline,AgentSessionEventTimelineChart,AgentSessionTurnHeader,AgentCodeSnippets,AgentCodeBlock - Attachments / toasts:
AttachmentCard,AttachmentPreviewDialog,AttachmentPickerButton,Toast,ToastStack - Tools / prompts:
ToolCallCard,ToolCallContentBlock,ToolApprovalBar,ToolGroupCard,SubAgentCard,SandboxToolCallCard,AgentStepsCard,ReasoningCard,AskUserPrompt,McpAuthPrompt,ResumeUnavailable
URL routing (withRouter)
Opt in to browser-URL sync for shell navigation. Requires react-router-dom
(v6 or v7) in the host; it is an optional peer and stays out of the bundle
unless withRouter is set, so dock/widget embeds and hosts that own their own
router should leave it off (the default).
<TrueForgeUI server={server} layout="sidebar" withRouter />
Places mirrored to the URL:
/— new chat / library landing (mode-dependent)/build-agent— new agent builder/agents/:agentName— immutable "Try" of a library agent/sessions— all-user Sessions browser (named agents and drafts)/sessions/:sessionId— a specific chat session/sessions/share/:sessionId— detail-only session view without the Sessions list or filters/settings— settings overlay (closing navigates to the chat place below it)/library— Agents/library/:agentId— agent details.?tab=overview|sessions|code|metricsselects the tab (default Overview); Metrics is available when the server provides the optionalmetricsport
Customize the paths (only honored when withRouter). Set any entry to false
to keep that place overlay-only with no URL:
<TrueForgeUI
server={server}
withRouter
routes={{
basename: '/app',
paths: {
buildAgent: '/new-agent',
session: '/chats/:sessionId',
sharedSession: '/sessions/share/:sessionId',
libraryAgent: '/library/:agentId',
settings: false,
},
}}
/>
Custom agent / session / libraryAgent templates must keep their :param segment, or the
place can be written to the URL but not read back.
Shell state stays the source of truth; the router mirrors it. Combining
withRouter with initialSessionId is not supported — the URL wins.
Notes on behaviour:
- Hashes and host-owned query keys are preserved across navigation. Session
keys (
sessionId,agentId,tab,view,s_tw,s_sts,s_ets) are removed when the destination does not own them, preventing stale filters or selections from leaking into unrelated routes. - A copied library session link is
?agentId=&sessionId=on the current page (plus/library/:agentIdwhenwithRouter). Opening it lands on that agent's Sessions tab. Clicking an agent in the library writes?tab=overviewso a leftover chatsessionIddoes not open Sessions. The same query works whenwithRouteris off. - The all-user Sessions page is
/sessionswhenwithRouteris on, or?view=sessionswhen it is off. Agent and time filters live in the query (agentId,s_twfor a relative window, ors_sts/s_etsfor an absolute range). Opening a session pinss_sts/s_etsaroundcreated_at(±5 min) so a refresh still finds that row on page 1 without scrolling the list. - A detail-only shared session is
/sessions/share/:sessionIdwhenwithRouteris on. Without SDK routing, the same view uses?view=shared-session&sessionId=:sessionIdon the host page. - A
/sessions/:sessionIdlink is resolved throughgetSessionso the chat opens with its own agent binding and mutability rather than as a new draft. /build-agentis used for a fresh builder; after its draft session persists, the URL transitions to/sessions/:sessionId.- Agent-filtered chat history keeps one intent key in the query string:
try_agent_namehides the filter for a Try Agent flow, whilehistory_agent_nameshows an explicitly selected filter. Both values are display names; the shell resolves the backend agent id before listing sessions. Non-chat destinations such as Build Agent, Agents, Sessions, Schedules, and Settings clear this query state. User filter changes start a clean chat and reset history pagination; All Chats remains paginated in 20-session pages. - Unrecognized paths (and malformed escapes) normalize to the root place.
/settingsis registered only while Settings chrome is available (catalog present andcapabilities.settings.enabled !== false). When that gate is off,/settingsis treated like an unknown path and replaces to root.- A URL naming a place the host cannot honor (e.g.
/agents/xwithout the agent library) is left in the address bar until the next navigation corrects it.
Hosts serving the SDK must send the app shell for unknown paths (SPA fallback), otherwise deep links 404 before React boots.
Analytics and slot overrides
Product analytics fire from containers that wrap atom callbacks (onCopy,
onSubmit, …). Visual slot overrides that keep those props continue to track
automatically. Overrides that invent new click paths should call
useTrackAnalytics() (and use AnalyticsEvents) themselves. Pass
analytics={{ track }} on <TrueForgeUI /> — the SDK does not ship a vendor.
Custom layout
Pass a React component as layout to own chrome; compose exported
Thread / ThreadListContainer / brand helpers:
function CenteredLayout({ className }: { className?: string }) {
return (
<div className={`mx-auto flex h-full max-w-3xl flex-col ${className ?? ""}`}>
<ThreadListContainer />
<Thread />
</div>
);
}
<TrueForgeUI layout={CenteredLayout} server={server} agentMode={…} />;
Restyle bubbles
import { SlotsProvider, Thread, type AssistantMessageBubbleProps } from '@truefoundry/trueforge-ui';
function AssistantBubbleV2({ children, error, actionBar }: AssistantMessageBubbleProps) {
return (
<div className="mr-auto max-w-[75%] rounded-2xl bg-neutral-100 px-4 py-2">
{children}
{error}
{actionBar}
</div>
);
}
<SlotsProvider overrides={{ AssistantMessageBubble: AssistantBubbleV2 }}>
<Thread />
</SlotsProvider>;
See theming.md for the full hard-cut design and migration notes.