Back to Blog

Claude Code SDK or claude -p: which one to script against

Alex Kim
9 min read
Claude Code SDK or claude -p: which one to script against

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 -p hands 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:

LanguageOld packageNew package
TypeScript@anthropic-ai/claude-code@anthropic-ai/claude-agent-sdk
Pythonclaude-code-sdkclaude-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 -p and 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 -rf and 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 jobUse
A CI step or cron job that runs one promptclaude -p with bare mode and JSON output
A tool written in Go, Ruby or another languageclaude -p as a subprocess
A Python or TypeScript service that checks each tool callAgent SDK with hooks
A multi-turn assistant inside your appAgent SDK with sessions
A product other people sign in toAgent SDK with your own API key
Several sessions coordinating through shared task listsAgent 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.

#claude-code#Agent SDK#Automation#ai-agents#Headless
Free assessment

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.