React hooks

@kortix/sdk/react is the reactive half of the SDK. Where createKortix(...) is imperative — you call a method, you get a promise — these hooks subscribe to live data and re-render as it changes. They're built on React Query and zustand, and kept current by OpenCode's SSE event stream.

You almost never touch the runtime plumbing directly. One hook runs a session:

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}
        disabled={s.runtimePhase !== 'ready'}
        onSend={(text) => s.send(text)}
        onStop={s.cancel}
      />
    </>
  );
}

That's the whole contract. No event provider to mount, no health poller, no "server store" to switch, no sandbox id, no canonical-session resolution — useSession owns all of it internally.

useSession(projectId, sessionId, options?)

The single hook for an open session. Internally it drives POST /start (the server long-polls), resolves the session's runtime, opens the SSE stream, resolves the canonical OpenCode id, and syncs messages — exposing one phase plus the thread, the actions, the interactive prompts, and the pre-runtime capabilities.

Readiness is server-truth: the runtime is ready when /start returns stage: 'ready' (the backend only returns that once the daemon answered). There is no client-side health poll — so a fresh session's first turn streams immediately, and the old "stuck until you hard-refresh" failure mode cannot occur.

Call it once per session view (like a provider) — it owns the SSE subscription and the /start poll for that (projectId, sessionId).

Returns

Actions

Options

KortixProjectProvider

useSession itself needs no provider — but a few route-scoped hooks (like useOpenCodeProviders() under More hooks) resolve "the project the user is looking at" from React context instead of a parameter, since the SDK is router-agnostic and can't call useParams() itself. A Next (or other router-based) host derives the project id once and mounts the provider near its root:

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

function ProjectLayout({ projectId, children }: { projectId: string; children: React.ReactNode }) {
  return <KortixProjectProvider projectId={projectId}>{children}</KortixProjectProvider>;
}

useKortixRouteProjectId() is the read side — it's what those hooks call internally, and it's exported for a host that wants the same value. Outside a project scope it returns null.

Capability hooks (available before the runtime)

Model, agent, and command catalogs come from the server, so you can build a picker on a "new session" screen before any sandbox exists. These are plain React Query reads — no runtime required.

import { useProjectModels, useVisibleAgents, useProjectConfig } from '@kortix/sdk/react';

const models = useProjectModels(projectId);        // selectable model rows
const agents = useVisibleAgents({ projectId });    // visible agents
const config = useProjectConfig(projectId);        // { open_code_default_agent, commands, … }

useSession already exposes these as s.models / s.agents / s.defaultAgent / s.commands for a session view; use the standalone hooks on screens that don't hold a session yet.

Primitives

Small building blocks the white-label reference uses — all owned by the SDK so every host shares one implementation.

Start-stash — the new-session → workbench hand-off. Your "what would you like to build?" screen collects a prompt + model + agent before the runtime exists; stash them under the new id, and useSession replays them as the first message once ready:

import { writeStartStash } from '@kortix/sdk/react';
import { generateSessionId } from '@kortix/sdk'; // root entry — not re-exported from /react

// new-session screen:
const sessionId = generateSessionId();
await kortix.project(projectId).sessions.create({ session_id: sessionId, name });
writeStartStash(sessionId, { prompt, model, agent });
router.push(`/projects/${projectId}/sessions/${sessionId}`);
// the session page just calls useSession(...) — the stash replays automatically.

Also readStartStash(sessionId) / clearStartStash(sessionId) / startStashKey.

A sibling fork-draft stash covers the same hand-off for forking a session at a message: stash the draft under the new forked session's id before navigating to it, then useForkSession() (below, under "Session list & CRUD") picks it up the same way useSession picks up a start-stash. forkDraftKey, writeForkDraft(sessionId, draft), readForkDraft(sessionId), clearForkDraft(sessionId).

Session list & CRUD

The session list and per-session lifecycle, as React Query queries and mutations.

import {
  useOpenCodeSessions,
  useCreateOpenCodeSession,
  useUpdateOpenCodeSession,
  useDeleteOpenCodeSession,
} from '@kortix/sdk/react';

function Sidebar() {
  const { data: sessions = [] } = useOpenCodeSessions();
  const create = useCreateOpenCodeSession();
  const rename = useUpdateOpenCodeSession();
  const remove = useDeleteOpenCodeSession();
  // …
}

Project data hooks

Reactive counterparts of the imperative p.secrets / p.triggers / p.changeRequests surfaces on The client — each a thin React Query binding with its own query-key factory, and mutations that invalidate the list so a write reflects without a manual refetch.

import { useProjectSecrets, useProjectTriggers, useChangeRequests } from '@kortix/sdk/react';

const secrets = useProjectSecrets(projectId);      // { data, upsert, remove, setPersonal, removePersonal }
const triggers = useProjectTriggers(projectId);     // { data, create, update, remove, fire }
const crs = useChangeRequests(projectId, 'open');   // { data, open, merge, close, requestChanges }

Runtime config

Read and write OpenCode's runtime config (opencode.jsonc as the server sees it); updates are optimistic and roll back on error.

import { useOpenCodeConfig, useUpdateOpenCodeConfig } from '@kortix/sdk/react';

const { data: config } = useOpenCodeConfig();
const update = useUpdateOpenCodeConfig();
update.mutate({ permission: { edit: 'allow' } });

MCP servers

useOpenCodeMcpStatus(), useAddMcpServer(), useConnectMcpServer(), useDisconnectMcpServer(), and the OAuth trio useMcpAuthStart() / useMcpAuthCallback() / useMcpAuthRemove().

PTY terminal

A live terminal into the session's sandbox — list/create/remove/resize PTYs, then open a WebSocket for the byte stream.

import { useOpenCodePtyList, useCreatePty, useRemovePty, getPtyWebSocketUrl } from '@kortix/sdk/react';

const { data: ptys = [] } = useOpenCodePtyList();
const create = useCreatePty();
const url = await getPtyWebSocketUrl(id);   // wss://… with the auth token appended

Use useUpdatePty() to push a title or { rows, cols } resize.

Model store

useModelStore(allModels, opts?) is a zustand-backed store of the user's model preferences — visibility, recents, per-agent and per-session selections, the global default, variants. Persisted client-side and pure UI state (it does not fetch — pass the flattened catalog from kortix.project(id).llmCatalog() or useProjectModels()).

import { useModelStore, type ModelKey } from '@kortix/sdk/react';

const store = useModelStore(models, { connectedProviderIds });
store.setSessionModel(sessionId, model);

Helpers include isVisible / setVisibility, recent / pushRecent, getVariant / setVariant, getSessionModel / setSessionModel, globalDefault / setGlobalDefault, and userPrefs; seedGlobalDefaultFromServer(model) — a plain function, not a hook — seeds the global default from the server the first time it resolves.

Lower-level hooks (what useSession composes)

More hooks

The opencodeKeys query-key factory is exported too, for targeted invalidateQueries / setQueryData against the same cache.

Kortix Master (tasks, tickets, credentials, projects)

@kortix/sdk/react also re-exports the full Kortix Master React Query layer — the hooks behind a project's task board, ticket/kanban system, credentials vault, and project/team management. This is the same hook set apps/web's Kortix UI runs on end to end; it's exported from the SDK so any host can build the same surface.

These hooks talk to the /kortix/* daemon routes and are otherwise plain React Query — no relation to useSession's runtime plumbing.

interface KortixMasterIdentity {
  userId: string | null;
  handle: string;      // stamped as actor_id / created_by_id on mutations
  isLoading: boolean;
}

Credentials

A project's secrets vault (/kortix/projects/:id/credentials) — values are never returned by the list call; useRevealCredential is a separate, audit-logged read.

import { useCredentials, useUpsertCredential, useRevealCredential } from '@kortix/sdk/react';

const { data: credentials = [] } = useCredentials(projectId);
const upsert = useUpsertCredential();
upsert.mutate({ projectId, name: 'STRIPE_KEY', value: 'sk_...', description: 'Stripe secret key' });

Kortix projects

The project registry itself (/kortix/projects) — distinct from an SDK Project (a sandbox/session container); a Kortix project is the task/ticket/credentials workspace layered on top.

import { useKortixProjects, useKortixProject, usePatchProject } from '@kortix/sdk/react';

const { data: projects = [] } = useKortixProjects(identity);
const { data: project } = useKortixProject(identity, projectId);

Tasks

The async task queue (/kortix/tasks) — a task is a unit of work an agent picks up, with a verification_condition an approval step checks against.

import { useKortixTasks, useCreateKortixTask, useStartKortixTask, useApproveKortixTask } from '@kortix/sdk/react';

const { data: tasks = [] } = useKortixTasks(projectId, 'in_progress');
const create = useCreateKortixTask();
create.mutate({ project_id: projectId, title: 'Fix the flaky test', verification_condition: 'CI green' });

KortixTaskStatus is one of todo · in_progress · input_needed · awaiting_review · completed · cancelled.

Tickets & kanban

The full ticket system (/kortix/tickets) plus a project's board configuration — columns, custom fields, templates, and the team of project agents tickets get assigned to.

import { useTickets, useCreateTicket, useAssignTicket, useCommentTicket } from '@kortix/sdk/react';

const { data: tickets = [] } = useTickets(projectId);
const createTicket = useCreateTicket(identity);
createTicket.mutate({ project_id: projectId, title: 'Ship the react.mdx page' });

Activity & notifications — derived client-side from the ticket event stream, no separate notifications endpoint:

import { useProjectActivity, computeNotifications, readLastSeen, writeLastSeen } from '@kortix/sdk/react';

const { data: events = [] } = useProjectActivity(projectId); // polls 10s
const notifications = computeNotifications(events, identity.handle, readLastSeen(projectId, identity.handle));

Milestones

Grouping/tracking layer above tickets (/kortix/projects/:id/milestones) — a milestone has an acceptance note and closes with a summary.

Sandbox services

Long-running background processes inside the sandbox (/kortix/services) — dev servers, databases, workers — registered and supervised by the daemon.

Next

• The client — the imperative createKortix facade.
• Sessions — the imperative session handle + the runtime.
• Modules — lower-level subpath imports.