lockstep
4 min readNaman Jain

Claude Agent SDK vs Claude Code: which one to use

Claude Agent SDK vs Claude Code, headless mode, the Client SDK, and Managed Agents: what each is, what they share, and which fits the agent you're building.

A team builds an internal bot that triages failing CI runs. The first version shells out to claude -p and parses JSON. It works, until they want to approve some tool calls from Slack, stream progress to a dashboard, and resume a run the next morning. Now they're building an application around a CLI, which is exactly what the Agent SDK is for.

This guide compares Claude Code, headless mode, the Agent SDK, the Client SDK, and Managed Agents, from Anthropic's Agent SDK overview, checked on 16 November 2026.

The short answer

You want toUse
Work interactively, or run one-off tasks from a terminalClaude Code
Script Claude Code in CI or a shell, or from any languageHeadless mode: claude -p --output-format json
Embed Claude Code's agent in your own Python or TypeScript appClaude Agent SDK
Call the model directly and write the agent loop yourselfClient SDK (the Anthropic API)
Have Anthropic host the agent loop and sandboxManaged Agents

What the Agent SDK is

Anthropic describes it as Claude Code as a library. It gives you the same tools, agent loop, and context management that power Claude Code, in Python and TypeScript, and runs the Claude Code binary under the hood.

What you get, per the docs:

CapabilityWhat it does
Built-in toolsRead, write, and edit files, run commands, search the web
HooksRun your code at points in the agent lifecycle
SubagentsSpawn focused agents for subtasks
MCPConnect external tools and data
PermissionsChoose which tools run automatically and which need approval
SessionsKeep context across exchanges, resume or fork later
Skills, commands, memoryLoad from the project's .claude/ and ~/.claude/, as in Claude Code
PluginsLoad skills, agents, hooks, and MCP servers by path

Install with pip install claude-agent-sdk or npm install @anthropic-ai/claude-agent-sdk. A minimal Python agent, adapted from the quickstart:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix them.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        print(message)

asyncio.run(main())

Agent SDK vs Claude Code

They share an engine. The difference is who's at the keyboard.

  • Claude Code is for a developer working interactively: prompts, permission dialogs, slash commands, a terminal or IDE interface.
  • The Agent SDK is for code driving the agent: your application sends the prompt, handles each message as it streams, decides permissions in a callback, and stores the session.

If a person will sit with the agent, use Claude Code. If the agent is part of a product or internal service, use the SDK.

Agent SDK vs headless mode

Headless mode, claude -p, runs Claude Code non-interactively and can print JSON. Anthropic's docs point to it for driving the agent loop from a language other than Python or TypeScript.

Choose headless mode for shell scripts, CI steps, and quick automation. Choose the SDK when you need typed messages, streaming into your own UI, hooks and permission decisions written as functions, or sessions managed from code.

Agent SDK vs the Client SDK

The Client SDK calls the Claude API directly. You get model responses; you write the tool definitions, the loop that runs tools and sends results back, and context management. That's the right choice for a chatbot, a classification pipeline, or an agent whose tools are nothing like file editing and shell commands.

The Agent SDK is the right choice when your agent needs to work with files, code, and commands, and you'd rather not rebuild what Claude Code already does.

Things to know before shipping

  • Authentication: use an API key. Anthropic's docs say third-party products built on the SDK may not offer claude.ai login or rate limits unless previously approved.
  • Terms: use is governed by Anthropic's Commercial Terms of Service.
  • Branding: your product can't be called Claude Code or look like it. "Powered by Claude" is allowed.
  • Configuration: because skills and memory load from .claude/, the repository your agent runs in shapes its behavior. Check what's there.

Where Lockstep fits

An SDK agent working in a repository has the same blind spot as a person-driven session: it knows the code, not the decisions behind it. Lockstep captures team decisions from PRDs, Slack, and pull requests, routes them to their owners for approval, and serves them through an MCP server that any MCP client, including an Agent SDK application, can call. The automatic session briefing is built for interactive Claude Code sessions.

See how it works.

Sources checked 16 November 2026

For scripting Claude Code, see Claude Code headless mode. For running it in CI, see Claude Code GitHub Actions. For the MCP side, see Claude Code MCP setup. For the harness concept behind the SDK, see what an AI coding agent harness is.

Frequently asked questions

What is the difference between the Claude Agent SDK and Claude Code?
Claude Code is an interactive app for developers, in the terminal, IDE, or desktop. The Agent SDK gives you Claude Code's agent loop, built-in tools, hooks, permissions, subagents, MCP, and sessions as a Python or TypeScript library, so you can build your own agent application on it.
Should I use the Agent SDK or claude -p?
claude -p with --output-format json is quickest for scripts, CI jobs, and languages other than Python or TypeScript. The Agent SDK fits when the agent is part of an application: you get typed messages, streaming, programmatic hooks and permission callbacks, and sessions you can resume or fork from code.
What is the difference between the Agent SDK and the Anthropic Client SDK?
The Client SDK calls the Claude API directly. You get model responses and write the tool loop, tools, and context management yourself. The Agent SDK includes all of that: Claude Code's tools, agent loop, and context management are built in.
Does the Claude Agent SDK read CLAUDE.md and skills?
Yes. Skills, commands, and memory load from the project's .claude/ directory and from ~/.claude/, the same as Claude Code, according to Anthropic's docs. Plugins can be loaded by local path.
Can I use my Claude subscription with the Agent SDK?
For your own products, no. Anthropic's docs say third-party developers may not offer claude.ai login or rate limits in products built on the Agent SDK unless previously approved, and should use API key authentication. Use is governed by Anthropic's Commercial Terms.

Keep reading