Claude Code SDK

Claude Code SDK Overview & Architecture

The SDK gives your application an agent that can use tools.

The basic loop is:

Prompt
  |
  v
Claude Agent SDK
  |
  +--> Read and search
  +--> Edit files
  +--> Run approved tools
  |
  v
Structured result

Your application controls tools, permissions, model choice, and output handling.

Treat the SDK as an orchestration layer around an agent runtime, not as a simple text-completion wrapper. A production integration should define the working directory, allowed tools, approval policy, environment variables, output format, logging, timeout behavior, and failure handling before the agent starts.

A safe architecture usually separates five responsibilities:

• Input preparation: collect the repository path, issue description, branch name, test command, and any constraints the agent must follow.
• Permission control: decide whether the agent can read files, edit files, run shell commands, access network resources, or request approval before risky actions.
• Execution boundary: run the agent in a controlled workspace, preferably one that can be reset or discarded after the job.
• Result collection: capture messages, tool events, changed files, logs, structured output, and exit status.
• Review: inspect the diff, run validation, and decide whether the result can move into a pull request or deployment path.

This structure keeps the Claude Agent SDK useful for embedded coding workflows while reducing the risk of broad, unattended changes.

TypeScript SDK Setup & First Call

Install the package:

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

Minimal example:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review this repository and list the main risks."
})) {
  console.log(message);
}

Start with read-only tools. Add editing only after the workflow is tested.

For a real TypeScript integration, wrap the call in a job handler rather than placing the agent directly behind an unbounded request. The handler can create a workspace, build the prompt from a template, pass a narrow task description, stream messages to logs, and store the final output for review.

A practical first workflow is a repository review job:

1. Check out a specific commit or branch.
2. Ask the agent to inspect the repository and identify risks.
3. Allow read and search tools only.
4. Save the streamed messages and final summary.
5. Let a developer decide whether a follow-up editing job should run.

When you enable write access, keep the prompt specific. For example, ask the agent to update one module, fix one failing test, or draft one migration plan. Broad prompts such as “improve this codebase” make review harder because the output scope is unclear.

Python SDK Quickstart

Install:

pip install claude-agent-sdk

Run a query:

import asyncio
from claude_agent_sdk import query

async def main():
    async for message in query(
        prompt="Summarize this repository."
    ):
        print(message)

asyncio.run(main())

Use a virtual environment. Pin the SDK version for production.

Python works well for internal automation, evaluation scripts, repository analysis, scheduled maintenance, and service-side orchestration. Keep the SDK call inside an async task so your application can stream messages, enforce timeouts, and record output as the agent works.

A production Python workflow should also define:

• the repository or working directory the agent can access;
• the prompt template and required output shape;
• the tool permissions for read, edit, and command execution;
• the timeout and cancellation policy;
• the location for logs, JSON output, generated summaries, and changed files;
• the validation command, such as a unit test, type check, linter, or build step.

Pinning the SDK version helps keep behavior stable across deploys. If the integration runs inside CI or an internal service, store credentials through the platform secret manager and avoid passing sensitive values inside the prompt.

As you benchmark Python automation runs, Claude 3.7 Sonnet can give you a useful comparison point for latency, reasoning depth, and workflow fit.

For source-level validation, Code is worth checking after you understand the Claude Code SDK workflow described here.

Headless Mode for Automation

Claude Code also supports non-interactive execution.

claude -p "Summarize the failing tests" --output-format json

Headless mode fits CI, scripts, and scheduled work.

Set timeouts. Capture exit status. Never grant broad unattended permissions by default.

For automated runs, prefer narrow jobs with deterministic inputs: a checked-out commit, a specific prompt template, scoped credentials, and a clear artifact destination for logs or JSON output. Add retry rules carefully, since rerunning an agent with edit permissions can create different file changes unless the workspace is reset between attempts.

Good headless jobs include:

• summarizing failing tests after a CI run;
• reviewing a pull request diff for risky changes;
• generating a migration checklist from a known code path;
• drafting release notes from merged commits;
• checking documentation against code changes.

Avoid using headless mode as an unrestricted background developer. Automation should have a bounded task, a bounded workspace, and a clear review step. If the job can edit files, run it on an isolated branch or disposable worktree, then validate the result before a human or policy-controlled process accepts it.

Headless jobs that need controlled access to external tools or repositories can use Claude Code MCP to keep those integrations explicit and auditable.

When details such as limits or setup steps matter, the GitHub project can help confirm the latest implementation surface.

Subagent Orchestration with the SDK

Subagents keep separate context for focused tasks.

Good subagent roles include:

• Repository explorer.
• Test analyst.
• Security reviewer.
• Documentation writer.
• Migration planner.

Give each subagent a narrow prompt and tool list. Return a summary to the parent agent.

For a managed multi-agent coding workflow, Verdent provides planning, work allocation, isolated execution, and verification.

> A repository-level proof point > > 76.1% on SWE-bench Verified is Verdent's credibility anchor. Plan-First execution and review turn model capability into a result a team can inspect. > > Enterprise-Grade Safety controls the workspace. Code Verification controls the result.

A useful pattern is to separate investigation from modification: one subagent maps the repository and risks, another proposes a plan, and only a constrained execution agent receives write access. This makes the final review easier because each agent returns a focused summary instead of mixing discovery, implementation, and validation in one long context.

A clean handoff can look like this:

1. Repository explorer: reads the codebase and identifies the relevant files.
2. Planner: turns the findings into a small implementation plan with acceptance criteria.
3. Execution agent: edits only the files needed for the approved plan.
4. Test analyst: runs or interprets validation results.
5. Reviewer: summarizes the diff, risks, and remaining questions.

The parent process should combine these outputs into one final result: what changed, why it changed, what passed, what failed, and what still needs human judgment. Verdent extends this pattern with planning, work allocation, worktree isolation, and verification built into the delivery flow.

Before assigning subagents real repository tasks, it helps to understand how Claude Code handles file access, command execution, and developer review loops.

Before you budget a real project around Claude Code SDK, compare the claims here with Augmentcode.

SDK vs Subscription: Which to Use

Use Claude Code with a subscription for interactive development.

Use the Agent SDK when embedding the agent in a product or pipeline.

Choose the subscription path when a developer wants an interactive coding assistant in the terminal and can supervise decisions in real time. This works well for exploration, local debugging, one-off refactors, and individual productivity.

Choose the Agent SDK when your team needs to call the agent from software you control. Common examples include internal developer portals, pull request automation, repository maintenance jobs, code review workflows, and custom engineering dashboards.

Choose headless mode when the job is scriptable and does not need a custom application layer. It is useful for CI summaries, scheduled checks, and repeatable command-line tasks.

Choose Verdent when the problem is broader than a single agent run. Verdent is designed for planned, parallel, isolated, and reviewed engineering work, especially when multiple tasks need coordination across a repository.