0
# Claude Code SDK
1

2
Python SDK for Claude Code providing comprehensive integration with Claude AI capabilities through both simple query functions and advanced bidirectional interactive conversations. The SDK supports custom tools implemented as in-process MCP servers that run directly within Python applications, eliminating the need for separate processes while providing better performance and easier debugging.
3

4
## Package Information
5

6
- **Package Name**: claude-code-sdk
7
- **Language**: Python
8
- **Python Version**: 3.10+
9
- **Installation**: `pip install claude-code-sdk`
10

11
## Core Imports
12

13
```python
14
from claude_code_sdk import query
15
```
16

17
For interactive conversations with custom tools and hooks:
18

19
```python
20
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
21
```
22

23
For creating custom tools:
24

25
```python
26
from claude_code_sdk import tool, create_sdk_mcp_server, SdkMcpTool
27
```
28

29
For type safety:
30

31
```python
32
from claude_code_sdk import (
33
    AssistantMessage, UserMessage, SystemMessage, ResultMessage,
34
    TextBlock, ToolUseBlock, ToolResultBlock,
35
    PermissionMode, McpServerConfig
36
)
37
```
38

39
## Basic Usage
40

41
```python
42
import anyio
43
from claude_code_sdk import query
44

45
async def main():
46
    # Simple one-shot query
47
    async for message in query(prompt="What is 2 + 2?"):
48
        print(message)
49

50
anyio.run(main)
51
```
52

53
With options and tool usage:
54

55
```python
56
from claude_code_sdk import query, ClaudeCodeOptions, AssistantMessage, TextBlock
57

58
async def main():
59
    options = ClaudeCodeOptions(
60
        allowed_tools=["Read", "Write", "Bash"],
61
        permission_mode='acceptEdits',  # auto-accept file edits
62
        cwd="/path/to/project"
63
    )
64

65
    async for message in query(
66
        prompt="Create a hello.py file",
67
        options=options
68
    ):
69
        if isinstance(message, AssistantMessage):
70
            for block in message.content:
71
                if isinstance(block, TextBlock):
72
                    print(block.text)
73

74
anyio.run(main)
75
```
76

77
## Architecture
78

79
The Claude Code SDK is built around two main interaction patterns:
80

81
- **Unidirectional Communication**: The `query()` function for simple, stateless interactions where all inputs are known upfront
82
- **Bidirectional Communication**: The `ClaudeSDKClient` class for interactive, stateful conversations with full control over message flow
83

84
**Key Components:**
85
- **Transport Layer**: Abstracts communication with Claude Code CLI through subprocess, network, or custom implementations
86
- **Message System**: Structured message types (User, Assistant, System, Result, Stream) with rich content blocks
87
- **Permission System**: Fine-grained control over tool execution with callbacks and permission modes
88
- **MCP Integration**: Support for both external MCP servers and in-process SDK MCP servers
89
- **Hook System**: Python functions that execute at specific points in the Claude agent loop for deterministic processing
90

91
## Capabilities
92

93
### Simple Queries
94

95
Unidirectional query interface for one-shot interactions with Claude Code. Ideal for simple questions, batch processing, code generation, and automated scripts where all inputs are known upfront.
96

97
```python { .api }
98
async def query(
99
    *,
100
    prompt: str | AsyncIterable[dict[str, Any]],
101
    options: ClaudeCodeOptions | None = None,
102
    transport: Transport | None = None,
103
) -> AsyncIterator[Message]:
104
```
105

106
[Simple Queries](./simple-queries.md)
107

108
### Interactive Client
109

110
Bidirectional client for interactive, stateful conversations with Claude Code. Provides full control over conversation flow with support for streaming, interrupts, dynamic message sending, custom tools, and hooks.
111

112
```python { .api }
113
class ClaudeSDKClient:
114
    def __init__(self, options: ClaudeCodeOptions | None = None): ...
115
    async def connect(self, prompt: str | AsyncIterable[dict[str, Any]] | None = None) -> None: ...
116
    async def receive_messages(self) -> AsyncIterator[Message]: ...
117
    async def query(self, prompt: str | AsyncIterable[dict[str, Any]], session_id: str = "default") -> None: ...
118
    async def interrupt(self) -> None: ...
119
    async def receive_response(self) -> AsyncIterator[Message]: ...
120
    async def disconnect(self) -> None: ...
121
    async def __aenter__(self) -> "ClaudeSDKClient": ...
122
    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool: ...
123
```
124

125
[Interactive Client](./interactive-client.md)
126

127
### Custom Tools
128

129
In-process MCP tools that run directly within your Python application. Create custom tools that Claude can invoke, with better performance than external MCP servers, simpler deployment, and direct access to your application's state.
130

131
```python { .api }
132
def tool(
133
    name: str,
134
    description: str,
135
    input_schema: type | dict[str, Any]
136
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]: ...
137

138
def create_sdk_mcp_server(
139
    name: str,
140
    version: str = "1.0.0",
141
    tools: list[SdkMcpTool[Any]] | None = None
142
) -> McpSdkServerConfig: ...
143
```
144

145
[Custom Tools](./custom-tools.md)
146

147
### Configuration and Options
148

149
Comprehensive configuration system for controlling Claude Code behavior including tool permissions, working directory, system prompts, MCP server configurations, and advanced features.
150

151
```python { .api }
152
@dataclass
153
class ClaudeCodeOptions:
154
    allowed_tools: list[str] = field(default_factory=list)
155
    system_prompt: str | None = None
156
    permission_mode: PermissionMode | None = None
157
    cwd: str | Path | None = None
158
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
159
    can_use_tool: CanUseTool | None = None
160
    hooks: dict[HookEvent, list[HookMatcher]] | None = None
161
    # ... additional fields
162
```
163

164
[Configuration and Options](./configuration-options.md)
165

166
### Hook System
167

168
Python functions that the Claude Code application invokes at specific points of the Claude agent loop. Hooks provide deterministic processing and automated feedback for Claude, enabling custom validation, permission checks, and automated responses.
169

170
```python { .api }
171
@dataclass
172
class HookMatcher:
173
    matcher: str | None = None
174
    hooks: list[HookCallback] = field(default_factory=list)
175

176
HookCallback = Callable[
177
    [dict[str, Any], str | None, HookContext],
178
    Awaitable[HookJSONOutput]
179
]
180
```
181

182
[Hook System](./hook-system.md)
183

184
### Message Types and Content
185

186
Rich message system with structured content blocks supporting text, tool usage, tool results, thinking blocks, and streaming events. Includes complete type definitions for all message and content types.
187

188
```python { .api }
189
Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent
190
ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
191

192
@dataclass
193
class AssistantMessage:
194
    content: list[ContentBlock]
195
    model: str
196
    parent_tool_use_id: str | None = None
197
```
198

199
[Message Types and Content](./message-types.md)
200

201
### Transport System
202

203
Abstract transport interface for custom Claude Code communication implementations. Enables custom transport implementations for remote Claude Code connections or alternative communication methods.
204

205
```python { .api }
206
class Transport(ABC):
207
    @abstractmethod
208
    async def connect(self) -> None: ...
209
    @abstractmethod
210
    async def write(self, data: str) -> None: ...
211
    @abstractmethod
212
    def read_messages(self) -> AsyncIterator[dict[str, Any]]: ...
213
    # ... additional abstract methods
214
```
215

216
[Transport System](./transport-system.md)
217

218
### Error Handling
219

220
Comprehensive error handling with specific exception types for different failure modes. Includes connection errors, process failures, JSON parsing issues, and message parsing errors.
221

222
```python { .api }
223
class ClaudeSDKError(Exception): ...
224
class CLIConnectionError(ClaudeSDKError): ...
225
class CLINotFoundError(CLIConnectionError): ...
226
class ProcessError(ClaudeSDKError): ...
227
class CLIJSONDecodeError(ClaudeSDKError): ...
228
```
229

230
[Error Handling](./error-handling.md)
231

232
## Constants
233

234
```python { .api }
235
__version__: str  # "0.0.23"
236
```