7.8 KiB
Session Management
Understanding how the Claude Agent SDK handles sessions and session resumption
Session Management
The Claude Agent SDK provides session management capabilities for handling conversation state and resumption. Sessions allow you to continue conversations across multiple interactions while maintaining full context.
How Sessions Work
When you start a new query, the SDK automatically creates a session and returns a session ID in the initial system message. You can capture this ID to resume the session later.
Getting the Session ID
options: { options: { model: "claude-sonnet-4-5" } })
for await (const message of response) { // The first message is a system init message with the session ID
if (message.type === 'system' && message.subtype === 'init') { if (message.type === 'system' && message.subtype === 'init') {
sessionId = message.session_id
console.log(`Session started with ID: ${sessionId}`)
// You can save this ID for later resumption
}
// Process other messages... // Process other messages... console.log(message) }
// Later, you can use the saved sessionId to resume if (sessionId) { const resumedResponse = query({
prompt: "Continue where we left off",
options: {
resume: sessionId
}
})
}
from claude_agent_sdk import query, ClaudeAgentOptions
session_id = None
async for message in query(
prompt="Help me build a web application",
options=ClaudeAgentOptions( options=ClaudeAgentOptions(
model="claude-sonnet-4-5"
)
):
## The first message is a system init message with the session ID
if hasattr(message, 'subtype') and message.subtype == 'init': if hasattr(message, 'subtype') and message.subtype == 'init':
session_id = message.data.get('session_id')
print(f"Session started with ID: {session_id}")
# You can save this ID for later resumption
Process other messages... # Process other messages
print(message)
Later, you can use the saved session_id to resume
if session_id: async for message in query(
prompt="Continue where we left off", prompt="Continue where we left off",
options=ClaudeAgentOptions(
resume=session_id
)
):
print(message)
Resuming Sessions
The SDK supports resuming sessions from previous conversation states, enabling continuous development workflows. Use the resume option with a session ID to continue a previous conversation.
options: { options: { resume: "session-xyz", // Session ID from previous conversation model: "claude-sonnet-4-5", allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"] } })
// The conversation continues with full context from the previous session for await (const message of response) { console.log(message) }
```python Python theme={null}
from claude_agent_sdk import query, ClaudeAgentOptions
## Resume a previous session using its ID
async for message in query(
prompt="Continue implementing the authentication system from where we left off",
options=ClaudeAgentOptions( options=ClaudeAgentOptions(
resume="session-xyz", # Session ID from previous conversation
model="claude-sonnet-4-5",
allowed_tools=["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
)
):
print(message)
## The conversation continues with full context from the previous session
The SDK automatically handles loading the conversation history and context when you resume a session, allowing Claude to continue exactly where it left off.
Forking Sessions
When resuming a session, you can choose to either continue the original session or fork it into a new branch. By default, resuming continues the original session. Use the forkSession option (TypeScript) or fork_session option (Python) to create a new session ID that starts from the resumed state.
When to Fork a Session
Forking is useful when you want to:
- Explore different approaches from the same starting point
- Create multiple conversation branches without modifying the original
- Test changes without affecting the original session history
- Maintain separate conversation paths for different experiments
Forking vs Continuing
| Behavior | forkSession: false (default) |
forkSession: true |
|---|---|---|
| Session ID | Same as original | New session ID generated |
| History | Appends to original session | Creates new branch from resume point |
| Original Session | Modified | Preserved unchanged |
| Use Case | Continue linear conversation | Branch to explore alternatives |
Example: Forking a Session
options: { model: "claude-sonnet-4-5" } options: { model: "claude-sonnet-4-5" } })
for await (const message of response) { if (message.type === 'system' && message.subtype === 'init') {
sessionId = message.session_id sessionId = message.session_id
console.log(`Original session: ${sessionId}`)
}
// Fork the session to try a different approach
const forkedResponse = query({
prompt: "Now let's redesign this as a GraphQL API instead",
```python
options: { options: {
resume: sessionId,
forkSession: true, // Creates a new session ID
model: "claude-sonnet-4-5"
}
})
for await (const message of forkedResponse) {
if (message.type === 'system' && message.subtype === 'init') {
```python
console.log(`Forked session: ${message.session_id}`) console.log(`Forked session: ${message.session_id}`)
// This will be a different session ID
}
// The original session remains unchanged and can still be resumed
const originalContinued = query({
prompt: "Add authentication to the REST API",
```python
options: { options: {
resume: sessionId,
forkSession: false, // Continue original session (default)
model: "claude-sonnet-4-5"
}
})
from claude_agent_sdk import query, ClaudeAgentOptions
## First, capture the session ID
session_id = None
async for message in query(
prompt="Help me design a REST API",
```python
options=ClaudeAgentOptions(model="claude-sonnet-4-5") options=ClaudeAgentOptions(model="claude-sonnet-4-5")
):
if hasattr(message, 'subtype') and message.subtype == 'init':
```python
session_id = message.data.get('session_id') session_id = message.data.get('session_id')
print(f"Original session: {session_id}")
## Fork the session to try a different approach
async for message in query(
prompt="Now let's redesign this as a GraphQL API instead",
```python
options=ClaudeAgentOptions( options=ClaudeAgentOptions(
resume=session_id,
fork_session=True, # Creates a new session ID
model="claude-sonnet-4-5"
)
):
if hasattr(message, 'subtype') and message.subtype == 'init':
```python
forked_id = message.data.get('session_id') forked_id = message.data.get('session_id')
print(f"Forked session: {forked_id}")
## This will be a different session ID
## The original session remains unchanged and can still be resumed
async for message in query(
prompt="Add authentication to the REST API",
```python
options=ClaudeAgentOptions( options=ClaudeAgentOptions(
resume=session_id,
fork_session=False, # Continue original session (default)
model="claude-sonnet-4-5"
)
):
print(message)