> ## 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, `QoderSDKClient` starts a brand new session with each connection. Through several fields in `QoderAgentOptions`, 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_session` operations.

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

<div id="creatingnewsessions" />

## Creating New Sessions

<div id="default" />

### Default

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

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, QoderSDKClient, qodercli_auth

options = QoderAgentOptions(auth=qodercli_auth())

async with QoderSDKClient(options=options) as client:
    await client.query("Hello")
    async for msg in client.receive_response():
        ...
```

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

<div id="specifyingasessionid" />

### Specifying a Session ID

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

```python theme={null}
import uuid

session_id = str(uuid.uuid4())

options = QoderAgentOptions(
    auth=qodercli_auth(),
    session_id=session_id,
)

async with QoderSDKClient(options=options) as client:
    await client.query("Hello")
    async for msg in client.receive_response():
        ...
```

<div id="resuming-sessions" />

<div id="resumingsessions" />

## Resuming Sessions

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

<div id="resumebyid" />

### Resume by ID

```python theme={null}
options = QoderAgentOptions(
    auth=qodercli_auth(),
    resume="previous-session-id",
)

async with QoderSDKClient(options=options) as client:
    await client.query("Continue the previous conversation")
    async for msg in client.receive_response():
        ...
```

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

<div id="resumethemostrecent" />

### Resume the Most Recent

When you don't know the session ID, use `continue_conversation=True` to pick up the most recently modified session:

```python theme={null}
options = QoderAgentOptions(
    auth=qodercli_auth(),
    continue_conversation=True,
)

async with QoderSDKClient(options=options) as client:
    await client.query("Continue")
    async for msg in client.receive_response():
        ...
```

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

<div id="forking-sessions" />

<div id="forkingsessions" />

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

```python theme={null}
options = QoderAgentOptions(
    auth=qodercli_auth(),
    resume="source-session-id",
    fork_session=True,
)

async with QoderSDKClient(options=options) as client:
    await client.query("Based on the prior context, explore a different direction")
    async for msg in client.receive_response():
        ...
```

To specify an ID for the forked new session:

```python theme={null}
options = QoderAgentOptions(
    auth=qodercli_auth(),
    resume="source-session-id",
    fork_session=True,
    session_id="my-new-session-id",
)
```

<div id="field-reference" />

<div id="fieldreference" />

## Field Reference

| Field                   | Type   | Behavior                                                                            |
| ----------------------- | ------ | ----------------------------------------------------------------------------------- |
| `session_id`            | `str`  | Used alone: creates with this ID; with `fork_session`: ID of the new forked session |
| `resume`                | `str`  | Session ID to resume                                                                |
| `continue_conversation` | `bool` | `True` resumes the most recent session                                              |
| `fork_session`          | `bool` | Used with `resume`; forks rather than continues                                     |

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

<div id="gettingthecurrentsessionid" />

## Getting the Current Session ID

The `data` dict of the `init` system message carries `session_id`; `ResultMessage` carries it too. Either can be used for bookkeeping:

```python theme={null}
from qoder_agent_sdk import ResultMessage, SystemMessage

current_session_id = None

async with QoderSDKClient(options=options) as client:
    await client.query("Hello")
    async for msg in client.receive_response():
        if isinstance(msg, SystemMessage) and msg.subtype == "init":
            current_session_id = msg.data["session_id"]
            print(f"session: {current_session_id}")
        elif isinstance(msg, ResultMessage):
            current_session_id = msg.session_id
```