React hooks

Run a Kortix session in React with the useSession hook.

@kortix/sdk/react adds React hooks on top of the SDK. This page covers useSession, the hook that runs a session end to end, and the other hooks confirmed stable for React apps.

useSession(projectId, sessionId, options?)

useSession starts the session, opens the server-selected event transport, and syncs messages, status, and pending prompts. Call it once per session view.

import { useSession } from '@kortix/sdk/react';

function Chat({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const s = useSession(projectId, sessionId);

  if (s.phase !== 'ready') return <Booting stage={s.stage} onRetry={s.retry} />;

  return (
    <>
      {s.messages.map(({ info, parts }) => (
        <Message key={info.id} info={info} parts={parts} />
      ))}
      <Composer busy={s.isBusy} onSend={s.send} onStop={s.cancel} />
    </>
  );
}

Readiness is server truth. The runtime is ready when POST /start returns stage: 'ready'. useSession does not run a separate client-side health check.

Returns

Field	Type	What it holds
`phase`	`'starting' \| 'ready' \| 'error'`	Overall state. Render a boot screen until `ready`.
`messages`	`{ info, parts }[]`	The message list. Parts stream in live.
`status`	`SessionStatus`	The session status.
`isBusy`	`boolean`	The agent is generating a reply.
`questions`, `permissions`	array	Pending agent questions and tool-approval requests. A `permission` here is one runtime tool approval, not an IAM permission.
`diffs`, `todos`	array	Live file diffs and todo items.
`sendError`	`KortixSendError \| null`	The last `send` failure: `billing`, `runtime-not-ready`, or `runtime-error`.
`rewindMessageId`	`string \| null`	The selected user message while a reversible rewind is staged.
`rewindPending`	`boolean`	A rewind or restore request is in progress.
`rewindError`	`KortixSendError \| null`	The last rewind or restore failure.
`models`, `agents`, `defaultAgent`, `commands`	—	Selectable models, selectable agents, the default agent, and slash commands. Available before the runtime starts.
`retry`	`() => void`	Force a re-check of `/start`.

Actions

Action	What it does
`send(text, override?)`	Send a prompt. `override` sets `{ model?, agent? }` for this message only.
`sendParts(parts, override?)`	Send text and runtime URL file parts through the selected transport. Private staged handles use platform prompt routes.
`rewind(messageId)`	Rewind this canonical session to a user message. The selected message and later path become hidden and recoverable.
`restoreRewind()`	Restore the removed path before another prompt commits its replacement.
`cancel()`	Stop the current run and clear pending questions and permissions.
`runCommand(command, args)`	Run a project slash command.
`answerQuestion(id, answers)`	Answer a pending agent question.
`rejectQuestion(id)`	Reject a pending agent question.
`answerPermission(id, reply, message?)`	Answer a tool-approval request. `reply` is `'once'`, `'always'`, or `'reject'`.

useSession also returns removeQuestion and removePermission. Do not use them. They clear the prompt from local state but never notify the agent, so the run stays blocked. Use answerQuestion, rejectQuestion, or answerPermission instead.

Options

Option	Default	What it does
`waitMs`	`15000`	The long-poll budget sent to `/start`.
`replayStartStash`	`true`	Replay a prompt saved before the session existed, once the session is ready.
`enabled`	`true`	Set `false` to delay the hook, for example until a billing check passes.
`chatEngine`	`true`	Set `false` if your app mounts its own chat surface for this session, to avoid syncing messages twice.

Sending is optimistic. send shows your message right away, then stream events fill in the agent’s reply.

rewind(messageId) never creates a session. It uses the canonical session from POST /start. The runtime restores file state and keeps the removed transcript path recoverable. The next accepted prompt commits the replacement path.

Other stable hooks

@kortix/sdk/react also exports React Query hooks for data that does not need a running session. Each mirrors a method on the client and needs no provider.

Hook	Reads
`useProjectModels(projectId)`	Selectable models for the project.
`useProjectModelPickerCatalog(projectId)`	The raw `/model-picker` record per wire model (`reasoning_options`, `temperature`, `limit`) for capability-gated controls.
`useVisibleAgents({ projectId })`	The project’s visible agents.
`useProjectConfig(projectId)`	The project’s runtime config: default agent, commands.
`useProjectSecrets(projectId)`	Secrets: list, add, remove, and personal overrides.
`useProjectTriggers(projectId)`	Triggers: list, create, update, remove, fire.
`useChangeRequests(projectId, status?)`	Change requests: list, open, merge, close, request changes.

Sessions — the session handle useSession wraps, and the KortixSendError kinds.
Reference — the full REST surface these hooks read from.