Client and React API
Declarations live in packages/client/src. The Connect a frontend guide explains how the pieces fit.
Stores
Section titled “Stores”Each store mirrors one of the API’s event streams and opens it when created. url is the API’s base URL. options.fetch makes every request; it defaults to the platform fetch.
| Function | Mirrors |
|---|---|
createWorkspaceStore(url, options?) |
Who the Familiars are, the rooms this person sees, who they are, and the login |
createFamiliarStore(url, id, options?) |
One Familiar’s model, memory and schedules |
createRoomStore(url, id, options?) |
One room’s log, its turns in progress and their transcript |
Each reads like a Zustand store, with getState(), getInitialState() and subscribe(listener), but has no setState. Its state is plain data from the stream. Commands, and disconnect(), are on the store itself and never change identity. disconnect() stops the stream and retries, and keeps the last state.
const workspace = createWorkspaceStore('/api')const [familiar] = await workspace.familiars.list()const room = createRoomStore('/api', await workspace.familiars.dm(familiar.id))await room.send('Hello')Every store has connection: 'connecting' | 'open' | 'reconnecting' | 'unauthorized' | 'failed' | 'outdated'. It goes open when the server’s handshake matches, before the first values arrive.
| Store | Field | Type | Notes |
|---|---|---|---|
| Workspace | familiars |
FamiliarsState | null | undefined |
{ familiars }, who each one is, by ID |
| Workspace | rooms |
RoomsState | null | undefined |
{ rooms }, by ID: named rooms and own DMs, as a list shows them (below) |
| Workspace | me |
Author | null | undefined |
{ id, name }: this person’s author ID and the name Familiars call them |
| Workspace | account |
AccountState | null | undefined |
null when the host manages credentials |
| Familiar | model |
AgentState | null | undefined |
Its model and reasoning level |
| Familiar | memory |
MemoryState | null | undefined |
{ subjects, next, months, forgotten }: who and what it knows about |
| Familiar | schedules |
SchedulesState | null | undefined |
|
| Room | transcript |
Transcript | undefined |
{ items, busy, earlier } |
| Room | view |
ConversationView | undefined |
The room log’s view, as streamed |
| Room | turns |
RoomActivity | null | undefined |
Activity keyed by Familiar ID |
Each document is undefined until it arrives and null when the stream sends none.
Rooms list
Section titled “Rooms list”Every room in rooms is a RoomListing: its setup (Room) and what a sidebar shows of it, all on the workspace’s one stream, so a list never opens a stream per room.
type RoomListing = Room & { last?: RoomPreview // its newest entry worth showing; absent until one is posted unread?: number // entries since this person's read marker turns: { familiar: number; status: 'queued' | 'elsewhere' | 'running' }[]}
type RoomPreview = { entry: number // compare with a read marker, or pass to `read` at: number // ms since the epoch: sort by it for most recent first text: string // the start of what it says, on one line} & ( | { kind: 'message'; author: Author } | { kind: 'reply' familiar: number name: string outcome: 'answered' | 'failed' | 'stopped' } | { kind: 'handoff' | 'reminder'; familiar: number; name: string } | { kind: 'note' })Staying quiet adds no entry. A last reply whose outcome is failed means the room’s last turn failed. turns is empty when no one is working on the room; a Familiar elsewhere is busy in another room, which isn’t said. unread counts from the person’s marker, which their own messages move, and the room store’s read(entry) moves; it’s every entry if they’ve never read the room.
Commands
Section titled “Commands”Commands return promises that reject with the server’s error. They aren’t retried. Each one calls the route operation of the same name, except loadOlder() and loadGap(gap), which call rooms.history.
| Store | Group | Commands |
|---|---|---|
| Workspace | familiars |
list(), create(identity), update(id, change), remove(id), dm(id) (the room ID) |
| Workspace | rooms |
list(), create(setup), update(id, change), archive(id), unarchive(id) |
| Workspace | me |
rename(name) |
| Workspace | account |
signIn(), answerSignIn(text), cancelSignIn(), signOut() |
| Workspace | push |
key() (undefined when the host has no push), subscribe(subscription), unsubscribe(subscription) |
| Workspace | connections |
list(), setSecret(connection, secret, value), deleteSecret(connection, secret) |
| Workspace | mcp |
add(server), remove(name), reconnect(name) |
| Familiar | model |
options(), set(ref), setThinkingLevel(level) |
| Familiar | memory |
section(), page(subject), forget(note) |
| Familiar | schedules |
cancel(id), pause(id), resume(id) |
| Room | send(text, mentions?), note(text), retry(reply), stop(), read(entry), loadOlder() |
send and note generate the requestId. retry(reply) tries a failed reply’s turn again; the transcript sets retry to that ID on a failed reply’s last item while it can be. A note is context the room’s Familiars see on their next turn, which no one replies to. loadOlder() loads the page before the transcript’s start while transcript.earlier is true; calls made while one loads share it. familiars.update takes { name?, persona?, avatar?, chatModel?, memoryModel? }; a null persona, avatar or model returns it to the default. chatModel is the model that Familiar answers with and memoryModel the one its memory filing and consolidation run on, each one of the workspace’s modelChoices. A memoryModel may carry a thinkingLevel. defaults.models() returns the workspace’s { chat, memory } defaults, each with its thinkingLevel, and every ModelOption; defaults.setModels({ chat?, memory? }) changes them, each a model with an optional level. An avatar is a short string your UI interprets, such as an index into its portraits; core only keeps it. unarchive calls rooms.update with { archived: false }. read(entry) marks the room read up to the newest entry the person has seen, such as its last.entry, and never moves the marker back. me.rename(name) changes what Familiars call the person from their next message.
Transcript
Section titled “Transcript”type TranscriptItem = | { type: 'gap'; id: string; gap: TranscriptGap } | { type: 'message' id: string author: Author text: string at: number mentions?: Mention[] } | { type: 'reply' id: string familiar: number name?: string // its name when it replied text: string thinking: string toolCalls: ToolCall[] at?: number stopped: boolean error?: string // why it failed, or the model's error } | { type: 'scheduled' id: string familiar: number prompt: string creator?: Author due: number }// The union also includes historical handoffs and room notes.
type ReplyingFamiliar = { familiar: number questions?: Question[] retrying?: Retrying tools?: ToolCall[]}
// A model request that failed, tried again `at`.type Retrying = { at: number; error: string }
type ToolCall = { id: string name: string arguments: Record<string, unknown> status: 'running' | 'done' | 'error' output: string details?: unknown}Times are milliseconds since the epoch. transcript.items contains the room’s history and gaps. A reply appears with its tool calls when it lands.
transcript.replying lists the Familiars currently working on this room. Pending tool approvals and server questions are in questions. retrying gives the retry time and the failed model request’s error. tools contains live calls for the current round, with their available arguments and output. transcript.busy covers both replying and queued work.
Helpers
Section titled “Helpers”ConversationTranscriptis re-exported from Pi for clients that assemble their own history. Its gap objects pass directly toloadGap.toRoomTranscript(view, turns?)projects an assembled PiTranscriptViewand optional room activity into a Familiar transcript. The room store already does this; use it for other clients.composeMessage(parts)turns a composer’s text and picked names,{ kind, id, name }, into{ text, mentions }: each pick becomes@Namein the text with a mention spanning it. Pass both tosend.
Import from @familiar-ai/client/react. Requires React 18 or 19. The bindings are for a room; use Zustand’s useStore with the other stores.
| Binding | Meaning |
|---|---|
RoomProvider |
{ store, children }. Doesn’t open or close the store |
useRoom(selector) |
Select from state. Compares with Object.is |
useRoomStore() |
The nearest provider’s store, for its commands |
The transcript retains loaded history across reconnects, and a reconnect resumes right after its newest entry. A gap item marks messages still missing, as after a disconnect too long to resume; loadGap(gap) fills it through the history endpoint and rejects if loading fails.