Skip to main content
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);
  }
}

​
Generating Session Titles

Use q.generateSessionTitle() when the host application needs a short display title for an existing session: 
const title = await q.generateSessionTitle(
  'User asked the agent to review authentication middleware and fix failing tests.',
);
The CLI returns the generated title through a control response. The current headless control path does not persist the title; persisted ai-title transcript entries are still visible through session-list APIs.

​
Reading Subagent Transcripts

Subagents write their own transcripts under the parent session. After the parent session completes, use listSubagents() to discover subagent IDs, then getSubagentMessages() to read one subagent’s message chain: 
import { getSubagentMessages, listSubagents } from '@qoder-ai/qoder-agent-sdk';

const agentIds = await listSubagents(sessionId, { dir: '/path/to/project' });

for (const agentId of agentIds) {
  const messages = await getSubagentMessages(sessionId, agentId, {
    dir: '/path/to/project',
  });

  console.log(agentId, messages.length);
}
getSubagentMessages() follows the subagent transcript’s parent chain and returns user / assistant messages in chronological order.