@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 permission requests.
`diffs`, `todos`	array	Live file diffs and todo items.
`sendError`	`KortixSendError \| null`	The last `send` failure: `billing`, `runtime-not-ready`, or `runtime-error`.
`runtimeTransport`	`'rest' \| 'acp'`	The server-selected transport. Display it for diagnostics only. Do not branch on it.
`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 file prompt parts through the selected transport.
`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 permission 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.

ACP experiment

The project experiment acp_runtime selects ACP. The default is REST. useSession owns both paths. The host does not construct /kortix/acp/ URLs and does not call OpenCode prompt routes directly. Disable the experiment to restore REST without changing the frontend.

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.
`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.

React hooks