Claude Code and the Claude Agent SDK run the same engine: the same tools, agent loop, and context management. The difference is the surface. Claude Code is a CLI for interactive terminal work, and the Agent SDK is a Python and TypeScript library for running that loop inside your own application. So the Claude Agent SDK vs Claude Code choice comes down to whether a person or a program is driving.

I ran both on the same three tasks on an M1 Mac in August 2026: locating a definition, fixing a failing test, and a multistep search-and-write job, three runs each. With the model, tools, and turn limit pinned to match, both passed the inspect and multistep tasks 3/3. On the code fix, the SDK passed 3/3 and the CLI 2/3, and the SDK's median cost for that task was $0.1136 against the CLI's $0.3359. Left on their defaults, the two picked different models.

There is also a third path. The Messages API, through Anthropic's Client SDK, gives you model calls and primitives; it does not provide Claude Code's built-in agent loop. Choose it when you want to own orchestration, retries, state, and tool safety. Choose the Agent SDK when you want Anthropic's loop with programmable hooks.

The Short Answer: Same Engine, Two Surfaces

Claude Code is a user-facing CLI product: you open a terminal, type a prompt, and an agent reads files, runs commands, and reports back. The Claude Agent SDK, as Anthropic's Agent SDK overview describes it, is the same agent loop exposed as a Python library and TypeScript package, so you can drive it programmatically from your own code.

DimensionClaude Code CLIClaude Agent SDK
InterfaceInteractive terminalPython lib / TS package
Best forDaily development, one-off tasksCI/CD, production apps, automation
Installnpm install -g @anthropic-ai/claude-codepip install claude-agent-sdk or npm install @anthropic-ai/claude-agent-sdk
Billing (July 2026)Claude.ai subscriptionSubscription (planned credit split is paused)
System prompt defaultClaude Code preset loadedMinimal (since SDK v0.1.0)
SessionsInteractive, local filesystemProgrammatic, stored as JSONL

A useful way to think about it: Claude Code is what a developer uses; the Claude Agent SDK is what developers build with. Many teams use both, the CLI for daily coding and the SDK for the CI pipelines that run in production.

Claude Code CLI and Agent SDK share one agent loop; the Messages API skips it and leaves the tool loop to you
Same engine, two surfaces, plus the Messages API path (AgenticWire diagram)

Why Anthropic Renamed It

The original name, Claude Code SDK, made the library sound like a tool only for coding tasks. But the same harness powers legal-document agents, research pipelines, and customer-support bots. The rename to Claude Agent SDK took effect on September 29, 2025, and Anthropic's engineering post explained the shift: "The key design principle behind the Claude Agent SDK is to give your agents a computer, allowing them to work like humans do."

For TypeScript projects, the npm package moved from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk. For Python, claude-code-sdk became claude-agent-sdk and the main options type was renamed from ClaudeCodeOptions to ClaudeAgentOptions. No logic changed; only the surface names did.

The Billing Split That Got Paused

Anthropic announced in May 2026 that starting June 15, SDK calls, claude -p, and third-party Agent SDK apps would move off the interactive subscription pool into a separate monthly credit billed at API list prices. That change never activated. Anthropic paused it before the deadline, and its help article now states that "Claude Agent SDK, claude -p, and third-party app usage still draw from your subscription's usage limits."

In practice, a shared Pro or Max subscription still powers both a production agent pipeline and daily developer usage, exactly as before the announcement. Anthropic says it will give advance notice before any revised metering plan ships, so budget against your current subscription ceiling rather than a hypothetical credit.

When to Use Claude Code CLI

The CLI is the right choice when the goal is interactive exploration or a quick one-off task. You get the full agent loop (read files, run commands, edit code, search the web) through a conversational interface with no additional code to write. Flags such as --dangerously-skip-permissions and --allowedTools let you tune permissions without touching a config file.

The spelling of those flags matters. When I ran claude --dangerouslySkipPermissions --version against CLI 2.1.177, it failed immediately with error: unknown option '--dangerouslySkipPermissions', and claude --help confirms the real flag is kebab-case, --dangerously-skip-permissions. --allowedTools is not affected the same way: both claude --allowedTools "Bash" --version and claude --allowed-tools "Bash" --version exit cleanly, since --help documents them as aliases. An earlier version of this page showed both flags in camelCase as if they shared one naming convention; only --allowedTools accepts that form.

Common CLI scenarios:

  • Refactoring a module while you review the output
  • Running a one-time migration script
  • Debugging a production issue in a sandboxed environment
  • Generating documentation from a codebase during a sprint

The CLI loads ~/.claude/settings.json, project .claude/ files, and CLAUDE.md automatically, so your custom skills and preferences carry over without any setup.

When to Use the Claude Agent SDK

The SDK is the right choice any time the agent needs to run without a human in the terminal: a scheduled job, a CI step, an application endpoint, or a long-running background task. The library gives you:

  • Programmatic control: pass a prompt and options, iterate over the returned messages, handle tool-result events
  • Custom tool hooks: PreToolUse and PostToolUse callbacks for audit logging, approval gates, or cost throttling
  • Subagent spawning: define specialized agents in AgentDefinition objects and let the main loop delegate to them
  • MCP server attachment: connect third-party MCP servers by passing a mcpServers config dict
  • Transport flexibility: supports Bedrock, Vertex AI, Azure AI Foundry, and the Anthropic API via environment variables. Set CLAUDE_CODE_USE_BEDROCK=1 with AWS credentials for Bedrock, CLAUDE_CODE_USE_VERTEX=1 with Google Cloud credentials for Vertex AI, or CLAUDE_CODE_USE_FOUNDRY=1 for Azure AI Foundry

The SDK is also the right path when you want to suppress the Claude Code system prompt. According to Anthropic's migration guide, starting with SDK v0.1.0 the library defaults to a minimal system prompt instead of loading Claude Code's CLI-focused instructions, which gives you a clean slate for building non-coding agents.

Correction (August 3, 2026): this section originally cited @anthropic-ai/claude-agent-sdk@0.2.0 as the version tested. npm's registry shows 0.2.0 shipped on January 7, 2026, and the package had already reached 0.3.193 by this article's own publish date, so the cited version was roughly six months and dozens of releases stale. A fresh install on August 3 resolved 0.3.220.

When I re-ran that check on @anthropic-ai/claude-agent-sdk@0.3.239, the query() function and its options.allowedTools shape were unchanged: for await (const message of query({ prompt: "List files here", options: { allowedTools: ["Bash", "Glob"] } })) still resolves. The package now has 31 top-level exports, including session-management helpers (forkSession, listSessions, tagSession) that did not exist in the 0.2.0 line.

The same three tasks on both surfaces

In the default configuration, with nothing tuned, the CLI and the SDK each passed inspect, fix, and multistep 3/3. The CLI's median wall time was lower on all three tasks, but the two defaults are not the same setup: the CLI selected claude-opus-5[1m] and the SDK selected claude-opus-5, so this measures default behavior, not model quality.

Task (default config)CLI median wall timeSDK median wall time
Inspect12,979 ms14,251 ms
Fix24,211 ms25,635 ms
Multistep17,896 ms22,648 ms

The parity configuration is the fairer comparison. Both surfaces used claude-sonnet-5, the same six allowed tools, the same max-turn setting, the same fresh fixture, and bypassed permissions. Both passed inspect and multistep 3/3; code-fix passed CLI 2/3 and SDK 3/3. For code-fix, the CLI's median cost and wall time were $0.3359 and 37,404 ms, while the SDK's were $0.1136 and 28,793 ms, with a median of 8 tool calls. The CLI's JSON output did not expose tool-call counts, so I make no CLI-versus-SDK tool-call comparison. These are observed run costs, not provider list prices or arithmetic estimates.

Migrating: ClaudeCodeOptions to ClaudeAgentOptions

If you are on claude-code-sdk (Python) or @anthropic-ai/claude-code (TypeScript), the migration is mechanical:

TypeScript:

npm uninstall @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk

Update all imports from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk. No other code changes are required unless you relied on the default system prompt behavior.

Python:

pip uninstall claude-code-sdk
pip install claude-agent-sdk

Rename ClaudeCodeOptions to ClaudeAgentOptions everywhere it appears. The migration guide says the two types have identical fields; only the name changed.

The one breaking change to watch: SDK v0.1.0 no longer loads Claude Code's system prompt by default. If your agent depended on that preset, pass it explicitly:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="...",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}
    ),
):
    ...

One related gotcha from the same guide: Python SDK 0.1.59 and earlier treated setting_sources=[] the same as omitting it, so upgrade before relying on that flag for CI isolation.

The Claude Code SDK question behind this comparison

The old "Claude Code SDK" name sticks because both surfaces share the Claude Code agent loop. Choose the CLI when a person is working interactively in a repository. Choose the Agent SDK when your application needs to start sessions, supply tools and permissions, handle messages, and persist outcomes through code. Before moving a CLI workflow into a service, test permission prompts, working-directory access, failure recovery, and billing under the intended account. The same engine does not make those operational boundaries interchangeable.

How I tested this

The task comparison ran on August 21, 2026 on an Apple M1 (arm64) with macOS 26.3 and Node v22.18.0, using Claude Code CLI 2.1.238 and a fresh npm install of @anthropic-ai/claude-agent-sdk 0.3.239. The script builds a small local git repository with the same content and commit on every run, and each run gets a fresh copy so one run's edits cannot affect the next. Every task has an objective pass or fail: inspect must name the right file, fix must make the test runner exit 0 without modifying the tests, and multistep must write a TODOS.md with the right number of entries.

Each task ran three times per surface in two configurations. Default is claude -p "<task>" against the SDK's query({prompt}) with nothing tuned. Parity pins the same model, allowed tools, turn limit, and working directory on both, with permissions bypassed. The run measures what each surface costs you, not model quality, and it does not cover other models, longer tasks, or CLI tool-call counts. The flag check in the CLI section was a separate check against CLI 2.1.177 and is not part of this record. The raw test record has every median and range, and the harness script is in the same folder.

FAQ

Is the Claude Code SDK deprecated?

The package @anthropic-ai/claude-code and claude-code-sdk (Python) are deprecated in favor of the renamed equivalents. They may still install and run, but Anthropic's active development and documentation are now on @anthropic-ai/claude-agent-sdk and claude-agent-sdk. Migrate when you next update dependencies.

Related coverage

References