Claude Swift SDKs

Development biography · earlier archive

Development profile compiled from project source and retained records in October 2026. Dates and test results describe those records; they do not imply a new build, live acceptance test or public release.

Port vs upstream (read first)

• Upstream products (Anthropic): the Claude API, the Anthropic TypeScript and Python SDKs, the Claude Agent SDK (Python and TypeScript), Claude Code, and Anthropic's examples, quickstarts and cookbooks. Anthropic builds, owns and publishes these.
• Local ports: independent Swift 6 re-implementations, written in this workspace from 2026-09-25 with AI assistance (Claude Code sessions). They aren't published by Anthropic or endorsed by it.
• Where they live: branch swift-sdk-port, pushed to the private GitHub repo entertrainment/claude-swift-sdks.
• Owner: the local workspace owner (Douglas, Entertrainment). No public authorship statement exists in the repo, so treat attribution as "private port by Entertrainment".
• Site wording: always say "Swift port of …", never "Anthropic's Swift SDK".

Claude Agent SDK for Swift (swift/ClaudeAgentSDK)

Biography (~650 words). Anthropic's Claude Agent SDK packages the engine behind Claude Code as a library: the agent loop, the built-in tools (Read, Write, Bash, …), hooks, permissions and session management. Officially it exists for Python and TypeScript. Swift developers building Mac tools, server-side Swift services or Apple-platform apps had no native way to embed that agent loop. This port fills the gap. It was written in September 2026 as part of a wider effort to port everything convertible in Anthropic's open-source developer material to Swift.

The design follows the Python SDK's architecture and keeps the same wire protocol. The library launches the claude CLI and exchanges newline-delimited JSON control messages with it. Swift idioms replace Python's. query(prompt:options:) returns an AsyncThrowingStream<Message, Error> for one-shot tasks. ClaudeSDKClient is an actor for multi-turn conversations: follow-up questions, interrupts, mid-session model or permission-mode changes, MCP server status, context usage and file rewinds. Cancelling the Swift task or breaking out of the loop stops the CLI. Options are a struct with a closure initializer, so call sites stay short.

The port also has the features that, upstream, only the TypeScript SDK offers. These include capability lists, plugin and skill reloads, settings updates, side questions, conversation rewind, background tasks, session titles, prompt suggestions and progress summaries. On 2026-09-27 the port was checked against the official TypeScript typings (sdk.d.ts, npm @anthropic-ai/claude-agent-sdk 0.3.283). That check added seven controls, elicitation and user-dialog callbacks, and typed inputs and outputs for all 33 hook events. Every system message subtype is typed. Tripwire tests fail if new upstream items appear unhandled.

Custom tools run in-process: you register Swift closures as an MCP server, and Claude calls them with direct access to your app's state. A tool's JSON schema can be derived automatically from a Decodable input type. canUseTool lets an app approve or deny each tool call. environmentPolicy limits which environment variables the CLI inherits.

A distinctive addition is remote sessions. iOS and visionOS can't spawn a CLI, so the SDK ports the npm package's browser transports (SSE and WebSocket). An iPhone or Vision Pro app can attach to a Claude Code session running elsewhere. The transports have resume, liveness timeouts, bounded reconnects and strict frame trust rules.

User journey: a developer adds the package by path or git URL and installs the claude CLI. They write for try await message in query. As Claude works, they see typed assistant, tool-use and result messages, ending with turns taken and cost. Next they switch to ClaudeSDKClient for a conversation, add a PreToolUse hook to log tool calls, and a canUseTool callback that refuses shell commands.

Live evidence is modest but real. On 2026-09-27, against the real Claude Code CLI 2.1.233 on Claude Haiku 4.5 (about $0.001 in total):

• a one-shot query returned its typed init message;
• a client session read a file through the Read tool, with the PreToolUse hook firing;
• a denied Bash command never ran;
• readFile, getServerInfo and reinitialize worked;
• the opt-in end-to-end test passed.

Features (authored by the port unless noted):

• query() and ClaudeSDKClient.
• Typed messages and hooks.
• In-process MCP tools; the protocol comes from the upstream MCP spec.
• Permission callbacks and environment policy.
• The TS-only session controls.
• Remote SSE/WebSocket transports.
• E2E test gated by CLAUDE_AGENT_SDK_E2E=1.

Dependency: the Claude Code CLI (Anthropic's product, not bundled). No Swift package dependencies.

Technical foundations:

• Swift 6 strict concurrency; Foundation only.
• Close-on-exec pipes and serialized process launches; the Linux child-process races were found and fixed during the port.
• swift-testing; 558 tests.

Maturity (dated):

• Source: implemented (2026-09-26/27).
• Tests: 558 pass on macOS and Linux .
• Built: debug builds for macOS, Linux, iOS and visionOS. A release build hasn't been recorded.
• Runtime: verified live on macOS only, 2026-09-27 (above).
• Remote transports: tested against mocks, never live.
• Released: no. Private repo; no tag, version number or package registry listing found.

Limits:

• Needs the claude CLI locally.
• Some newer controls (reloadOutputStyles, readMcpResource, updateSettings, projectConfigRoot, permissionPrompts, perTaskStopAffordance) need a CLI newer than 2.1.233.
• The deprecated V2 session API isn't ported; upstream removed it.
• No Windows-specific handling.

FAQs:

• Is it official? No. It's a private Swift port of Anthropic's open-source SDK.
• Does it need Claude Code installed? Yes, on macOS and Linux. Not for remote sessions.
• Does it work on iPhone? Only by connecting to a remote Claude Code session.
• Any dependencies? Foundation only.

Anthropic Swift API Library (swift/AnthropicSDK, module Anthropic)

Biography (~620 words). Anthropic publishes official SDKs for several languages but not Swift. Apple-platform and server-side Swift developers have relied on thin community wrappers that cover the Messages endpoint and little else. This port set out to match the TypeScript SDK feature for feature. That means every endpoint in its api.md, including the large beta surface (managed agents, sessions, environments, memory stores, vaults, tunnels, deployments, organisation admin, webhooks), plus the helpers that make the SDK pleasant to use.

The library reads ANTHROPIC_API_KEY like its upstream. A message is one call: client.messages.create(MessageCreateParams(model: .claudeSonnet5, maxTokens: 1024, messages: [.user("Hello, Claude")])). Streaming gives a textStream to print as text arrives, then the accumulated final message. Structured output turns a reply straight into a Swift type: messages.parse(params, as: MyType.self). The JSON schema is derived from the Decodable type, with no macros. On Apple's newest OSes, Apple's FoundationModels @Generable types work too. Tool runners execute your Swift tools in a loop until Claude finishes. API unions are Swift enums with an unknown case, so newer server responses decode without breaking older apps.

Cloud support is a major part. AnthropicClient.bedrock(BedrockConfiguration(region:)) signs requests with AWS SigV4 and decodes Bedrock's binary event stream. A full AWS credential chain is included: environment variables, profiles, credential_process, web identity, ECS, EC2 metadata, and, since 2026-09-28, aws login, SSO and role profiles via the AWS CLI. Vertex AI, Microsoft Foundry and Claude Platform on AWS and GCP have their own clients.

The port also brings Anthropic's self-hosted environment tooling to Swift. That covers the worker and a local agent toolset (bash, read, write, edit, glob and grep, confined to a working folder). It can download and safely extract agent skills, using its own zip, tar and DEFLATE readers. It also syncs memory stores both ways, following the Python SDK's rules.

User journey: an iOS developer adds the package and calls create with a prompt, then switches to stream to show text as it arrives. They define a struct Recipe: Decodable and call parse(_, as: Recipe.self) to get typed data. A company on AWS swaps in AnthropicClient.bedrock(...) without touching the rest of its code.

Live evidence:

• On 2026-09-27/28, on Amazon Bedrock (eu-west-1, Claude Haiku 4.5 inference profile), all four smoke-test steps passed: create, stream, the tool runner and structured parse. Total cost was under one cent.
• The live run exposed a real bug: Bedrock omits a caller field the types required. It was fixed in commit c38ec05 with a regression test.
• On 2026-09-29, the same four steps passed using only the SDK's own credential chain with an aws login session (commit fd7be7a).
• The first-party Claude API itself hasn't been called live.

Features (authored port):

• Full endpoint coverage, with typed models.
• Streaming, structured output and tool runners (GA, beta and sessions).
• Batches, files, models and skills.
• Cloud clients and the AWS/GCP credential chains.
• Request middleware, a logger and pagination.
• Webhook verification.
• Environment worker, agent toolset, skills extraction and memory-store sync.
• FoundationModels bridge on Apple platforms.

Dependencies: none beyond Foundation. The AWS CLI is optional, used only for aws login/SSO/role profiles.

Technical foundations:

• Swift 6 strict concurrency.
• URLSession, with a delegate-based streaming path on Linux.
• Hand-written AWS SigV4 and event-stream decoding; generated, version-checked model types.

Maturity (dated):

• Source: complete, 201/201 endpoints (2026-09-26).
• Tests: 512 pass on macOS and 508 on Linux (2026-09-28).
• Built: debug builds pass. The release build is currently broken on the Xcode 26 toolchain . There's no fix commit yet.
• Runtime: verified live on Bedrock only.
• Released: no. Private repo, no version tag.

Limits:

• Release builds fail on Xcode 26 until the fix above lands.
• Not live-tested against api.anthropic.com, Vertex, Foundry or Claude Platform.
• Not ported: Google external_account and impersonated credentials; the Zod/Standard Schema helpers (Swift types are used instead); OpenTelemetry propagation.
• Google service-account keys need a token provider on Linux.

FAQs:

• Official? No. It's a private port of Anthropic's TypeScript SDK.
• Which platforms? All Apple platforms from 2022-era versions, plus Linux.
• Bedrock? Yes, verified live. The AWS account must first submit Anthropic's use-case form.
• Dependencies? None beyond Foundation.

Related ports (short, supporting entries; not separate products)

ClaudeForFoundationModels (swift/ClaudeForFoundationModels) is a clone of Anthropic's anthropics/ClaudeForFoundationModels. Only its local anthropic-sdk branch (rebased onto AnthropicSDK, 244 tests) is local work. Present it as upstream plus a local branch, not as a port.

Roadmap (from HANDOFF "Remaining work")

• Fix the Xcode 26 release-build compiler crash (urgent; blocks AssistantApp release builds).
• Live-test against the first-party Claude API, then the cookbooks and examples.
• Run the Swift sandbox worker in a live session before it replaces the Python worker.
• Possibly publish: no decision is recorded.