The open-source agent harness - the runtime layer that turns an LLM into a working agent.
@truefoundry/trueforge-ui
A themeable, composable React SDK for building production-ready AI agent chat applications. Build your own agent chat platform with a flexible UI layer that works with TrueForge or any custom backend. The SDK is fully open source, giving you complete control over your architecture, components, and integrations. Powered by assistant-ui, it follows the familiar shadcn/ui and Tailwind CSS variable theming conventions, making it easy to customize every aspect of the experience.
Features
- Fully themeable — Use built-in themes inspired by TrueFoundry, ChatGPT, Claude, and Gemini, or create your own brand identity.
- Composable by design — Swap layouts, components, and interaction patterns to fit your product.
- Backend agnostic — Connect to TrueForge or any custom API via
TrueForgeServerConfig. - Open source — Extend, customize, and contribute without vendor lock-in.
- Built on assistant-ui — Leverage a modern React foundation with seamless shadcn/ui and Tailwind CSS integration.
- Production ready — Focus on your agents while the SDK handles the chat experience.
Bring your own brand, colors, layout, components, and server—the Agent SDK wires up the rest.
Table of contents
- Installation
- Getting started
<TrueForgeUI />props- Theming
- Content classNames
- Brand / logo
- Agent modes
- Layouts
- Custom layouts
- Overriding components
- Server
- Exports
- Docs
- License
Installation
npm install @truefoundry/trueforge-ui
# or
pnpm add @truefoundry/trueforge-ui
# or
yarn add @truefoundry/trueforge-ui
react / react-dom are required peers. The host app must have
Tailwind CSS set up (v4 recommended) so preflight
and your app chrome work alongside the SDK. In the host stylesheet:
@import 'tailwindcss';
SDK styles (tokens, utilities, OpenUI) load automatically when TrueForgeUI /
ThemeProvider mounts — you do not need to import the SDK stylesheet for
client-only apps.
Optional (SSR / explicit load order):
@import 'tailwindcss';
@import '@truefoundry/trueforge-ui/styles.css';
See docs/compatibility.md for version ranges.
Getting started
TrueForge (type: "trueforge") — Harness
Zero-config path for the TrueForge / Harness API. The SDK dynamically loads
@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter, builds the
HTTP client, and composes chat + builder + default settings catalogs into an
AgentUIServer.
Install the SDK peer used by the adapter (workspace package in this monorepo):
pnpm add @truefoundry/trueforge-sdk
Bearer token (embeds / remote API):
import { TrueForgeUI } from '@truefoundry/trueforge-ui';
export default function App() {
return (
<div style={{ height: '100dvh' }}>
<TrueForgeUI
server={{
type: 'trueforge',
baseUrl: process.env.TRUEFORGE_BASE_URL, // optional; default '/'
token: process.env.TRUEFORGE_TOKEN!,
}}
layout="sidebar"
/>
</div>
);
}
Cookie / same-origin hosts — omit token and inject fetch (e.g. an
auth-aware wrapper that follows OIDC cookies):
<TrueForgeUI
server={{
type: 'trueforge',
baseUrl: '/',
fetch: authAwareFetch,
}}
layout="sidebar"
agentConfig={{
mode: 'AgentLibraryWithComposer',
defaultAgentSpec: { model: { name: '…' } }, // often seeded at boot from listModels
}}
/>
Optional: pass catalog to override the built-in settings catalogs, or import
createTrueForgeAgentUIServer from
@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter when you need
the factory outside <TrueForgeUI />.
Custom — bring your own AgentUIServer
Pass a complete server object directly. Use createTrueForgeServer to compose separately implemented ports.
import { TrueForgeUI, createTrueForgeServer } from '@truefoundry/trueforge-ui';
const server = createTrueForgeServer({
chatServer,
getCapabilities,
getModels,
getSkills,
getMcp,
searchAgents,
saveAgent,
});
<TrueForgeUI server={server} layout="sidebar" />;
<TrueForgeUI /> props
<TrueForgeUI /> is the single entry point. Every capability is driven by a prop.
<TrueForgeUI
server={{
type: 'trueforge',
baseUrl: process.env.TRUEFORGE_BASE_URL,
token: process.env.TRUEFORGE_TOKEN,
}} // or a ready AgentUIServer
layout="sidebar" // 'sidebar' | 'drawer' | 'dock' | 'widget' | CustomLayout
agentConfig={{
mode: 'AgentLibraryWithComposer', // default when omitted
defaultAgentSpec: { model: { name: 'openai-main/gpt-4.1' } },
}}
theme={{
preset: 'claude',
brand: { mode: 'icon-title', name: 'Acme', icon: '/icon.svg' },
}}
overrides={{/* slot overrides */}}
className="h-full"
/>
| Prop | Type | Required | Description |
|---|---|---|---|
server |
TrueForgeServerConfig |
✅ | Built-in trueforge config or a ready AgentUIServer. |
layout |
LayoutProp |
✅ | Built-in layout string or a custom React component. |
agentConfig |
AgentConfig |
— | Shell mode: SingleAgent / AgentLibrary / AgentComposer / AgentLibraryWithComposer. Defaults to library + composer. |
theme |
ThemeConfig |
— | Preset, mode, tokens, brand, icons, content classNames (see Theming). |
overrides |
SlotOverrides |
— | Map of slot overrides (see Overriding components). |
className |
string |
— | Applied to the layout root. |
initialSessionId |
string |
— | Resume a specific session. |
onError |
(error: unknown) => void |
— | Host error hook (runtime + server init). |
analytics |
{ track: TrackAnalytics } |
— | Host product-analytics sink; SDK never ships a vendor. |
<TrueForgeUI
server={server}
layout="sidebar"
onError={handleError}
analytics={{
track: (eventName, data) => {
// Forward to PostHog / Segment / your sink
myAnalytics.capture(eventName, data);
},
}}
/>
Later sections use server as a TrueForgeServerConfig (usually type: "trueforge"). For a host-built port, pass the AgentUIServer directly.
Theming
Pass a preset and/or tokens and the whole UI adapts. Values map onto product CSS variables (--primary-bg, --text-primary, --card-bg, --primary-button-bg, --failure-bg, --radius, …), so no component needs palette-specific code.
const server = {
type: 'trueforge' as const,
baseUrl: process.env.TRUEFORGE_BASE_URL,
token: process.env.TRUEFORGE_TOKEN,
};
<TrueForgeUI
server={server}
layout="sidebar"
theme={{
preset: 'claude', // 'trueforge' | 'claude' | 'chatgpt' | 'gemini'
mode: 'dark', // omit for uncontrolled (useTheme().setTheme works)
tokens: {
primaryBg: 'oklch(0.14 0.02 260)',
textPrimary: 'oklch(0.97 0 0)',
secondaryBg: 'oklch(0.22 0.02 260)',
primaryButtonBg: 'oklch(0.55 0.2 275)',
primaryButtonHover: 'oklch(0.5 0.2 275)',
primaryButtonText: 'oklch(0.98 0 0)',
ghostButtonHover: 'oklch(0.8 0.12 200)',
radius: '0.5rem',
},
}}
/>;
You can also override tokens from host CSS on .aui-theme-root (inline theme.tokens still win over :root):
.aui-theme-root {
--font-agent-ui: 'Your Font', ui-sans-serif, system-ui, sans-serif;
--primary-button-bg: oklch(0.55 0.2 275);
}
Screenshot: the same layout rebranded with a custom palette.
See docs/theming.md for presets, controlled vs uncontrolled mode, and deeper theming notes.
Content classNames
Style content renderers (markdown, code fences, OpenUI, Monaco) without swapping
slots. Pass theme.classNames on <TrueForgeUI /> — values merge onto the
defaults via cn():
<TrueForgeUI
server={server}
layout="sidebar"
theme={{
classNames: {
markdown: 'prose prose-neutral dark:prose-invert max-w-none',
inlineCode: 'font-semibold',
syntaxHighlighter: {
root: 'my-code-block rounded-lg',
pre: 'bg-zinc-950 p-4',
code: 'text-sm font-mono',
lineNumber: 'opacity-60',
},
openui: { root: 'my-openui-host', scope: 'p-2' },
monaco: { root: 'my-monaco h-64', editor: 'rounded-lg', monacoTheme: 'vs-dark' },
},
}}
/>
theme.classNames key |
Component / surface | Fields |
|---|---|---|
markdown |
Markdown (message prose root) |
string |
inlineCode |
Markdown inline `code` |
string |
syntaxHighlighter |
SyntaxHighlighter (non-OpenUI fences) |
root, pre, code, lineNumber |
openui |
OpenUiFenceBlock |
root, scope |
monaco |
MonacoEditorCore (code artifacts / diffs) |
root, editor, monacoTheme (Monaco theme id) |
Custom layouts and host atoms under the provider can read the same map with
useOptionalContentClassNames() / useContentClassNames() (exported from the
package). Host CSS on .aui-markdown / .aui-syntax-highlighter / .aui-openui
/ .aui-monaco still works as an alternative.
Brand / logo
Set brand.mode, then pass the fields that mode requires. name always labels the
mark (alt / aria-label).
| Look | mode |
Required | Expanded chrome | Collapsed / compact |
|---|---|---|---|---|
| Default | omit brand |
— | TrueForge wordmark | TrueForge square |
| Icon + title | 'icon-title' |
name (+ optional icon) |
square + title text | square |
| Icon only | 'icon-only' |
name, icon |
square (no title text) | square |
| Wide logo | 'logo' |
name, icon, logo |
wide logo (no title text) | square |
<TrueForgeUI
server={server}
layout="sidebar"
theme={{
brand: {
mode: 'icon-title',
name: 'Acme',
icon: '/brand/icon.svg',
},
}}
/>
Icon-only chrome (name kept for alt):
theme={{
brand: {
mode: 'icon-only',
name: 'Acme',
icon: '/brand/icon.svg',
},
}}
Wide logo for expanded chrome. A square icon is required because collapsed chrome,
the welcome screen, and the widget button continue to use the square asset:
<TrueForgeUI
server={server}
layout="sidebar"
theme={{
brand: {
mode: 'logo',
name: 'Acme',
icon: '/brand/icon.svg',
logo: '/brand/wordmark.svg',
href: '/',
},
}}
/>
Both icon and logo accept { src, light, dark }. The SDK picks the source matching the
resolved theme mode; setting only one light/dark source uses it for both. href wraps
configured images in a same-tab link.
Component marks — theme.brand takes image URLs only. To render an inline SVG or a custom
component, override the BrandLogo slot, the same way you replace any other atom:
<TrueForgeUI server={server} layout="sidebar" overrides={{ BrandLogo: MyMark }} />
Custom layouts — import BrandLogo and use variant="icon" for compact surfaces or
variant="logo" for expanded chrome. Prefer resolveBrandChrome(useBrand()) so expanded
vs collapsed choices match the base layouts. Pair with useBrandName() when chrome should
show the title text (see Custom layouts).
Screenshot: external brand mark rendered in the base layout header.
Agent modes
agentConfig controls library chrome, draft composer, and how New Chat / Clear Chat behave.
| Mode | Layout chrome | Agent selection / New Chat |
|---|---|---|
AgentLibraryWithComposer (default) |
Agents + draft builder | New Chat opens draft; library picks a named agent |
SingleAgent |
Named-only, plain composer | Locked to name; New Chat / Clear Chat = new thread |
AgentLibrary |
Agents only (no draft) | Empty until pick; no New Chat; Clear Chat after selection |
AgentComposer |
Draft builder only (no library) | Always draft; New Chat / Clear Chat = fresh draft |
In library modes, picking an agent from Agents switches to a named chat for that agent and remounts the runtime so the new agent starts from a clean conversation. Draft chats can be promoted via Save agent (server.saveAgent on the resolved AgentUIServer). Clear Chat (thread header) resets the current named or draft session.
Mutable composers expose Agent Config for live model parameters, instructions, runtime behavior, per-connector MCP tools, and skills. Runtime Config opens in a second right-side drawer. The compact Tools picker contains only Connectors and Skills. The Save Agent drawer only edits the agent name while preserving the active draft configuration; cancelling it discards that local edit. Model context and output limits render when the server supplies that optional catalog metadata.
{
/* Library + draft (default) */
}
<TrueForgeUI server={server} layout="sidebar" />;
{
/* Named-only lock */
}
<TrueForgeUI server={server} layout="sidebar" agentConfig={{ mode: 'SingleAgent', name: 'support-agent' }} />;
{
/* Library only — select an agent to start */
}
<TrueForgeUI server={server} layout="sidebar" agentConfig={{ mode: 'AgentLibrary' }} />;
{
/* Composer only */
}
<TrueForgeUI
server={server}
layout="sidebar"
agentConfig={{
mode: 'AgentComposer',
defaultAgentSpec: { model: { name: 'openai-main/gpt-4.1' } },
}}
/>;
Screenshot: Agents open; selecting an agent resets the thread.
Layouts
Built-in layout values:
| Value | Description |
|---|---|
sidebar |
Icon rail + recent session history + active thread |
drawer |
Full-bleed thread; sessions open in a slide-over |
dock |
Fixed-width right panel; list XOR thread stack |
widget |
Same stack as dock, opened from a bottom-right FAB |
Custom layouts
For full control, pass a React component as layout. The SDK still wires server, shell mode, slots, and runtime behind it.
import { Thread, ThreadListContainer, BrandLogo, useTheme } from '@truefoundry/trueforge-ui';
function Layout({ className }: { className?: string }) {
const { mode, setTheme } = useTheme();
return (
<div className={className} style={{ display: 'flex', height: '100%' }}>
<aside style={{ width: 256 }}>
<BrandLogo variant="logo" className="h-6 w-auto max-w-40" />
<ThreadListContainer />
</aside>
<main style={{ flex: 1, minWidth: 0 }}>
<button type="button" onClick={() => setTheme(mode === 'dark' ? 'light' : 'dark')}>
Theme
</button>
<Thread />
</main>
</div>
);
}
<TrueForgeUI server={server} layout={Layout} />;
For deeper composition without TrueForgeUI, nest SlotsProvider outside TrueForgeChatProvider — see docs/customization.md.
Screenshot: a custom layout assembled from
BrandLogo,ThreadListContainer, andThread.
Overriding components
Every curated feature atom is overridable. Provide an overrides map to swap any single component while inheriting the rest.
import { TrueForgeUI, type AssistantMessageBubbleProps } from '@truefoundry/trueforge-ui';
function MyBubble({ children, error, actionBar, className }: AssistantMessageBubbleProps) {
return (
<div className={`flex flex-col gap-2 border-l-2 border-primary-button-bg pl-3.5 ${className ?? ''}`}>
{error ? <div className="rounded-lg bg-failure-bg/10 px-2.5 py-2 text-sm text-failure-bg">{error}</div> : null}
<div>{children}</div>
{actionBar}
</div>
);
}
<TrueForgeUI
server={server}
layout="sidebar"
overrides={{
AssistantMessageBubble: MyBubble,
// WelcomeScreen, ComposerShell, ToolCallCard, … all overridable
}}
/>;
Overridable slots include composer pieces (ComposerShell, ComposerLeftSection, ComposerRightSection, ComposerSendButton), messages (AssistantMessageBubble, UserMessageBubble, UserMessageEdit), Markdown, WelcomeScreen, thread-list atoms, agent metrics (AgentMetrics, AgentMetricsView, AgentMetricsTimeRangeFilter, AgentMetricCard, AgentMetricStatistics, AgentMetricChart), and tool/prompt cards (ToolCallCard, ToolApprovalBar, ToolGroupCard, SubAgentCard, SandboxToolCallCard, AgentStepsCard, ReasoningCard, AskUserPrompt, McpAuthPrompt, and more).
See docs/customization.md for the full slot list.
Server
<TrueForgeUI /> takes a TrueForgeServerConfig: built-in backends init
inside the component, or pass a ready AgentUIServer directly.
type TrueForgeServerConfig =
| {
type: 'trueforge';
baseUrl?: string;
token?: string;
fetch?: typeof fetch;
catalog?: CatalogServer;
permissions?: PermissionsServer;
}
| AgentUIServer;
type AgentUIServer = AgentChatServer &
AgentBuilderServer & {
catalog?: CatalogServer;
sessions?: AgentSessionsServer;
metrics?: AgentMetricsServer;
schedules?: ScheduleServer;
permissions?: PermissionsServer;
};
| Port | Responsibility |
|---|---|
AgentChatServer |
Sessions, turns, streaming, draft AgentSpec sync |
AgentBuilderServer |
getModels / getSkills / getMcp / searchAgents / saveAgent |
catalog |
Settings CRUD (models / connectors / optional skills & sandbox) |
sessions |
Agent details + sessions browser (/sessions, /library/:agentId) |
schedules |
Schedules page (/schedules) |
AgentMetricsServer |
Agent meter aggregates, chart definitions, and chart data |
PermissionsServer |
Per-resource USE, MANAGE, and DELETE grants |
Omit a chrome port such as catalog or schedules to hide and unregister its routes.
When permissions is omitted from a custom server, actions remain enabled for backward compatibility.
When provided, denied mutation controls stay visible but disabled with an explanatory tooltip. The built-in
type: "trueforge" server enables checks automatically through the Harness permissions endpoint; an explicit
PermissionsServer overrides that default.
Zero-config TrueForge (Harness) — see Getting started.
type: "trueforge" resolves via
@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter
(createTrueForgeAgentUIServer: chat + builder + default catalogs). Auth is
host-owned: pass token and/or fetch.
Compose your own AgentUIServer (custom): use the exported createTrueForgeServer helper or implement the port directly.
Implement AgentUIServer yourself:
import { TrueForgeUI, type AgentUIServer } from '@truefoundry/trueforge-ui';
const agentServer: AgentUIServer = {
// AgentChatServer methods…
createSession,
listSessions,
getSession,
updateSession,
createTurn,
// …
// AgentBuilderServer methods…
getModels: async () => [],
getSkills: async () => [],
getMcp: async () => [],
searchAgents: async () => [],
saveAgent: async ({ agentName, agentSpec }) => ({ ok: true }),
};
<TrueForgeUI server={agentServer} layout="sidebar" />;
See docs/server.md for the full method list and BYO guidance.
Exports
| Export | Kind | Purpose |
|---|---|---|
TrueForgeUI |
Component | Root component — accepts all props above |
TrueForgeServerConfig |
Type | server prop: truefoundry / trueforge / AgentUIServer |
createTrueForgeServer |
Function | Compose chat + builder into AgentUIServer |
Thread, ThreadListContainer, BrandLogo |
Components | Layout primitives for custom layouts |
resolveBrandChrome, useBrandName, useBrand |
Helpers | Brand chrome look + name for custom layouts |
| Composer / message / tool atoms | Components | Overridable, themeable building blocks |
SlotsProvider, useSlot, useTheme |
API | Overrides + theme mode |
AnalyticsProvider, useTrackAnalytics, AnalyticsEvents |
API | Host product-analytics sink + event catalog |
AgentUIServer, AgentChatServer, AgentBuilderServer |
Types | Resolved server contract |
ThemeConfig, LayoutProp, SlotOverrides, AgentSpec, … |
Types | Configuration contracts |
@truefoundry/trueforge-ui/styles.css |
CSS | Optional; auto-injected by ThemeProvider |
@truefoundry/trueforge-ui/assistant-ui |
Entry | Shared useAui / useAuiState (single instance) |
@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter |
Entry | createTrueForgeAgentUIServer + Harness catalogs / chat |
Curated public API: docs/api.md.
Docs
| Doc | Topic |
|---|---|
| docs/api.md | Curated public API |
| docs/architecture.md | Atoms, containers, slots |
| docs/customization.md | Theme, slots, custom layout |
| docs/compatibility.md | Peer matrix |
| docs/server.md | Server port + BYO |
| docs/theming.md | Themes, brand, icons, presets |
| CHANGELOG.md | Migration notes |
Troubleshooting: "requires an AuiProvider"
Usually duplicate @assistant-ui/core / @assistant-ui/store instances. Diagnose with pnpm why, align react across the workspace, and import chrome hooks from @truefoundry/trueforge-ui (or /assistant-ui) so you share the SDK’s copy.
Development
From the monorepo root:
pnpm install
pnpm --filter @truefoundry/trueforge-ui typecheck
pnpm --filter @truefoundry/trueforge-ui test
pnpm --filter @truefoundry/trueforge-ui build
Publishing: see RELEASING.md.
License
Security: SECURITY.md · Conduct: CODE_OF_CONDUCT.md · Changes: CHANGELOG.md