Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

By default, query() starts a brand new session with each call. Through several fields in options, you can specify a session ID, resume a historical session, or fork from an existing session.

​
Concepts

A session corresponds to a persisted conversation history on the CLI side (including context, tool call records, compaction boundaries, etc.), identified by a UUID. The init system message contains the current session_id, which also serves as the anchor point for subsequent resume/fork operations. The auth: accessTokenFromEnv() shown in the examples below can be replaced with any other authentication method used in your project. See SDK Authentication.

​
Creating New Sessions

​
Default

Without passing any session-related fields, a new session is created each time: 
const q = query({
  prompt: 'Hello',
  options: { auth: accessTokenFromEnv() },
});

​
Specifying a Session ID

Let the caller determine the session UUID (suitable when the host manages its own session index): 
import { randomUUID } from 'node:crypto';

const sessionId = randomUUID();
const q = query({
  prompt: 'Hello',
  options: {
    auth: accessTokenFromEnv(),
    sessionId,
  },
});

​
Resuming Sessions

​
Resume by ID

const q = query({
  prompt: 'Continue the previous conversation',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'previous-session-id',
  },
});

​
Resume the Most Recent

When you don’t know the session ID, use continue: true to pick up the most recently modified session: 
const q = query({
  prompt: 'Continue',
  options: {
    auth: accessTokenFromEnv(),
    continue: true,
  },
});
Do not pass resume and continue simultaneously.

​
Forking Sessions

Derive a new session from an existing one, preserving the original context but obtaining a new session ID. The original session is unaffected: 
const q = query({
  prompt: 'Based on the prior context, explore a different direction',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'source-session-id',
    forkSession: true,
  },
});
To specify an ID for the forked new session: 
options: {
  auth: accessTokenFromEnv(),
  resume: 'source-session-id',
  forkSession: true,
  sessionId: 'my-new-session-id',
}

​
Field Reference

FieldTypeBehavior
sessionIdstringUsed alone: creates with this ID; with forkSession: ID of the new forked session
resumestringSession ID to resume
continuebooleantrue resumes the most recent session
forkSessionbooleanUsed with resume; forks rather than continues

​
Getting the Current Session ID

Listen for the init message: 
for await (const msg of q) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    console.log('session_id:', msg.session_id);
  }
}