> ## 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.

# 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.

<div id="concepts" />

## 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](/en/cli/sdk/authentication).

<div id="creating-new-sessions" />

## Creating New Sessions

<div id="default" />

### Default

Without passing any session-related fields, a new session is created each time:

```typescript theme={null}
const q = query({
  prompt: 'Hello',
  options: { auth: accessTokenFromEnv() },
});
```

<div id="specifying-a-session-id" />

### Specifying a Session ID

Let the caller determine the session UUID (suitable when the host manages its own session index):

```typescript theme={null}
import { randomUUID } from 'node:crypto';

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

<div id="resuming-sessions" />

## Resuming Sessions

<div id="resume-by-id" />

### Resume by ID

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

<div id="resume-the-most-recent" />

### Resume the Most Recent

When you don't know the session ID, use `continue: true` to pick up the most recently modified session:

```typescript theme={null}
const q = query({
  prompt: 'Continue',
  options: {
    auth: accessTokenFromEnv(),
    continue: true,
  },
});
```

Do not pass `resume` and `continue` simultaneously.

<div id="forking-sessions" />

## 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:

```typescript theme={null}
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:

```typescript theme={null}
options: {
  auth: accessTokenFromEnv(),
  resume: 'source-session-id',
  forkSession: true,
  sessionId: 'my-new-session-id',
}
```

<div id="field-reference" />

## 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                                    |

<div id="getting-the-current-session-id" />

## Getting the Current Session ID

Listen for the `init` message:

```typescript theme={null}
for await (const msg of q) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    console.log('session_id:', msg.session_id);
  }
}
```