Meta

• License: MIT License (MIT)
• Author: Anthropic
• Tags ai , anthropic , claude , sdk
• Requires: Python >=3.10
• Provides-Extra: dev

Classifiers

• Development Status
  • 3 - Alpha
• Intended Audience
  • Developers
• License
  • OSI Approved :: MIT License
• Programming Language
  • Python :: 3
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
• Typing
  • Typed

Claude Code SDK for Python

⚠️ DEPRECATED: This package has been deprecated and is no longer maintained. Please migrate to the Claude Agent SDK (claude-agent-sdk).

Python SDK for Claude Code. See the Claude Code SDK documentation for more information.

Installation

pipinstallclaude-code-sdk

Prerequisites:

• Python 3.10+
• Node.js
• Claude Code: npm install -g @anthropic-ai/claude-code

Quick Start

importanyio
fromclaude_code_sdkimport query

async defmain():
 async for message in query(prompt="What is 2 + 2?"):
 print(message)

anyio.run(main)

Basic Usage: query()

query() is an async function for querying Claude Code. It returns an AsyncIterator of response messages. See src/claude_code_sdk/query.py.

fromclaude_code_sdkimport query, ClaudeCodeOptions, AssistantMessage, TextBlock

# Simple query
async for message in query(prompt="Hello Claude"):
 if isinstance(message, AssistantMessage):
 for block in message.content:
 if isinstance(block, TextBlock):
 print(block.text)

# With options
options = ClaudeCodeOptions(
 system_prompt="You are a helpful assistant",
 max_turns=1
)

async for message in query(prompt="Tell me a joke", options=options):
 print(message)

Using Tools

options = ClaudeCodeOptions(
 allowed_tools=["Read", "Write", "Bash"],
 permission_mode='acceptEdits' # auto-accept file edits
)

async for message in query(
 prompt="Create a hello.py file", 
 options=options
):
 # Process tool use and results
 pass

Working Directory

frompathlibimport Path

options = ClaudeCodeOptions(
 cwd="/path/to/project" # or Path("/path/to/project")
)

ClaudeSDKClient

ClaudeSDKClient supports bidirectional, interactive conversations with Claude Code. See src/claude_code_sdk/client.py.

Unlike query(), ClaudeSDKClient additionally enables custom tools and hooks, both of which can be defined as Python functions.

Custom Tools (as In-Process SDK MCP Servers)

A custom tool is a Python function that you can offer to Claude, for Claude to invoke as needed.

Custom tools are implemented in-process MCP servers that run directly within your Python application, eliminating the need for separate processes that regular MCP servers require.

For an end-to-end example, see MCP Calculator.

Creating a Simple Tool

fromclaude_code_sdkimport tool, create_sdk_mcp_server, ClaudeCodeOptions, ClaudeSDKClient

# Define a tool using the @tool decorator
@tool("greet", "Greet a user", {"name": str})
async defgreet_user(args):
 return {
 "content": [
 {"type": "text", "text": f"Hello, {args['name']}!"}
 ]
 }

# Create an SDK MCP server
server = create_sdk_mcp_server(
 name="my-tools",
 version="1.0.0",
 tools=[greet_user]
)

# Use it with Claude
options = ClaudeCodeOptions(
 mcp_servers={"tools": server},
 allowed_tools=["mcp__tools__greet"]
)

async with ClaudeSDKClient(options=options) as client:
 await client.query("Greet Alice")

 # Extract and print response
 async for msg in client.receive_response():
 print(msg)

Benefits Over External MCP Servers

• No subprocess management - Runs in the same process as your application
• Better performance - No IPC overhead for tool calls
• Simpler deployment - Single Python process instead of multiple
• Easier debugging - All code runs in the same process
• Type safety - Direct Python function calls with type hints

Migration from External Servers

# BEFORE: External MCP server (separate process)
options = ClaudeCodeOptions(
 mcp_servers={
 "calculator": {
 "type": "stdio",
 "command": "python",
 "args": ["-m", "calculator_server"]
 }
 }
)

# AFTER: SDK MCP server (in-process)
frommy_toolsimport add, subtract # Your tool functions

calculator = create_sdk_mcp_server(
 name="calculator",
 tools=[add, subtract]
)

options = ClaudeCodeOptions(
 mcp_servers={"calculator": calculator}
)

Mixed Server Support

You can use both SDK and external MCP servers together:

options = ClaudeCodeOptions(
 mcp_servers={
 "internal": sdk_server, # In-process SDK server
 "external": { # External subprocess server
 "type": "stdio",
 "command": "external-server"
 }
 }
)

Hooks

A hook is a Python function that the Claude Code application (not Claude) invokes at specific points of the Claude agent loop. Hooks can provide deterministic processing and automated feedback for Claude. Read more in Claude Code Hooks Reference.

For more examples, see examples/hooks.py.

Example

fromclaude_code_sdkimport ClaudeCodeOptions, ClaudeSDKClient, HookMatcher

async defcheck_bash_command(input_data, tool_use_id, context):
 tool_name = input_data["tool_name"]
 tool_input = input_data["tool_input"]
 if tool_name != "Bash":
 return {}
 command = tool_input.get("command", "")
 block_patterns = ["foo.sh"]
 for pattern in block_patterns:
 if pattern in command:
 return {
 "hookSpecificOutput": {
 "hookEventName": "PreToolUse",
 "permissionDecision": "deny",
 "permissionDecisionReason": f"Command contains invalid pattern: {pattern}",
 }
 }
 return {}

options = ClaudeCodeOptions(
 allowed_tools=["Bash"],
 hooks={
 "PreToolUse": [
 HookMatcher(matcher="Bash", hooks=[check_bash_command]),
 ],
 }
)

async with ClaudeSDKClient(options=options) as client:
 # Test 1: Command with forbidden pattern (will be blocked)
 await client.query("Run the bash command: ./foo.sh --help")
 async for msg in client.receive_response():
 print(msg)

 print("\n" + "=" * 50 + "\n")

 # Test 2: Safe command that should work
 await client.query("Run the bash command: echo 'Hello from hooks example!'")
 async for msg in client.receive_response():
 print(msg)

Types

See src/claude_code_sdk/types.py for complete type definitions:

• ClaudeCodeOptions - Configuration options
• AssistantMessage, UserMessage, SystemMessage, ResultMessage - Message types
• TextBlock, ToolUseBlock, ToolResultBlock - Content blocks

Error Handling

fromclaude_code_sdkimport (
 ClaudeSDKError, # Base error
 CLINotFoundError, # Claude Code not installed
 CLIConnectionError, # Connection issues
 ProcessError, # Process failed
 CLIJSONDecodeError, # JSON parsing issues
)

try:
 async for message in query(prompt="Hello"):
 pass
except CLINotFoundError:
 print("Please install Claude Code")
except ProcessError as e:
 print(f"Process failed with exit code: {e.exit_code}")
except CLIJSONDecodeError as e:
 print(f"Failed to parse response: {e}")

See src/claude_code_sdk/_errors.py for all error types.

Available Tools

See the Claude Code documentation for a complete list of available tools.

Examples

See examples/quick_start.py for a complete working example.

See examples/streaming_mode.py for comprehensive examples involving ClaudeSDKClient. You can even run interactive examples in IPython from examples/streaming_mode_ipython.py.

License

MIT

Verified details

These details have been verified by PyPI

Owner

• Anthropic, PBC.

Unverified details

These details have not been verified by PyPI

Project links

• Documentation
• Homepage
• Issues

• Download URL: claude_code_sdk-0.0.25.tar.gz
• Upload date: Sep 29, 2025
• Size: 41.3 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.2.0 CPython/3.12.11

Hashes for claude_code_sdk-0.0.25.tar.gz

Algorithm	Hash digest
SHA256	0d9e1eba432d4fe8a2f75f06ec9bb4c310f39b1d55246e7e4b2c69bfdd69eab3
MD5	04950de15b386506562fbd8297f1c40f
BLAKE2b-256	ec0d0f4a71415826578a5ace16817c52df84d76ffbda5cdad02f520a2b963bde

See more details on using hashes here.

• Download URL: claude_code_sdk-0.0.25-py3-none-any.whl
• Upload date: Sep 29, 2025
• Size: 31.0 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.2.0 CPython/3.12.11

Hashes for claude_code_sdk-0.0.25-py3-none-any.whl

Algorithm	Hash digest
SHA256	3d6a4ef958182f311d6050776d2675d9b39650a2db221c582a0a5156472dcee3
MD5	58a04c3147b8be16f455c46e2d52b207
BLAKE2b-256	f541c934058080f3233bbc95bc9abac5e0191bf336ad5f69a33b5f54a4737e88

See more details on using hashes here.