Contents

kiliczsh/claude-agents-sdk-swift

Unofficial Swift Claude Agent SDK for macOS applications.

Requirements

  • macOS 14+
  • Swift 5.9+
  • Claude Code CLI installed and authenticated (the SDK launches it as a

child process; an explicit executable URL can also be provided)

  • No external package dependencies

Installation

.package(url: "https://github.com/kiliczsh/claude-agents-sdk-swift.git", from: "0.1.0")

Depend on the ClaudeAgentSDK product.

Quick start

import ClaudeAgentSDK

// Resolve the Claude Code executable (PATH, Homebrew, /usr/local/bin —
// or pass .explicit(url) for a known location).
let executable = try ClaudeCLIResolver()
    .resolve(.systemSearch(configuredDirectories: []))

let transport = ClaudeProcessTransport(
    configuration: try ClaudeProcessConfiguration(executableURL: executable)
)

let session = ClaudeAgentSession(transport: transport)
try await session.connect()

let reader = Task {
    for try await message in session.messages {
        switch message {
        case .assistant(let assistant):
            // Typed content blocks (text, tool use, ...)
            print(assistant)
        case .result(let result):
            print("Turn finished:", result)
        default:
            break
        }
    }
}

try await session.send(prompt: "Summarize this project")

ClaudeAgentOptions configures the session (system prompt, model, permission mode, allowed/disallowed tools, in-process SDK MCP servers, working directory). session.interrupt(), setModel(:), and setPermissionMode(:) are available at runtime; session.close() shuts the child process down deterministically.

Status

Implemented, with an 81-test suite that runs against scripted in-memory transports and fixtures (no live CLI required):

  • lossless JSONValue, typed foundation errors, diagnostics, and redaction;
  • deterministic Claude Code executable lookup and semantic version policy;
  • explicit child-environment and command construction;
  • byte-based NDJSON framing with a configurable 1 MiB limit;
  • an actor-isolated ClaudeProcessTransport with a transport-local

non-blocking write queue, redacted stderr diagnostics, connect/close race guards, cancellation cleanup, and EOF -> SIGTERM -> SIGKILL -> reap shutdown escalation on every exit path including protocol errors;

  • typed content messages (ClaudeMessage/ClaudeContentBlock) with

unknown-kind preservation and fail-closed parsing of known kinds;

  • ClaudeAgentSession: initialize handshake, control-protocol

request/response matching with timeout, interrupt/setModel/ setPermissionMode, and spec-shaped user turns; and

  • in-process SDK MCP tools (ClaudeSdkTool/ClaudeSdkServer) dispatched

over the control protocol (tools/list, tools/call), with mcp<server><tool> naming and --mcp-config serialization matching the Python SDK.

Not yet implemented: hooks, an interactive canUseTool permission callback (pre-approve via allowedTools instead), session resume/fork, and the one-shot convenience query() wrapper. bypassPermissions requires an explicit dangerouslyAllowBypassPermissions opt-in.

Reference baseline

The initial implementation is pinned to the following upstream baseline, verified on 2026-07-09:

| Reference | Version | Claude Code | Use in this project | |---|---:|---:|---| | claude-agent-sdk-python | 0.2.114 (fdee0ad) | 2.1.205 | Canonical readable implementation for transport, parsing, control flow, and lifecycle | | @anthropic-ai/claude-agent-sdk | 0.3.205 | 2.1.205 | Public API and behavioral cross-check through its published declarations and examples | | Claude Agent SDK documentation | 2026-07-09 snapshot | 2.1.205 era | Product semantics, supported workflows, authentication, and deployment guidance |

The Python SDK is MIT licensed. The TypeScript SDK is publicly distributed but its implementation is not open-source; its declarations are a compatibility reference, not source to copy. Claude Code itself is subject to Anthropic's applicable terms.

Runtime model

Claude Agent SDKs run an agent loop inside Claude Code rather than reimplementing that loop in the host language. The SDK covers this complete model:

  1. resolve an explicit or system-installed claude executable;
  2. launch it with stream-JSON input and output;
  3. exchange newline-delimited JSON over stdin and stdout;
  4. decode messages into typed, forward-compatible Swift values;
  5. service control requests for permissions, hooks, MCP tools, user input, and

session operations; and

  1. shut the process down deterministically when its Swift task or session ends.

Official Python and TypeScript packages bundle platform-specific Claude Code binaries. This repository will expose a bundled-URL provider, but will not redistribute the Claude Code binary until redistribution, signing, update, and notarization requirements are explicitly resolved. An external executable is the v1 default.

macOS distribution target

The first supported application profile is a Developer ID-signed and notarized macOS app. Mac App Store/App Sandbox compatibility is a separate validation track because a sandboxed child process inherits restrictions that affect file access, command execution, session storage, and networking.

The SDK will not assume that a GUI app has a shell-configured PATH. macOS hosts must be able to provide an executable URL, a security-scoped working directory, an app-owned Claude configuration directory, and an explicitly constructed child-process environment.

Authentication

Third-party products must use an Anthropic API key or a supported cloud provider rather than offering Claude.ai OAuth login on behalf of their users. The host application owns credential storage, normally Keychain, and supplies credentials only to the child-process environment. The SDK will never persist API keys in session data or logs.

Scope

Version 1 targets the capabilities needed by a real interactive macOS client:

  • one-shot and persistent streaming sessions;
  • complete and partial response streaming;
  • interruption and runtime control requests;
  • typed tool approvals and AskUserQuestion interactions;
  • hooks and in-process Swift MCP tools;
  • structured output, session resume, usage/cost reporting, and file

checkpointing;

  • forward-compatible message decoding; and
  • deterministic subprocess cleanup and cancellation.

Direct Anthropic API access, iOS, Linux, Windows, and automatic Claude Code binary installation are outside the initial scope.

Disclaimer

Unofficial community implementation; not published or endorsed by Anthropic. Although the public Agent SDK is documented, the CLI stream/control protocol is not a standalone public specification. Compatibility must therefore be tested against recorded SDK and CLI versions before a new version is declared supported.

Package Metadata

Repository: kiliczsh/claude-agents-sdk-swift

Default branch: main

README: README.md