Claude Code vs Claude Agent SDK: Which Is for What?

Claude Code is the finished product you use for interactive coding; the Claude Agent SDK is the extracted engine you embed in custom applications. They share the same underlying harness, and the confusion between them stems from a naming history that obscures a simple architectural relationship.

Why Developers Confuse Claude Code and the Claude Agent SDK

The Claude Agent SDK was originally named the "Claude Code SDK." Anthropic announced the rename on September 29, 2025. That rename created a naming split that implies two separate products. The Agent SDK is the same harness that powers Claude Code, exposed as a library.

Anthropic's own engineering blog states it directly: "The agent harness that powers Claude Code (the Claude Code SDK) can power many other types of agents, too. To reflect this broader vision, we're renaming the Claude Code SDK to the Claude Agent SDK."

Anthropic's own Xcode announcement, published February 3, 2026, states the relationship directly: Xcode 26.3 "introduces a native integration with the Claude Agent SDK, the same underlying harness that powers Claude Code."

Four misconceptions recur in developer discussions.

• "The SDK is a separate product that Claude Code calls into." The architectural distinction runs the other way. The SDK is the same harness that powers Claude Code, packaged as a library.
• "Claude Code is for coding; the SDK is for general agents." Anthropic presents Claude Code as useful beyond traditional coding, including for internal research and non-coding workflows.
• "The SDK is just a CLI passthrough." The SDK adds structured programmatic access, subagent orchestration with context isolation, and session-spanning context management that simple claude -p usage does not expose as a library interface.
• "SDK credentials work as standard API keys." The SDK and Claude Code support different authentication flows. Teams should follow the documented Agent SDK quickstart and migration guide rather than assuming credentials are interchangeable.

A fourth option complicates the picture. Anthropic also ships Managed Agents, a hosted REST API where Anthropic runs both the agent and its sandbox, a separate product from the Agent SDK and the better fit for long-running work nobody wants to host. The Client SDK is a fifth, for teams calling the API and writing the tool loop themselves.

The "Code vs. SDK" decision is an interface choice, not a capability choice. Both tools expose the same agent loop: gather context, take action, verify results, repeat.

Claude Code: What It Is and When to Use It

Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. It runs in the terminal, VS Code, the desktop app, and the browser, with a low-friction setup after installation and authentication.

One capability separates Claude Code from autocomplete tools. Given a high-level instruction such as "refactor the auth module to use the new token service, run tests, fix failures", it executes a multi-step plan across files, commands, and verification loops. A developer can interrupt at any point with Esc, and a double Esc performs checkpoint-based rollback.

What Claude Code ships with:

• File operations (read, edit, create, rename)
• Code search and codebase exploration
• Execution (shell commands, test runners, git)
• Web access (documentation lookup, error message search)
• Six permission modes for managing how it uses tools and edits code: Manual, acceptEdits, plan, auto, dontAsk, and bypassPermissions
• CLAUDE.md configuration files in the project root for persistent project instructions
• CI pipeline monitoring on GitHub and GitLab, with a dedicated GitHub Actions workflow for PR and issue automation

Ideal use cases for Claude Code:

• Solo refactoring with inline diffs, test execution, and git commits
• Security reviews scoped to changed files (git diff main --name-only | claude -p "review these changed files for security issues")
• CI/CD automation via the -p flag in GitHub Actions workflows
• Codebase onboarding, where Claude reads actual project files, not training data
• Test generation with automatic fix loops

Claude Code is best suited to tasks where a human developer is actively steering the loop in a terminal, IDE, desktop app, or browser-based session.

Claude Agent SDK: What It Is and When to Use It

The Claude Agent SDK is a Python and TypeScript library that exposes the same agent loop powering Claude Code as a programmable interface, with separate walkthroughs for a first Python agent and for TypeScript type safety. The primary entry point is the query() async generator, which accepts a prompt and options and streams back typed messages. The package names and migration path are documented in the migration guide.

The SDK exposes the Claude Code harness as a programmatic interface, not a standalone UI, and the gap between what it ships and what a developer still assembles is the part teams underestimate.

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
 
async def main():
    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",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

What the SDK adds beyond CLI usage:

• Subagent orchestration with context isolation and parallel execution
• Programmatic lifecycle hooks that run custom code at set points in the agent lifecycle, including PreToolUse, PostToolUse and Stop
• Session management with persistence across turns via sessionId
• Custom system prompts and settings source control per invocation
• Multi-provider support beyond the Anthropic API: Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform (formerly Vertex AI), and Microsoft Foundry
  Ideal use cases for the Agent SDK:
• Team platforms serving multiple users, where allowedTools restricts capabilities per request
• Long-running automation exceeding a single context window, using subagent patterns
• Non-code agents (legal review, customer service, financial compliance)
• Custom CI/CD pipelines requiring structured output parsing
• Production systems needing explicit error handling and retry logic
  Hooks are the enforcement surface, and they are the reason teams with a security boundary to hold reach for the SDK over the CLI. A PreToolUse hook runs before a tool call and can refuse it, so a rule such as never touching production credentials is enforced by code and not requested in a prompt. CLAUDE.md instructions are interpreted by the model and degrade as context fills; a hook fires every time. Paired with allowedTools and permission modes set per invocation, hooks are what give a shared agent an auditable blast radius.

Two defaults changed when the Claude Code SDK became the Claude Agent SDK at v0.1.0, and both matter in production. The SDK no longer loads Claude Code's system prompt by default; a minimal prompt takes its place, and Claude Code's behavior has to be requested explicitly as a preset. Filesystem settings are the second: omitting settingSources loads user, project, and local settings the way the CLI does, including CLAUDE.md files and custom commands. Passing an empty settingSources array runs the agent isolated from all of them, which is what CI/CD pipelines, deployed applications, test environments, and multi-tenant systems need so that one developer's local customizations cannot leak into everyone's agent.

The SDK fits systems where the application drives the agent, and the integration requires typed messages, hooks, and code-level control over tools and settings.

Claude Code vs Claude Agent SDK at a Glance

The table below maps the key architectural and operational differences between the two tools.

Key Differences: Interface, Extensibility, Orchestration, Deployment

Interface

Claude Code provides a full interactive experience: natural-language prompts, slash commands (/compact, /init, /ide), inline diffs in VS Code, and a desktop app with parallel-session support. None of that exists here. The interface is the query() async generator and the typed message stream it returns. The SDK overview draws the same boundary between interactive development and programmatic embedding.

Extensibility

Claude Code extends through CLAUDE.md configuration files loaded into every session, custom slash commands defined in .claude/commands/, and Skills. Behavior is controlled programmatically, with system prompts, allowed tools, hooks, and settings sources all set per query() invocation via ClaudeAgentOptions. For teams that need deterministic behavioral enforcement, the SDK's hooks system fires unconditionally, while CLAUDE.md instructions are model-interpreted and can degrade as context grows.

Orchestration

Both tools support multi-agent patterns, but through different mechanisms. Claude Code manages orchestration through its agent loop with human oversight available at each step. Orchestration logic lives in prompts and conversation history, giving developers explicit control over routing, parallel execution, and subagent lifecycle. Anthropic's own multi-agent research system used Claude Opus 4 as orchestrator and Claude Sonnet 4 as subagents: a mixed-model pattern available through the SDK.

Deployment

Claude Code deploys across terminal, IDE, desktop app, web, and CI/CD. Building the surrounding integration layer around the library interface is left to the developer. Sandboxing uses Linux bubblewrap and macOS Seatbelt, and Anthropic's own measurements put the reduction in permission prompts at 84% in internal usage.

When to Use Each (and When You Need Both)

One question decides it. Is a human driving the agent, or is the application?

When a human developer is driving the work interactively, Claude Code is the right tool. Spec-driven refactors, PR automation, codebase onboarding, security reviews on changed files: these are Claude Code's core territory.

When an application or automated system is driving the agent, the SDK is the right tool. Multi-user platforms, long-running automation exceeding a single context window, non-code agents (legal, finance, customer service), and production systems requiring structured error handling all require the SDK's programmatic control surface.

The two also combine. Prototype in Claude Code, then productionize in the SDK. Anthropic describes the Agent SDK as exposing Claude Code's tools and runtime for building production agents. The workflow follows five steps: explore in Code, prototype in Code, extract working prompts, embed in the SDK with hooks and error handling, and deploy.

Known Limitations

Context compaction is lossy in both tools. Anthropic's Agent SDK writeup documents automatic compaction and context-management capabilities for long conversations, and a reproducible bug report filed on July 10, 2025 and since closed documented a compaction failure that left sessions stuck in a permanent compaction loop. Any deployment running long enough to rely heavily on compaction needs deliberate context management.

Per-query latency is worth measuring, not assuming. A GitHub issue opened on October 18, 2025 reported a consistent 12-second overhead on every query() call and traced it to the SDK starting a fresh process on every call, with no warm process reused. That issue is now closed. Neither the figure nor its fix should be taken on trust, so the version that actually ships needs its own measurement.

Permission fatigue shaped how the modes work. Manual mode prompts before most file edits, shell commands, and network calls, which is why auto mode, where a classifier reviews each action, is the built-in starting mode on Pro, Max and Team plans. At the far end, bypassPermissions auto-approves writes to protected paths such as .git, .vscode, and .claude, a scope Anthropic pairs with containers and non-root users; plan-mode sessions can reach the same approvals where bypass permissions are available.

Where a Managed Agent Platform Fits

The gap between Claude Code's single-session interactive model and the Agent SDK's build-it-yourself requirement leaves a middle ground: teams that want agents running against their codebase without writing and maintaining the orchestration layer themselves.

Cosmos, Augment Code's unified cloud agents platform, sits in that middle ground and is available on all paid plans. Where the Agent SDK gives a library and expects an application around it, Cosmos supplies the surrounding platform and expects configuration where the SDK expects integration code. Its documented building blocks are Experts, Environments, Capabilities, Triggers, Sessions, Automations, and Files.

A platform differs from a library in how work starts and in what outlives it. An Expert responds to the outside world through triggers that begin a session from a first-party integration such as GitHub, Linear, Slack, GitLab, or PagerDuty, from a schedule, or from a webhook; through subscriptions that keep a running session listening for follow-up events; and through integrations that give it scoped access to external systems. Each Expert runs in its own Environment, which is sandboxed and ephemeral, pausing after inactivity and possibly restarting from a clean state. Sessions outlive the environment. The conversation is retained and auditable, saved indefinitely, and can be reopened later.

Augment Code ships Experts, so not every role has to be built from nothing. Deep Reviewer and Risk Analyzer handle review, Pair Reviewer works alongside a developer, Code Review Memory carries what earlier reviews established, and PR Author, PR Fixer, and Verifier take a task from description through implementation to a check against a live environment. Teams can fork any of them or build their own. Prism model routing picks a model per conversational turn, which Augment's routing writeup puts at 20 to 30% lower cost per task than frontier reasoning models, with a negligible quality difference. Bring-your-own-key model choice is supported.

None of this replaces the Agent SDK for a team that needs a custom agent embedded in its own product. Cosmos replaces the coordination layer that team would otherwise write first.

What to Do Next

So the choice is not about capability at all. It is about who holds the wheel. Claude Code handles the first case with zero setup. The Agent SDK handles the second with full programmatic control. The hybrid pattern holds because each tool fits a different phase of the development lifecycle.

A third answer is that neither tool is the unit of the decision. A team that wants agents working on its codebase continuously, triggered by its own systems and reviewable afterwards, is choosing a platform, not an interface, and Cosmos is that option on all paid plans.

Frequently Asked Questions About Claude Code vs the Claude Agent SDK

Related Reading

• 9 Open-Source Agent Orchestrators for AI Coding (2026)
• 8 Best AI Coding Assistants by Job [Updated August 2026]
• 5 Best Agentic Development Environments for Enterprise Teams in 2026
• 7 AI Tools That Actually Understand Enterprise Codebases
• 8 Best AI Tools for Spec-Driven Development