Skip to main content

Overview

The Claude Code SDK has been renamed to the Claude Agent SDK and its documentation has been reorganized. This change reflects the SDK’s broader capabilities for building AI agents beyond just coding tasks.

What’s Changed

Migration Steps

For TypeScript/JavaScript Projects

1. Uninstall the old package:
2. Install the new package:
3. Update your imports: Change all imports from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk:
4. Update package.json: If @anthropic-ai/claude-code is still listed in your package.json, replace it with @anthropic-ai/claude-agent-sdk and update the version range as well, for example from "^0.0.42" to "^0.3.0". 5. Review breaking changes Make any code changes needed to complete the migration.

For Python Projects

1. Uninstall the old package:
If the old package isn’t installed, pip prints WARNING: Skipping claude-code-sdk as it is not installed. That’s expected and you can continue to the next step. 2. Install the new package:
If claude-code-sdk is listed in your requirements.txt or pyproject.toml, replace it with claude-agent-sdk. 3. Update your imports: Change all imports from claude_code_sdk to claude_agent_sdk:
4. Review breaking changes Make any code changes needed to complete the migration.

Breaking changes

To improve isolation and explicit configuration, Claude Agent SDK v0.1.0 introduces breaking changes for users migrating from Claude Code SDK.

Python: ClaudeCodeOptions renamed to ClaudeAgentOptions

What changed: The Python SDK type ClaudeCodeOptions has been renamed to ClaudeAgentOptions. Migration:

System prompt no longer default

What changed: The SDK no longer uses Claude Code’s system prompt by default. Migration:

Settings sources default

This default was briefly changed in v0.1.0 to load no filesystem settings and then reverted, so no migration action is needed. Current behavior: Omitting settingSources on query() loads user, project, and local filesystem settings, matching the CLI. This includes ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md files, and custom commands. To run isolated from filesystem settings, pass settingSources: [], or setting_sources=[] in Python. See Control filesystem settings with settingSources for what each source loads. Isolation is especially important for CI/CD pipelines, deployed applications, test environments, and multi-tenant systems where local customizations should not leak in.
Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on setting_sources=[]. See What settingSources does not control for inputs that are read even when settingSources is [].

Next Steps