Skip to content

React

@aidy-dev/react renders aidy inside your product: a side dock with the conversation, a ⌘K search palette, approval cards, forms, a Markdown help viewer and the admin model settings. It talks to aidy through @aidy-dev/client.

Terminal window
npm install @aidy-dev/react @aidy-dev/client

Create one client and wrap the part of the app that shows aidy in AidyProvider. Import the stylesheet once.

import { createClient } from '@aidy-dev/client';
import { AidyDock, AidyProvider, SearchPalette } from '@aidy-dev/react';
import '@aidy-dev/react/styles.css';
import { useMemo } from 'react';
import { useNavigate } from 'react-router';
export function Shell({ children }: { children: React.ReactNode }) {
const navigate = useNavigate();
const client = useMemo(
() =>
createClient({
headers: async () => ({ Authorization: `Bearer ${await getAccessToken()}` }),
}),
[],
);
return (
<AidyProvider
client={client}
locale="en"
theme="system"
onOpen={navigate}
upload={uploadToYourStorage}
context={() => [{ description: 'The page the user is on', value: location.pathname }]}
>
{children}
<AidyDock />
<SearchPalette />
</AidyProvider>
);
}

createClient options:

Option Meaning
baseUrl Where aidy is mounted: '' (the default, the page’s origin), an origin (https://console.example.com), or a path prefix (/assistant, the host’s basePath). The client adds /aidy/v0 itself, so never pass /aidy/v0.
headers Called before every request, for example to add the user’s Authorization. Omit it when the browser’s cookies authenticate the user.
fetch A custom fetch, for tests.

AidyProvider props:

Prop Meaning
client The client above.
locale Any BCP 47 tag; default 'en'. Sets the strings and the lang of aidy’s elements (Strings and locales).
strings Partial<Strings>: replaces built-in strings by key.
upload (file: File) => Promise<UploadedFile> ({ url, mimeType, name? }): stores a file the user attaches and returns a URL the model can fetch. Without it the composer offers no attachments.
context () => { description, value }[]: what the user is looking at. Called as each run starts (new messages and answers to approvals or forms alike) and sent as the run’s AG-UI context.
theme 'light', 'dark' or 'system' (default, follows prefers-color-scheme).
onOpen Shows a product page. It receives same-origin paths only (/path?query#hash).

The provider reads the assistant’s name once from GET /aidy/v0/info (createAidy({ name }), AIDY_NAME) and uses it wherever a string names the assistant: the dock title, “Open {name}”, “Message {name}…”, “Ask {name}”. Until it answers, and if it fails, the name is Aidy.

When a write succeeds, its x-aidy.open page arrives as an aidy.ui.open event, and search results and citations carry URLs. aidy hands same-origin paths to onOpen, so your router changes the page without a reload. Without onOpen, it assigns window.location. Links to other origins open in a new tab.

  • AidyDock is the side panel: a launcher, the conversation, and its history. ⌘J (Ctrl+J) toggles it, Escape closes it, and it fills the screen on narrow viewports. Approvals and forms appear inline.
  • SearchPalette opens on ⌘K (Ctrl+K). It searches every source in parallel and groups hits by type. Arrow keys move, Enter opens, and the last row hands the query to the assistant.

AidyDock props:

Prop Meaning
open, onOpenChange Controls whether the panel is open.
threadId, onThreadChange Controls the thread shown; null is a new conversation.

Uncontrolled, the dock remembers whether it was open and its thread in localStorage, under aidy:dock:<client.baseUrl> (the page’s origin when baseUrl is empty), and restores them after mounting, so a reload or a page change keeps the conversation. Controlled values win over what it remembers. Where storage is off or throws, it simply forgets.

SearchPalette props:

Prop Meaning
open, onOpenChange Controls whether the palette is open.
onAsk (query) => void: takes the query of the last row. By default it opens the dock with the query as a new question.

Result groups are headed by the hit type: strings={{ 'type.work_item': 'Work items' }} names one, and a type without a string shows humanized (work_item → Work item).

Open the dock from your own UI with useDock:

import { useDock } from '@aidy-dev/react';
function StopButton({ name }: { name: string }) {
const dock = useDock();
return <button onClick={() => dock.ask(`stop ${name}`)}>Ask Aidy</button>;
}

useDock() returns { open, setOpen, ask }; ask(query) opens the dock on a new conversation that starts with query.

useSearchPalette() returns { isOpen, open(query?), close() }, for a search button in your header or on a phone, where there is no ⌘K:

import { useSearchPalette } from '@aidy-dev/react';
function SearchButton() {
const palette = useSearchPalette();
return <button onClick={() => palette.open()}>Search</button>;
}

With upload, the composer has an attach button (several files at a time), and takes files dropped onto the thread and files or images pasted into the message box. Pending files show as thumbnails (images) or name chips, each with a remove button, while they upload; a failed upload says so and is left out of the message. A message may carry attachments and no text. Sent images show as thumbnails and files as chips; both open in a new tab.

import type { UploadedFile } from '@aidy-dev/react';
async function uploadToYourStorage(file: File): Promise<UploadedFile> {
const body = new FormData();
body.append('file', file);
const { url } = await fetch('/api/files', { method: 'POST', body }).then((r) => r.json());
return { url, mimeType: file.type, name: file.name }; // e.g. /files/f_123
}

Return a path on your host (or a URL on its origin) when the file needs the user’s credential: aidy fetches it as the user and inlines it for vision models. Other URLs go to the provider as they are. See AG-UI: user messages and Models: vision.

Every finished answer has thumbs up and down, sent with client.setFeedback to PUT …/feedback. A thumbs down offers an optional comment. The user can change the rating; a failure only shows a note. Admins read every rating with client.listFeedback().

AidyThread renders one conversation without the dock (threadId, onThreadCreated, initialMessage). For a fully custom layout, use the hooks and the lower-level components:

import { answerApproval, answerForm } from '@aidy-dev/client';
import { AidyForm, ApprovalCard, useThread } from '@aidy-dev/react';
function Interrupts({ threadId }: { threadId: string }) {
const thread = useThread(threadId);
return thread.state.interrupts.map((open) =>
open.kind === 'approval' ? (
<ApprovalCard
key={open.id}
interrupt={open}
onAnswer={(approved) => thread.resume([answerApproval(open, approved)])}
/>
) : open.kind === 'input' ? (
<AidyForm
key={open.id}
form={open.form}
onSubmit={(answers) => thread.resume([answerForm(open, answers)])}
/>
) : null,
);
}
  • ApprovalCard shows the operation’s impact and frozen arguments, and disables itself when the approval expires (15 minutes). answerApproval echoes the argsHash, so the approval binds to what the user saw. See Approvals.
  • AidyForm validates answers with the form’s rules before calling onSubmit. See Forms.
  • state.citations holds each message’s citations as { n, hit }[]; Markdown’s citations prop links [n] in the text to the citation numbered n, and a number without one stays plain text.
  • With @aidy-dev/client alone, attachmentPart({ url, mimeType, name? }) builds the image or document part of an uploaded file for run(threadId, { message, context? }).
Hook Returns
useThread(threadId) { threadId, state, error, send, resume, cancel }; replays and follows the thread’s events. send takes text or AG-UI content parts.
useThreads() The user’s threads, newest first, with loadMore, reload and remove.
useSearch(query) Federated search, debounced 150 ms.
useCatalog() The operations visible to this user.

All of them must render inside AidyProvider.

import { HelpViewer, ModelSettings } from '@aidy-dev/react';
<HelpViewer url="/help/getting-started.md" />; // relative links and images resolve against it
<ModelSettings />; // admin form for the model chain; needs aidy:admin to save

ModelSettings edits the model chain: provider, model, base URL, API key, temperature, max output tokens and image support. API keys are write-only: the form shows whether a key is stored, and an empty key field keeps the stored one. New rows get an id model-N. Models configured in code (provider custom) are shown read-only; saving replaces them, and the form says so. Reset to defaults asks for confirmation, then calls client.resetSettings() (DELETE /aidy/v0/settings) and shows the configured chain.

Every component, used inside the dock or on its own (AidyThread, SearchPalette, ModelSettings, HelpViewer), carries the .aidy-root theme variables, data-aidy-theme and lang. The styles set what they rely on explicitly (lists, headings, links, code, tables, buttons, inputs), so a CSS reset such as Tailwind’s preflight does not change them.

Every color and size is a CSS variable on .aidy-root. Override them in your stylesheet:

.aidy-root {
--aidy-accent: #0f766e;
--aidy-accent-fg: #ffffff;
--aidy-accent-soft: #ccfbf1;
--aidy-radius: 6px;
--aidy-font: Inter, system-ui, sans-serif;
--aidy-dock-width: 460px;
}
.aidy-root[data-aidy-theme="dark"] {
--aidy-accent: #2dd4bf;
}

The full set: --aidy-bg, --aidy-fg, --aidy-muted, --aidy-surface, --aidy-border, --aidy-accent, --aidy-accent-fg, --aidy-accent-soft, --aidy-danger, --aidy-danger-soft, --aidy-warning, --aidy-warning-soft, --aidy-success, --aidy-mark, --aidy-overlay, --aidy-shadow, --aidy-radius, --aidy-font, --aidy-mono, --aidy-dock-width. With theme="system", the dark values apply under prefers-color-scheme: dark.

locale is any BCP 47 tag. zh-CN has its own strings; every other tag speaks English. locales holds the built-in tables, locales.en and locales['zh-CN'], typed Strings. A string is looked up in strings, then the locale’s table, then English, and an unknown key shows as itself.

import { AidyProvider, type Strings } from '@aidy-dev/react';
const ja: Partial<Strings> = { send: '送信', 'type.work_item': '作業項目' };
<AidyProvider client={client} locale="ja" strings={ja}>…</AidyProvider>;

{name} in a string is the assistant string, which itself defaults to the name from /info, so strings={{ assistant: 'Copilot' }} renames the assistant everywhere. type.<type> keys name search result groups.

locale covers aidy’s own strings. The assistant’s replies follow the user: the identity locale and the language they write in. Pick the locale from your app’s language setting so both agree.