[FEATURE] Dynamic working directory switching for instance pooling

[konglinghai123]

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When deploying Claude Agent SDK in a server-side environment handling multiple concurrent users, we face critical performance bottlenecks:

1. Slow Initialization Per Instance Each new SDK instance initialization takes 20-30+ seconds (related: #2166, #3044). For a server handling concurrent requests, this latency is unacceptable:

Initial user requests timeout or have poor UX Cannot achieve target response time of < 2s Resource waste during initialization

2. High Resource Consumption with Multiple Sessions Running separate instances per session leads to:

Excessive memory/CPU usage as concurrent sessions grow Scaling challenges for multi-tenant deployments Increased infrastructure costs

3. No Instance Reuse Mechanism Currently, there's no official way to:

Keep SDK processes in a "warm" state between different user sessions Reuse initialized instances across different contexts Dynamically change the working directory for an active instance

Proposed Solution

Feature Request: Dynamic Tool Directory Switching Proposed API Python: pythonfrom claude_agent_sdk import ClaudeSDKClient

Initialize once (warm pool)

client = ClaudeSDKClient()

Dynamically switch working directory per session

client.set_working_directory("/workspace/user_session_1") response1 = client.send_message("Analyze this project")

Reuse same instance for different session

client.set_working_directory("/workspace/user_session_2") response2 = client.send_message("Debug this code") TypeScript: typescriptimport { ClaudeSDKClient } from '@anthropic-ai/claude-code';

const client = new ClaudeSDKClient();

// Switch context per session await client.setWorkingDirectory('/workspace/user_session_1'); const response1 = await client.sendMessage('Analyze this project');

await client.setWorkingDirectory('/workspace/user_session_2'); const response2 = await client.sendMessage('Debug this code'); Benefits

Instance Pooling: Maintain a pool of pre-warmed SDK instances (e.g., 5-10 processes) that can be dynamically assigned to incoming requests Eliminate Cold Start: Reduce request latency from 20-30s to < 1s Better Resource Utilization: Maintain fewer processes while serving more concurrent users Horizontal Scalability: Enable efficient load balancing across server instances

Implementation Considerations

Isolation: Ensure complete isolation of file operations between directory switches State Reset: Provide option to reset shell environment/context when switching directories Safety: Validate directory paths and permissions before switching Backwards Compatibility: Add as opt-in feature without breaking existing APIs

Alternative Solutions

If dynamic directory switching is architecturally challenging, other approaches that would help:

Significantly Faster Initialization (< 1s target instead of 20-30s) Built-in Instance Pooling: SDK-managed warm instance pool with automatic lifecycle management Lightweight Reset API: Method to reset instance state without full reinitialization Multi-Session Mode: Built-in support for isolated sessions within a single process

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

No response

Additional Context

No response