# anthropics/claude-code-sdk-python architecture

> Architecture diagram of the GitHub repository anthropics/claude-code-sdk-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anthropics/claude-code-sdk-python
- Repository: https://github.com/anthropics/claude-code-sdk-python

## Overview

This is a Python SDK for running Claude Agent through the bundled or configured Claude Code CLI. The main workflow accepts a prompt through either the one-shot query API or an interactive client, configures the session, exchanges streaming messages over a transport, and yields parsed responses. Additional capabilities include in-process MCP tools, hooks and permission callbacks, plus session listing, mutation, import, resume, and pluggable storage. Edges reflect README statements or relationships named in the SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`src/claude_agent_sdk/_internal/client.py`](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/client.py) (Query orchestration), [`src/claude_agent_sdk/_internal/query.py`](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/query.py) (Query protocol), [`src/claude_agent_sdk/_internal/session_store.py`](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_store.py) (Session store), [`src/claude_agent_sdk/client.py`](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/client.py) (Interactive client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["SDK interfaces"]
  node_public_api["Public API<br/>[__init__.py]"]
  node_query_api["One-shot query<br/>[query.py]"]
  node_interactive["Interactive client<br/>[client.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_query_engine["Query protocol<br/>[query.py]"]
  node_internal_client["Query orchestration<br/>[client.py]"]
  node_transport["Transport interface<br/>[__init__.py]"]
  node_cli_transport["CLI subprocess<br/>[subprocess_cli.py]"]
  node_parser["Message parser<br/>[message_parser.py]"]
  node_mcp_bridge["SDK MCP bridge<br/>[sdk_mcp_bridge.py]"]
end

subgraph group_sessions["Session lifecycle"]
  node_session_api["Session operations<br/>[sessions.py]"]
  node_session_import["Session import<br/>[session_import.py]"]
  node_session_mutations["Session mutations"]
  node_session_resume["Session resume<br/>[session_resume.py]"]
  node_session_store[("Session store<br/>[session_store.py]")]
  node_store_validation["Store validation"]
  node_summary["Session summaries<br/>[session_summary.py]"]
  node_transcript_batcher["Transcript batcher"]
end

subgraph group_contracts["Types and errors"]
  node_types["SDK types<br/>[types.py]"]
  node_errors["Error types<br/>[_errors.py]"]
end

node_user(("SDK application"))
node_cli["Claude Code CLI"]

node_user -->|"submits prompt"| node_query_api
node_user -->|"starts conversation"| node_interactive
node_public_api -->|"exports"| node_query_api
node_query_api -->|"delegates to"| node_internal_client
node_interactive -->|"initializes"| node_query_engine
node_interactive -->|"uses for resume"| node_session_resume
node_internal_client -->|"orchestrates"| node_query_engine
node_internal_client -->|"validates options"| node_store_validation
node_internal_client -->|"selects transport"| node_transport
node_internal_client -->|"prepares resume"| node_session_resume
node_query_engine -->|"uses protocol"| node_transport
node_query_engine -->|"dispatches tools"| node_mcp_bridge
node_transport -->|"implemented by"| node_cli_transport
node_cli_transport -->|"exchanges stream"| node_cli
node_interactive -->|"uses parser"| node_parser
node_session_api -->|"loads sessions"| node_session_store
node_session_api -->|"uses summaries"| node_summary
node_session_import -->|"uses session helpers"| node_session_api
node_session_import -->|"uses batcher"| node_transcript_batcher
node_session_mutations -->|"uses session helpers"| node_session_api
node_session_mutations -->|"checks store"| node_store_validation
node_session_resume -->|"loads transcript"| node_session_store
node_session_resume -->|"uses batcher"| node_transcript_batcher
node_session_store -->|"derives metadata"| node_summary
node_transcript_batcher -->|"writes batches"| node_session_store
node_public_api -->|"exports types"| node_types
node_public_api -->|"exports errors"| node_errors
node_session_store -->|"implements contract"| node_types
node_query_engine -->|"raises errors"| node_errors

click node_public_api "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/__init__.py"
click node_query_api "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/query.py"
click node_interactive "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/client.py"
click node_query_engine "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/query.py"
click node_internal_client "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/client.py"
click node_transport "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/transport/__init__.py"
click node_cli_transport "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/transport/subprocess_cli.py"
click node_parser "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/message_parser.py"
click node_mcp_bridge "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/sdk_mcp_bridge.py"
click node_session_api "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/sessions.py"
click node_session_import "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_import.py"
click node_session_mutations "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_mutations.py"
click node_session_resume "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_resume.py"
click node_session_store "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_store.py"
click node_store_validation "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_store_validation.py"
click node_summary "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_summary.py"
click node_transcript_batcher "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/transcript_mirror_batcher.py"
click node_types "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/types.py"
click node_errors "https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_errors.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_query_api,node_interactive toneBlue
class node_query_engine,node_internal_client,node_transport,node_cli_transport,node_parser,node_mcp_bridge toneAmber
class node_session_api,node_session_import,node_session_mutations,node_session_resume,node_session_store,node_store_validation,node_summary,node_transcript_batcher toneMint
class node_types,node_errors toneRose
class node_user,node_cli toneIndigo
```

## Components

### SDK interfaces

- [Public API](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/__init__.py): `src/claude_agent_sdk/__init__.py`
- [One-shot query](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/query.py): `src/claude_agent_sdk/query.py`
- [Interactive client](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/client.py): `src/claude_agent_sdk/client.py`

### Agent runtime

- [Query protocol](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/query.py): `src/claude_agent_sdk/_internal/query.py`
- [Query orchestration](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/client.py): `src/claude_agent_sdk/_internal/client.py`
- [Transport interface](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/transport/__init__.py): `src/claude_agent_sdk/_internal/transport/__init__.py`
- [CLI subprocess](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/transport/subprocess_cli.py): `src/claude_agent_sdk/_internal/transport/subprocess_cli.py`
- [Message parser](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/message_parser.py): `src/claude_agent_sdk/_internal/message_parser.py`
- [SDK MCP bridge](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/sdk_mcp_bridge.py): `src/claude_agent_sdk/_internal/sdk_mcp_bridge.py`

### Session lifecycle

- [Session operations](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/sessions.py): `src/claude_agent_sdk/_internal/sessions.py`
- [Session import](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_import.py): `src/claude_agent_sdk/_internal/session_import.py`
- [Session mutations](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_mutations.py): `src/claude_agent_sdk/_internal/session_mutations.py`
- [Session resume](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_resume.py): `src/claude_agent_sdk/_internal/session_resume.py`
- [Session store](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_store.py): `src/claude_agent_sdk/_internal/session_store.py`
- [Store validation](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_store_validation.py): `src/claude_agent_sdk/_internal/session_store_validation.py`
- [Session summaries](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/session_summary.py): `src/claude_agent_sdk/_internal/session_summary.py`
- [Transcript batcher](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_internal/transcript_mirror_batcher.py): `src/claude_agent_sdk/_internal/transcript_mirror_batcher.py`

### Types and errors

- [SDK types](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/types.py): `src/claude_agent_sdk/types.py`
- [Error types](https://github.com/anthropics/claude-code-sdk-python/blob/main/src/claude_agent_sdk/_errors.py): `src/claude_agent_sdk/_errors.py`

### Other components

- **SDK application**
- **Claude Code CLI**

## Connections

- SDK application → One-shot query: submits prompt (evidence: `README.md`)
- SDK application → Interactive client: starts conversation (evidence: `README.md`)
- Public API → One-shot query: exports (evidence: `src/claude_agent_sdk/__init__.py`)
- One-shot query → Query orchestration: delegates to (evidence: `src/claude_agent_sdk/query.py`)
- Interactive client → Query protocol: initializes (evidence: `src/claude_agent_sdk/client.py`)
- Interactive client → Session resume: uses for resume (evidence: `src/claude_agent_sdk/client.py`)
- Query orchestration → Query protocol: orchestrates (evidence: `src/claude_agent_sdk/_internal/client.py`)
- Query orchestration → Store validation: validates options (evidence: `src/claude_agent_sdk/_internal/client.py`)
- Query orchestration → Transport interface: selects transport (evidence: `src/claude_agent_sdk/_internal/client.py`)
- Query orchestration → Session resume: prepares resume (evidence: `src/claude_agent_sdk/_internal/client.py`)
- Query protocol → Transport interface: uses protocol (evidence: `src/claude_agent_sdk/_internal/query.py`)
- Query protocol → SDK MCP bridge: dispatches tools (evidence: `src/claude_agent_sdk/_internal/query.py`)
- Transport interface → CLI subprocess: implemented by (evidence: `src/claude_agent_sdk/_internal/transport/subprocess_cli.py`)
- CLI subprocess → Claude Code CLI: exchanges stream (evidence: `src/claude_agent_sdk/_internal/transport/subprocess_cli.py`)
- Interactive client → Message parser: uses parser (evidence: `src/claude_agent_sdk/client.py`)
- Session operations → Session store: loads sessions (evidence: `src/claude_agent_sdk/_internal/sessions.py`)
- Session operations → Session summaries: uses summaries (evidence: `src/claude_agent_sdk/_internal/sessions.py`)
- Session import → Session operations: uses session helpers (evidence: `src/claude_agent_sdk/_internal/session_import.py`)
- Session import → Transcript batcher: uses batcher (evidence: `src/claude_agent_sdk/_internal/session_import.py`)
- Session mutations → Session operations: uses session helpers (evidence: `src/claude_agent_sdk/_internal/session_mutations.py`)
- Session mutations → Store validation: checks store (evidence: `src/claude_agent_sdk/_internal/session_mutations.py`)
- Session resume → Session store: loads transcript (evidence: `src/claude_agent_sdk/_internal/session_resume.py`)
- Session resume → Transcript batcher: uses batcher (evidence: `src/claude_agent_sdk/_internal/session_resume.py`)
- Session store → Session summaries: derives metadata (evidence: `src/claude_agent_sdk/_internal/session_store.py`)
- Transcript batcher → Session store: writes batches (evidence: `src/claude_agent_sdk/_internal/transcript_mirror_batcher.py`)
- Public API → SDK types: exports types (evidence: `src/claude_agent_sdk/__init__.py`)
- Public API → Error types: exports errors (evidence: `src/claude_agent_sdk/__init__.py`)
- Session store → SDK types: implements contract (evidence: `src/claude_agent_sdk/types.py`)
- Query protocol → Error types: raises errors (evidence: `src/claude_agent_sdk/_internal/query.py`)