CLAUDE.md

Build & Test Commands

# Build all targets
swift build

# Run all tests (mocked — no API key required)
swift test

# Run a specific test target
swift test --filter AIProviderKitTests
swift test --filter ClaudeProviderTests

# Run a single test by name
swift test --filter AIClientTests/sendForwardsRequest

# Run integration tests against the real Claude API (requires ANTHROPIC_API_KEY)
ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY> swift package integration-tests

Architecture

This is a Swift Package with the following library products:

• AIProviderKit — Core protocols, models, builders, registries, and the AIClient actor. Has no external dependencies.
• ClaudeProvider — Anthropic Messages API implementation. Depends on AIProviderKit.
• AIProviderKitPersistence — SwiftData-backed conversation persistence with .chat export/import. Depends on AIProviderKit.
• AIProviderKitUI — Optional SwiftUI AILogView for in-app log viewing. Depends on AIProviderKit.

Key design patterns

AIClient (actor) is the main entry point. It owns a ToolRegistry, SkillRegistry, and RecipeRegistry (all actor-based). When send(_:) is called and the model returns a toolUse stop reason, AIClient executes the tools concurrently via withThrowingTaskGroup and sends a follow-up request automatically — this loop repeats until the model stops requesting tools.

AIProvider protocol is the only integration point for new providers. Implement send(_:) for request/response and optionally StreamableProvider for SSE streaming. No changes to AIClient or any core type are needed.

ClaudeProvider internals follow a mapper pattern:

• ClaudeRequestMapper — converts AIRequest → Claude-specific request body
• ClaudeResponseMapper — converts Claude response / SSE data → AIResponse / AIStreamEvent
• HTTPClient protocol (implemented by URLSessionHTTPClient) is injected, enabling test substitution via MockHTTPClient

ContentBlock is the universal currency for message content (.text, .image, .toolUse, .toolResult). All providers map to/from this type.

JSONValue is the untyped value type used for tool inputs/outputs, avoiding Any.

Adding a new provider

1. Add a library + target in Package.swift (see commented-out OpenAI entries as a template)
2. Create a folder under Sources/ with a mapper pair (XRequestMapper, XResponseMapper), an HTTPClient implementation, and the provider class conforming to StreamableProvider
3. Extend AIModel with provider-specific model constants
4. See Documentation/AddingAProvider.md for a full walkthrough

Testing conventions

Tests use Swift Testing (@Suite, @Test, #expect). Each test follows given / when / then with comments. Mocks live in Tests/<Target>/Mocks/:

• MockAIProvider — configurable stub that records received requests
• SequentialMockProvider — returns a queue of pre-configured responses (used for multi-turn tool-use tests)
• MockHTTPClient — stubs HTTP at the network layer for ClaudeProvider tests

Platform & language requirements

• Swift 6, full Sendable compliance, StrictConcurrency and ExistentialAny upcoming features enabled on all targets
• iOS 26+ / macOS 26+ / watchOS 11+ / tvOS 26+ / visionOS 2+
• Use async/await and actors throughout; avoid callback-based or GCD patterns

Documentation conventions

• Diagrams — always use Mermaid for any architecture, sequence, or flow diagram. Never use ASCII art. Supported diagram types in this project: graph (dependency / module graphs), sequenceDiagram (request/response flows), flowchart (decision flows).
• Issue files — detailed design for a milestone lives in Documentation/Issues/<slug>.md. The ROADMAP entry links to it and contains only a one-sentence intro + flat - [ ] checklist.
• ROADMAP format — each milestone uses a short intro paragraph (optional) and a flat bullet checklist. No sub-headers, no code blocks, no diagrams inside ROADMAP.md itself.

Documentation assets

Banner updates: use the /update-banner skill. Canonical palette and layout rules live in .claude/skills/update-banner/SKILL.md — do not duplicate colors here.