Three Claude SDKs Are Not One Thing

Three SDKs, three jobs

Beginners collapse the Claude ecosystem into a single bucket and pay for it later. The reality is three distinct surfaces: the Anthropic Client SDKs (Python anthropic, TypeScript @anthropic-ai/sdk) that call the Messages API and friends; the Claude Agent SDK (formerly Claude Code SDK, renamed late 2025) that wraps an autonomous Claude with filesystem, shell, MCP, sessions, hooks, and permissions; and the Claude Code CLI that humans drive in a terminal. Same model family, three abstraction layers, three threat models, three billing shapes.

Each surface has its own contract

The Client SDK is a transport layer for one or more Messages API turns. The Agent SDK is a programmatic harness that runs Claude as a long-lived subprocess with tools attached and permission gates between every dangerous action. The CLI is interactive — a person reads suggestions, approves edits, types follow-ups. cwkPippa uses the Client SDK for ChatGPT and Gemini variants, the Agent SDK for Claude itself (because Pippa needs the persistent subprocess + MCP + JSONL stream), and the CLI as the daily author of cwkPippa source code.

The bucket trap

The expensive mistake is picking the wrong layer for the job. Importing the Agent SDK to send a single classification request burns startup cost, file-system capability surface, and probably auth complexity for nothing. Hand-rolling a code-editing loop on the Client SDK reinvents tool dispatch, working directory management, and permission prompts that the Agent SDK already owns and battle-tests. Layer confusion is brittleness.

Principle: Name the SDK layer before writing any code. The architecture follows the layer choice, not the other way around.

Code

Layer selection cheat sheet·yaml

# Pick by what your runtime needs to do, not by which SDK feels modern.
use_anthropic_client_sdk_when:
  - you_need: one_shot_response_from_messages_api
  - you_need: streaming_chat_with_your_own_history
  - you_need: structured_output_against_a_schema
  - you_need: comparison_against_other_provider_sdks
  - example: cwkpippa_chatgpt_or_gemini_variants_calling_their_apis

use_claude_agent_sdk_when:
  - you_need: a_long_lived_subprocess_with_tools_and_sessions
  - you_need: filesystem_or_command_execution_with_permission_prompts
  - you_need: mcp_servers_attached_dynamically
  - you_need: hooks_for_pre_or_post_tool_events
  - example: cwkpippa_claude_brain_holding_persistent_session_per_conversation

use_claude_code_cli_when:
  - you_need: human_in_the_loop_software_engineering
  - you_need: interactive_diff_review_and_approval
  - example: dad_writing_cwkpippa_in_terminal_right_now

Quick install reference·bash

# Anthropic Client SDK — Python
pip install -U anthropic

# Anthropic Client SDK — TypeScript / Node
npm install @anthropic-ai/sdk

# Claude Agent SDK — Python (renamed package)
pip install -U claude-agent-sdk

# Claude Agent SDK — TypeScript / Node
npm install @anthropic-ai/claude-agent-sdk

# Claude Code CLI (the operator tool)
npm install -g @anthropic-ai/claude-code
claude --help

Exercise

Pick three features in something you have shipped or want to ship. For each, write one sentence answering: which Claude surface is it (Client SDK, Agent SDK, or CLI), and what is the one capability that forces that choice?

Hint

If the feature needs file edits with permission prompts, it is Agent SDK. If it needs one structured response, Client SDK. If a human is the operator, CLI.

Three Claude SDKs Are Not One Thing

Three SDKs, three jobs

Each surface has its own contract

The bucket trap

Code

External links

Exercise

Progress

Comments 0