Last updated: November 20, 2026
TL;DR
The Claude Code SDK is now called the Claude Agent SDK, and it runs the same agent as claude -p. Pick by what calls it. A shell script, a cron job or a CI step that sends one prompt and reads one result should use claude -p. A Python or TypeScript application that has to react while the agent works, decide on tool calls in code, or keep a conversation going should use the Agent SDK (Anthropic's Agent SDK overview).
Three differences settle most cases:
- ๐งฉ Where your logic lives.
claude -phands your script a result at the end. The SDK hands your code every step as it happens, and lets it answer. - ๐๏ธ What loads by default. Both read your
CLAUDE.md, settings and skills unless you turn that off, and the switch is different in each. - ๐ How it signs in. Plan on an API key or a cloud provider for both. Anthropic doesn't allow products built on the SDK to offer claude.ai login.
What the Claude Code SDK is now
Anthropic renamed the Claude Code SDK to the Claude Agent SDK to reflect "the SDK's broader capabilities for building AI agents beyond coding tasks" (migration guide). The packages changed name with it:
| Language | Old package | New package |
|---|---|---|
| TypeScript | @anthropic-ai/claude-code | @anthropic-ai/claude-agent-sdk |
| Python | claude-code-sdk | claude-agent-sdk |
Two more changes matter if you have old code. The Python options type ClaudeCodeOptions is now ClaudeAgentOptions. And since v0.1.0 the SDK no longer uses Claude Code's system prompt by default: it starts with a minimal one, and you ask for Claude Code's with the claude_code preset.
Both packages bundle a native Claude Code binary, so most installs need no separate Claude Code install. The exceptions are a Python install that falls back to a source distribution, for example on ARM64 Windows, and an npm install that skips optional dependencies (quickstart).
Use claude -p when a script calls it once
Anthropic's own comparison table sends "interactive development or run one-off tasks from a terminal" to the CLI, and embedding the agent "in your own Python or TypeScript application, in a process you operate" to the SDK. An unattended one-off task is the CLI's case with nobody at the terminal:
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
claude -p fits when:
- The caller is a shell script, a cron entry or a CI step. One prompt goes in, one result comes out, and the exit code says whether it worked.
- Your language isn't Python or TypeScript. The SDK overview's own advice for any other language is to run the CLI as a subprocess with
-pand JSON output. - You don't need to step in mid-run. Approvals are set before the run starts, with allowed tools or a permission mode.
Our Claude Code headless guide covers the four settings such a run needs: bare mode, approved tools, JSON output, and caps on turns and spend.
Use the Agent SDK when your code has to take part
The SDK's query() returns an async iterator. Each message is Claude's reasoning, a tool call, a tool result or the final outcome, and your loop sees each one as it arrives. Anthropic's quickstart agent is a few lines of Python:
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
),
):
print(message)
The CLI can stream events too, with its stream-json output, but then your script parses lines of text and can't answer back. The SDK is worth the extra code when you need:
- Decisions in code. Programmatic hooks are callbacks that run in your process and return structured decisions. The docs' example denies any Bash command containing
rm -rfand sends Claude the reason (Use Claude Code features in the SDK). - A conversation that continues. Sessions keep context across exchanges, and you can resume or fork them later.
- Your own tools and helpers. MCP servers connect external tools and data, and subagents take isolated subtasks.
- A Python or TypeScript host. The SDK is a library in those two languages only.
Both load your Claude Code setup unless you stop them
This catches anyone who moves a job from a laptop to a server. When you leave out settingSources (setting_sources in Python), query() reads the same filesystem settings as the CLI: user, project and local settings, CLAUDE.md files, and the skills, agents and commands in .claude/. Pass an empty list to run with only what you configure in code. The CLI's equivalent is bare mode, which the headless guide covers.
An empty list still isn't full isolation. Managed policy settings and the global ~/.claude.json config are read regardless, and auto memory loads unless you set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Anthropic's advice for multi-tenant deployments is to give each tenant its own filesystem, with settingSources: [] and that variable set.
One version note: Python SDK 0.1.59 and earlier treated an empty list the same as leaving the option out, so upgrade before you rely on it.
Both need an API key or a cloud provider
The quickstart sets ANTHROPIC_API_KEY with a key from the Claude Console. The SDK reads it from the environment of the process that runs your agent and doesn't load .env files on its own. It also signs in through Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform or Microsoft Foundry, each switched on with an environment variable such as CLAUDE_CODE_USE_BEDROCK=1.
The SDK pages carry one firm line: "Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK." On the CLI side, bare mode never reads your subscription login, so a bare claude -p run needs the same kind of key.
Pick by the job
| Your job | Use |
|---|---|
| A CI step or cron job that runs one prompt | claude -p with bare mode and JSON output |
| A tool written in Go, Ruby or another language | claude -p as a subprocess |
| A Python or TypeScript service that checks each tool call | Agent SDK with hooks |
| A multi-turn assistant inside your app | Agent SDK with sessions |
| A product other people sign in to | Agent SDK with your own API key |
| Several sessions coordinating through shared task lists | Agent teams, a CLI feature the SDK doesn't configure directly |
Frequently asked questions
What is the Claude Code SDK?
It's the old name of the Claude Agent SDK, Anthropic's Python and TypeScript library that runs Claude Code's agent, with its built-in tools, permissions, sessions and hooks, inside your own application. The packages are now claude-agent-sdk on PyPI and @anthropic-ai/claude-agent-sdk on npm.
Is the Claude Agent SDK the same as Claude Code?
It runs the same agent. The SDK is a library that runs the Claude Code binary, with the same tools, agent loop and context management. What differs is the interface: the CLI is built for a terminal, and the SDK gives your code a stream of messages and options to control the run.
Should I use claude -p or the Agent SDK?
Use claude -p when a shell script, cron job or CI step runs one prompt and reads one result, or when your language isn't Python or TypeScript. Use the Agent SDK when Python or TypeScript code needs to react to each step, decide on tool calls, or keep a conversation going.
Does the Agent SDK load CLAUDE.md?
Yes, by default. When you leave out settingSources, it reads user, project and local settings, CLAUDE.md files and the skills, agents and commands in .claude, like the CLI. Pass an empty list to turn that off. Managed policy settings, ~/.claude.json and auto memory are still read unless you disable them separately.
Can I use my Claude subscription with the Agent SDK?
The SDK docs sign in with an API key from the Claude Console or a cloud provider such as Bedrock. Anthropic doesn't allow third-party developers to offer claude.ai login or rate limits in their products, agents built on the SDK included, unless previously approved.
Do I need to install Claude Code to use the Agent SDK?
Usually not. The Python and TypeScript packages bundle a native Claude Code binary. You need a separate install when pip falls back to a source distribution, for example on ARM64 Windows, or when npm skips optional dependencies.
How do I migrate from claude-code-sdk?
Uninstall the old package, install claude-agent-sdk or @anthropic-ai/claude-agent-sdk, and change your imports. In Python, rename ClaudeCodeOptions to ClaudeAgentOptions. If you relied on Claude Code's system prompt, ask for it with the claude_code preset, since the SDK now starts with a minimal one.
Write the rules once, for both
Whichever you pick, the agent does what its instructions say, every run, with nobody reading along. Anthropic's tip is to use CLAUDE.md "when you want the same context shared between interactive Claude Code sessions and your SDK agents". Writing those rules once, and adding one each time a run goes wrong, is the method in our guide to compound engineering for Claude Code. For the other ways to run Claude Code without you, start with our Claude Code automation guide.
Stop guessing. Score your first workflow.
Score one workflow in about five minutes. Nine questions, a grade, and the specific gap holding it back - no call required.
Related Posts

Claude Code GitHub Actions: set it up, and decide what it can touch
Claude Code GitHub Actions runs Claude Code in your repository's workflows, on an @claude mention or a prompt on any GitHub event. How to install it, how it signs in, and the four layers that decide what a run can touch and spend.

Claude Code PR review: four ways to review every pull request, and which to pick
Managed Code Review, Claude in your own CI, /code-review in your session, or ultrareview: what starts each Claude Code PR review, where it runs, what it costs, and which to pick for your plan and code host.

Claude Code headless mode: run claude -p from scripts, with output you can parse and a cap on spend
Claude Code headless mode runs one prompt with claude -p and exits. How to make runs repeatable with bare mode, approve tools without a prompt, read JSON output, and cap turns and spend.
