--- title: kiliczsh/claude-agents-sdk-swift framework: Swift Package Catalog role: article path: packages/kiliczsh/claude-agents-sdk-swift --- # 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 ```swift .package(url: "https://github.com/kiliczsh/claude-agents-sdk-swift.git", from: "0.1.0") ``` Depend on the `ClaudeAgentSDK` product. ## Quick start ```swift 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____` 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 6. 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