Session Control

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:

import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

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

Field	Type	Behavior
sessionId	string	Used alone: creates with this ID; with forkSession: ID of the new forked session
resume	string	Session ID to resume
continue	boolean	true resumes the most recent session
forkSession	boolean	Used 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);
  }
}

User data directory

The user data directory stores session history, resources, logs, and other user-level CLI data. Set QODER_CONFIG_DIR through options.env to select this directory:

import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Analyze this repository',
  options: {
    auth: accessTokenFromEnv(),
    env: {
      ...process.env,
      QODER_CONFIG_DIR: '/var/lib/my-agent/qoder',
    },
  },
});