Set environment variables

The env option sets environment variables for the Claude Code process that runs your session. Whether your values replace the inherited environment or merge over it differs by language:

• TypeScript: env replaces the subprocess environment
• Python: the SDK merges your values over the inherited environment, and your values override the inherited ones

In TypeScript, spread process.env into env to keep inherited variables such as PATH, HOME, and ANTHROPIC_API_KEY. When you leave env unset, the subprocess inherits your environment in both languages.

The example routes API traffic through a gateway by setting ANTHROPIC_BASE_URL.

const options = {
env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

options = ClaudeAgentOptions(
env={"ANTHROPIC_BASE_URL": "https://gateway.example.com"},
)

The variables you pass can also configure Claude Code itself. For the variables the Claude Code process reads, see Environment variables. To tune API timeouts and stall detection this way, follow the Handle slow or stalled API responses section in the TypeScript reference or the Python reference.

Set the working directory

Set cwd to run the session in a specific directory. When you leave cwd unset, the session runs in your process's working directory. Neither SDK has a setter for cwd. To run in a different directory, start another session with that cwd.

Claude Code reads the working directory to determine:

• Project settings and hooks: which project's settings and hooks load
• Skills: where session skills are discovered
• Session storage: which project a stored session belongs to

To let tools reach files outside the working directory, add paths with additionalDirectories (TypeScript) or add_dirs (Python). For the scope of that grant, see Additional directories grant file access, not configuration.

Limit turns and spend

Cap turns and spend with maxTurns / max_turns and maxBudgetUsd / max_budget_usd. Both caps are off when unset. When a session hits a cap, the run ends with a result message whose subtype names the cap, error_max_turns or error_max_budget_usd. What happens next differs by input mode:

• Single-shot query(): the SDK yields the cap result and then raises, so wrap the loop in a try block to continue past the error
• Streaming input: the session stays alive past a cap result, and the max-turns count starts over for each queued message. The budget total accumulates across messages, and once spend reaches the cap, later messages in the same conversation end with the same budget result. A /clear starts the budget over

The two caps treat 0 differently:

• maxTurns / max_turns: 0 runs the session without a turn limit, the same as leaving the option unset
• maxBudgetUsd / max_budget_usd: the CLI rejects 0 as an invalid amount at startup, and the session never runs

For more information about both caps, including subagent spend, see Turns and budget.

Change configuration mid-session

When you start a session with streaming input, you can switch its model and permission mode while it runs. Where you call the setters differs by language:

• TypeScript: methods on the object query() returns
• Python: methods on ClaudeSDKClient, since query() returns a plain iterator without control methods

Both languages have the same setters:

• setModel() / set_model(): switches the model. Call it with no model to switch to Claude Code's default model rather than the model you passed in options.
• setPermissionMode() / set_permission_mode(): switches the permission mode

TypeScript also has applyFlagSettings() and updateSettings():

• applyFlagSettings(): applies settings at runtime, as in await session.applyFlagSettings({ effortLevel: "high" }). The method takes settings file keys rather than options fields, so check the applyFlagSettings() reference for the schema and for which keys take effect mid-session.
• updateSettings(): writes one allowlisted key to a settings file. The updateSettings() reference names the key each source accepts and the version floors.
  • Pass "localSettings" to write the project's local settings file, as in await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). The written key takes effect on the session's next request and persists for later sessions that load local settings.
  • Pass "userSettings" to write effortLevel, the only key that source accepts. Claude Code saves it as the default effort level for the session's current model, and the running session's effort doesn't change.

The example below runs a two-turn session, changes the configuration between the turns, and prints the model that answered each turn. In TypeScript, the prompt stream holds the second message until the setters have run, and the second turn runs on the new model.

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

function userMessage(text: string): SDKUserMessage {
return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };
}

// Hold the second prompt until the setters have run.
let startSecondTurn!: () => void;
const secondTurnReady = new Promise<void>((resolve) => {
startSecondTurn = resolve;
});

async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {
yield userMessage("Reply with exactly: ready");
await secondTurnReady;
yield userMessage("Reply with exactly: done");
}

const session = query({
prompt: turnPrompts(),
options: {
model: "claude-sonnet-5",
},
});

let turnModel = "";
let completedTurns = 0;

for await (const message of session) {
if (message.type === "assistant") {
turnModel = message.message.model;
} else if (message.type === "result") {
completedTurns += 1;
if (completedTurns === 1) {
console.log(`First turn model: ${turnModel}`);
await session.setModel("claude-opus-5");
await session.setPermissionMode("acceptEdits");
startSecondTurn();
} else {
console.log(`Second turn model: ${turnModel}`);
break;
}
}
}

import asyncio

from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient

async def main():
options = ClaudeAgentOptions(model="claude-sonnet-5")

async with ClaudeSDKClient(options=options) as client:
await client.query("Reply with exactly: ready")
first_model = ""
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
first_model = message.model

await client.set_model("claude-opus-5")
await client.set_permission_mode("acceptEdits")

await client.query("Reply with exactly: done")
second_model = ""
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
second_model = message.model

print(f"First turn model: {first_model}")
print(f"Second turn model: {second_model}")

asyncio.run(main())

On the Claude API, the program prints First turn model: claude-sonnet-5, then Second turn model: claude-opus-5 after the switch.

Configure specific features

The table below maps each option to the feature it configures. For options this page doesn't cover, see the TypeScript and Python references. If you know your goal but not which option serves it, start from Choose the right feature.

Next steps

To see configuration composed into working agents:

• Quickstart: build and run a first agent end to end
• Examples: find a complete, runnable project or a guided Claude Cookbook recipe that matches what you want to build
• Multi-tenant isolation: isolate each tenant's settings and memory with settingSources / setting_sources, env, and cwd