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 officially renamed it in March 2026. That rename created a naming split that implies two separate products. In practice, 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."

The Xcode integration announcement described Xcode 26.3 as introducing support for agentic coding with coding agents such as Anthropic's Claude Agent, while third-party reports characterized this as a native integration with the Claude Agent SDK that powers Claude Code.

Several misconceptions appear repeatedly 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.

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.

The core capability that separates Claude Code from autocomplete tools: you give it a high-level instruction ("refactor the auth module to use the new token service, run tests, fix failures"), and it executes a multi-step plan across files, commands, and verification loops. You can interrupt at any point with Esc, and press Esc twice quickly to perform 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)
• Five permission modes for managing how it uses tools and edits code
• 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 rather than relying on 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. 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 rather than a standalone UI. Anthropic's migration guide documents the package and class changes from the older Claude Code SDK naming to the Claude Agent SDK naming.

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 hooks (PreToolUse, PostToolUse, Stop) for deterministic behavioral enforcement
• Session management with persistence across turns via sessionId
• Custom system prompts and settings source control per invocation
• Multi-provider support: Anthropic API, Amazon Bedrock, Google Vertex AI, Azure

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 need explicit error handling and retry logic

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. The SDK provides none of this. Its 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. The SDK controls behavior programmatically: system prompts, allowed tools, hooks, and settings sources are 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. The SDK embeds orchestration logic 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. The SDK requires developers to build the surrounding integration layer around the library interface. Sandboxing uses Linux bubblewrap and macOS Seatbelt, reducing permission prompts by 84% in Anthropic's internal usage.

When to Use Each (and When You Need Both)

The decision reduces to a single question: Is a human driving the agent, or is your 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 most compelling pattern is using both: prototype in Claude Code and 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.

Limitations Worth Knowing

Context compaction is lossy in both tools. Anthropic's Agent SDK writeup documents automatic compaction and context-management capabilities for long conversations, and a confirmed bug documents compaction failures that corrupt session state. Any deployment running long enough to rely heavily on compaction needs deliberate context management.

The Agent SDK has a specific latency constraint: a confirmed GitHub issue documents a consistent 12-second overhead per query call due to process spawning. This makes the SDK a poor fit for applications requiring very low-latency responses. Anthropic maintainers discussed daemon mode as a possible solution to the per-query process-spawn latency.

Permission fatigue is a frequently cited friction point in Claude Code: repeated confirmation prompts before file edits, command execution, and git operations. The auto permission mode mitigates this by having a classifier evaluate each action autonomously, while bypassPermissions permits all actions except for protected paths such as .git, .vscode, and .claude to ensure uninterrupted execution.

How Intent Addresses the Gap Between These Two Tools

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 need multi-agent orchestration but don't want to build the coordination layer from scratch.

Intent, Augment Code's agentic development environment, addresses this gap through a BYOA (Bring Your Own Agent) model. Teams with existing Claude Code subscriptions can use those agents directly within Intent's orchestration framework without switching providers or purchasing a separate Augment subscription. Claude Code subscriptions remain billed through Anthropic when used via BYOA.

Intent's agent architecture maps three roles:

The living spec model addresses a specific limitation Claude Code shares with some agent tooling: Claude Code does not natively detect when implementation drifts from the original plan. Intent's specs auto-update as agents complete work, and when requirements change mid-development, updates propagate to all active agents.

For teams already running custom agents built through the Agent SDK, Intent's BYOA model orchestrates Claude Code instances rather than raw SDK invocations. The value it adds over either Anthropic tool alone is coordinated multi-agent work within isolated workspaces, where each Implementor works in a separate git worktree, and the Coordinator tracks progress against a living, spec-driven development plan.

Pick the Right Layer for How Your Team Works

The Claude Code vs Agent SDK decision reduces to a single question: is a human driving the agent, or is your application? Claude Code handles the first case with zero setup. The Agent SDK handles the second with full programmatic control. The hybrid pattern (prototype in Code, productionize in SDK) remains compelling because each tool fits a different phase of the development lifecycle.

For teams that need multi-agent orchestration without building coordination infrastructure from scratch, Intent's BYOA model provides a spec-driven workspace that keeps agents aligned through living documentation.

Frequently Asked Questions About Claude Code vs the Claude Agent SDK

Related Guides

• Codex 2.0 vs Cursor vs Copilot CLI vs OpenCode: Which Wins
• Native MCP Standard for AI Agents vs API Wrappers
• AI Stacks: 5 Integrated Platforms vs Build-Your-Own Toolchains
• Claude Code Alternatives for Enterprise Development Teams
• Replit Agent vs Cursor vs Augment Code: Which Scales for Enterprise