Client sessions namespace

client.sessions manages agent session records. A session is the server-side work unit shared by the agent runtime and chat persistence. It is not the process itself.

sessions.list()

await client.sessions.list(): Promise<{ sessions: SessionInfo[] }>

Returns a point-in-time snapshot of all sessions. Use onSnapshot for live UI updates.

const { sessions } = await client.sessions.list();
const running = sessions.filter((session) => session.alive);

sessions.create(opts?)

await client.sessions.create(opts?: {
  id?: string;
  label?: string;
  cwd?: string;
  meta?: Record<string, unknown>;
}): Promise<{ status: "created"; sessionId: string; label: string; meta: Record<string, unknown> | null }>

const { sessionId } = await client.sessions.create({
  label: "review: checkout-flow",
  cwd: "/Users/me/app",
  meta: { projectId: "checkout" },
});
await client.agent.start(sessionId, { provider: "claude-code" });

With HTTP transport enabled, the promise resolves after the database row is committed. Calling agent.start immediately after create is safe.

sessions.update(session, opts)

await client.sessions.update(session: string, opts: {
  label?: string;
  meta?: Record<string, unknown>;
  cwd?: string;
}): Promise<{ status: "updated"; session: string }>

This does not change model or permission mode for a running agent. Use client.agent.update, setModel, or setPermissionMode for runtime settings.

sessions.remove(session)

await client.sessions.remove(session: string): Promise<{ status: "removed" }>

Deletes the session record, persisted history, runtime chain, and any pending permission request. If an agent process exists, it is stopped before removal. The default session cannot be removed. Calls that still target the removed session return no-session or no-active-session errors.

sessions.onSnapshot(callback)

const unsubscribe = client.sessions.onSnapshot((sessions: SessionInfo[]) => void);

The callback receives the full session list every time. Replace local state with the snapshot instead of applying diffs. It fires after WebSocket connection, lifecycle changes, and agent status changes.

sessions.onConfigChanged(callback)

const unsubscribe = client.sessions.onConfigChanged(
  (event: { session: string; [key: string]: unknown }) => void,
);

Use this when a settings UI needs to reflect model, permission mode, or runtime defaults changed by another client.