TL;DR: All 307 Apple frameworks are now indexed. 302,424 documentation pages searchable. Community contributors added Agent Skill support and a Claude Code plugin. Homebrew resource bundle fix.

The Completionist Achievement: Unlocked

I wanted every Apple framework in the index. Not most of them. All of them.

Turns out, the crawler was only finding ~20 frameworks by following links from Apple’s developer homepage. That’s like exploring a library by only reading the “Staff Picks” shelf. The rest of Apple’s documentation was sitting there, patiently waiting to be discovered.

The fix: seed the crawler from Apple’s own technologies.json – their internal index of every framework. Feed that to the BFS crawler, and suddenly the whole library opens up.

But that was just the first of five bugs hiding in the crawl engine:

That last one was sneaky. If a page’s content hadn’t changed since the last crawl, the crawler skipped it – but skipped before adding its child links to the queue. Entire subtrees silently disappeared.

The result: 13 previously missing frameworks crawled and indexed. CoreGraphics, CoreMedia, CoreVideo, CoreText, CoreAudio, dnssd, Hypervisor, IOBluetooth, HIDDriverKit, Matter, OpenGLES, USBDriverKit, and CoreAudioTypes.

Yes, even OpenGLES. Deprecated, but completionism has no room for judgment.

Your AI agent can now answer questions about Hypervisor’s vCPU mapping and IOBluetooth’s RFCOMM channels. You’re welcome.

Community Contributions

This release marks a milestone I’m genuinely excited about: the first external contributions to Cupertino.

Both add new ways to use Apple documentation without running an MCP server. Two contributors saw something they wanted, built it, and sent a PR. That’s the open source dream right there.

Agent Skill Support (PR #167)

Tijs Teulings added support for using Cupertino as a stateless Agent Skill. AI coding agents get direct access to Apple documentation via CLI commands with JSON output – no MCP server process needed.

Install with OpenSkills:

npx openskills install mihaelamj/cupertino

Or manually copy the skill definition to .claude/skills/cupertino/.

No daemon. No stdio pipe. Just cupertino search "SwiftUI" --format json and you’re done.

Claude Code Plugin (PR #169)

Gustavo Ambrozio took Tijs’s skill and leveled it up into a proper Claude Code plugin with marketplace support.

claude /plugin marketplace add https://github.com/mihaelamj/cupertino.git

The plugin adds a manifest, marketplace metadata, and improved skill descriptions with better trigger phrases. One command to install, zero configuration after that.

Thank you Tijs and Gustavo. It’s a great feeling to see the project grow beyond a single-maintainer effort.

The Homebrew Symlink Saga

Here’s a fun one. After the v0.10 release, brew install cupertino worked fine… until you actually ran any command. Instant crash:

Fatal error: could not load resource bundle:
from /opt/homebrew/bin/Cupertino_Resources.bundle

The problem: Homebrew symlinks files from the Cellar to /opt/homebrew/bin/, but not directories. The resource bundle was sitting happily in the Cellar, but Bundle.main.bundleURL (which doesn’t resolve symlinks) was looking in /opt/homebrew/bin/ where the symlink lives. Two ships passing in the night.

The fix was two-pronged:

1. Formula: Added a post_install hook that manually creates the symlink for the resource bundle directory
2. Code: CupertinoResources.bundle now resolves symlinks via executableURL.resolvingSymlinksInPath() before falling back to Bundle.module

Belt and suspenders. If you had the crash, brew update && brew upgrade cupertino fixes it.

Search Improvements

Framework search now includes synonym matching. Because nobody remembers if it’s “CoreGraphics” or “Core Graphics”:

Case-insensitive, space-tolerant. Type it however you remember it.

Install or Update

# New install
brew install mihaelamj/tap/cupertino

# Update existing
brew update && brew upgrade cupertino

# Or one-line install
bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

Then:

cupertino setup  # Download databases (~30 seconds)
cupertino serve  # Start MCP server

Issues and PRs Closed

• #159 - Missing framework documentation
• #160 - Crawler improvements for full coverage
• #167 - Agent Skill support (@tijs)
• #169 - Claude Code plugin (@gpambrozio)
• #162 - CONTRIBUTING.md (@William-Laverty)
• #133 - README link fix (@lwdupont)
• #172 - Crawler session resume and delay fixes

Links

• GitHub Repository
• Documentation
• Release Notes

I created a GitHub repo from my phone while walking around the house. No terminal, no SSH, no laptop open. Just iMessage.

iRelay is a Swift daemon that listens for iMessages on your Mac, spawns Claude Code in your project directory, and sends the result back as a text. You message your Mac like you’d message a person, except it writes code.

GitHub: github.com/mihaelamj/iRelay

Demo

How It Works

The flow is simple:

iPhone (iMessage) → Mac (iRelay daemon) → Claude Code → response → iMessage

You send something like irelayy fix the failing test from your phone. Your Mac picks it up, runs Claude Code against your project, and texts you back with what it did.

That’s it. No web UI, no port forwarding, no VPN. Just iMessage as a transport layer.

Why the Double Y

I already run OpenClaw on the same Mac for iMessage automation. Two daemons listening to the same iMessage account would fight over every incoming message.

The fix: a prefix. iRelay claims any message starting with irelayy (double y). OpenClaw ignores those. Everything else goes to OpenClaw. Simple namespace partitioning over a shared channel.

What I Actually Did With It

First real test: I asked it to investigate my repos and suggest a business idea. It came back with MCPMe. Then I told it to create the repo, write the README, and push it. All from iMessage. The Mac did the work while I made coffee.

That’s the use case — you’re away from your desk but you want something done now. A quick fix, a repo setup, a refactor. Text it, walk away, get the result back on your phone.

Architecture

iRelay is designed around channels and providers:

• Channels handle message transport — iMessage is the one that works today. The architecture supports Telegram, Slack, Discord, Signal, Matrix, IRC, and WebChat, but those are scaffolded, not wired up yet.
• Providers handle LLM execution — Claude Code is the primary one. OpenAI, Ollama, and Gemini slots exist for future use.

Conversation history is preserved across messages, so context carries over. You can also save and restore sessions.

What’s Next

iRelay pairs well with Cupertino — when Claude Code has offline access to Apple’s documentation, the responses you get back over iMessage are significantly better. No hallucinated APIs, no deprecated patterns. I’ve been quietly working on a major Cupertino update that nearly doubles framework coverage, which will make this combination even stronger. More on that soon.

Built in a day. Used from the couch.

TL;DR: Cupertino now has setup guides for 8 different AI tools. MCP protocol upgraded to 2025-06-18. Comprehensive documentation for all binaries. No more Node.js in the codebase.

This release focuses on reach. More AI tools can use Cupertino. Better documentation. Cleaner internals.

Release Summary

Since v0.8.0, Cupertino has had 5 releases:

Multi-Agent Support (v0.9.1)

The most requested feature: “How do I use Cupertino with X?”

Cupertino started as a Claude tool. But MCP is an open protocol. Any AI assistant that speaks MCP can use it.

v0.9.1 adds setup guides for 8 AI tools:

Quick Setup

For most tools, configuration is a JSON object:

{
  "mcpServers": {
    "cupertino": {
      "command": "/opt/homebrew/bin/cupertino",
      "args": ["serve"]
    }
  }
}

The exact structure varies by tool. Full examples are in the serve command documentation.

Dynamic Path Detection

If you’re not sure where cupertino is installed:

claude mcp add cupertino -- $(which cupertino)
codex mcp add cupertino -- $(which cupertino) serve

The $(which cupertino) expands to the actual binary path. Works for Homebrew installs on both Apple Silicon (/opt/homebrew/bin) and Intel (/usr/local/bin).

MCP Protocol Upgrade (v0.9.0)

v0.9.0 upgrades the MCP protocol from 2024-11-05 to 2025-06-18.

This matters because newer AI tools expect the newer protocol. Without this upgrade, Cupertino would fail to initialize with clients that only support 2025-06-18.

The upgrade includes backward compatibility:

// Server negotiates with client
public let MCPProtocolVersion = "2025-06-18"
public let MCPProtocolVersionsSupported = ["2025-06-18", "2024-11-05"]

// During initialization, find common version
let negotiatedVersion = clientVersions
    .first { MCPProtocolVersionsSupported.contains($0) }

If a client requests 2024-11-05, Cupertino still works. If it requests 2025-06-18, that works too. The MCPClient and MockAIAgent also support version fallback when connecting to servers.

Thanks to @erikmackinnon for the contribution (#130).

Binary Documentation (v0.9.1)

Cupertino ships 4 executables. Until now, only cupertino had proper documentation.

v0.9.1 adds 48 documentation files covering all binaries:

cupertino

The main CLI with 12 commands. Already documented, but now with updated MCP client configuration examples.

cupertino-tui

The terminal UI for browsing and selecting packages:

cupertino-tui
cupertino-tui --version

5 views documented:

• Dashboard - Overview and quick actions
• Packages - Browse and select Swift packages
• Archive - Apple Archive documentation selection
• Videos - WWDC video selection
• Settings - Configuration options

mock-ai-agent

A testing tool that simulates MCP client behavior:

mock-ai-agent search "SwiftUI navigation"
mock-ai-agent list-tools
mock-ai-agent --server /path/to/cupertino
mock-ai-agent --version  # New in v0.9.1

Arguments documented:

• <query> - Search query to execute
• --server - Path to MCP server binary

Useful for testing MCP servers without a full AI client.

cupertino-rel

The release automation tool (maintainer-only):

cupertino-rel bump patch          # Bump version
cupertino-rel tag --version 0.9.1 --push  # Create and push tag
cupertino-rel homebrew --version 0.9.1    # Update Homebrew formula
cupertino-rel databases --version 0.9.1   # Upload database release
cupertino-rel docs-update patch   # Documentation-only release
cupertino-rel full 0.10.0         # Complete release workflow

6 subcommands with all options documented:

• bump - Update version in all files
• tag - Create and push git tags
• homebrew - Update Homebrew formula
• databases - Upload databases to cupertino-docs
• docs-update - Documentation-only releases
• full - Complete release workflow

Documentation Structure

The documentation follows the same granular folder structure as the main CLI:

docs/binaries/
├── README.md
├── cupertino-tui/
│   ├── README.md
│   ├── option (--)/
│   │   └── version.md
│   └── view/
│       ├── dashboard.md
│       ├── packages.md
│       ├── archive.md
│       ├── videos.md
│       └── settings.md
├── mock-ai-agent/
│   ├── README.md
│   ├── option (--)/
│   │   ├── server.md
│   │   └── version.md
│   └── argument (<>)/
│       └── query.md
└── cupertino-rel/
    ├── README.md
    ├── option (--)/
    │   └── version.md
    └── subcommand/
        ├── bump/
        ├── tag/
        ├── homebrew/
        ├── databases/
        ├── docs-update/
        └── full/

No More Node.js (v0.8.3)

v0.8.3 removed the last Node.js dependency from the codebase.

The MCP integration tests previously used npm packages to simulate client behavior. Now they use cupertino serve directly:

@Test("Initialize handshake with cupertino server")
func cupertinoServerInitialize() async throws {
    let process = Process()
    process.executableURL = URL(fileURLWithPath: ".build/debug/cupertino")
    process.arguments = ["serve"]

    let stdinPipe = Pipe()
    let stdoutPipe = Pipe()
    process.standardInput = stdinPipe
    process.standardOutput = stdoutPipe

    try process.run()

    // Send initialize request (compact JSON + newline)
    let initRequest = """
    {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}\n
    """
    stdinPipe.fileHandleForWriting.write(Data(initRequest.utf8))

    // Parse and verify response
    let response = try JSONDecoder().decode(JSONRPCResponse.self, from: responseData)
    #expect(response.serverInfo.name == "cupertino")
}

The tests verify:

• MCP initialize handshake
• tools/list responses
• Protocol version negotiation
• Server info and tool registration

Swift-only tests. No npm. No node_modules. No package-lock.json.

This is now policy in AGENTS.md: no Node.js or npm in the Cupertino codebase.

Setup Progress Animation (v0.8.2)

Database downloads are ~400MB. Previously, cupertino setup showed nothing while downloading.

Now you get real-time feedback:

Download progress with bar:

⠹ [████████████░░░░░░░░░░░░░░░░░░] 42% (168MB/400MB)

Extraction spinner:

⠧ Extracting databases...

Implementation details:

• DownloadProgressDelegate implements URLSessionDownloadDelegate for real-time progress
• ExtractionSpinner shows animated feedback during unzip
• Extended download timeout to 10 minutes for large database files
• Uses ANSI escape codes for in-place updates

Small things that make the tool feel responsive.

Installer ANSI Fix (v0.8.1)

The one-line installer had broken ANSI colors:

Before:

\033[32m✓ Installation complete\033[0m

After:

✓ Installation complete  (in green)

Two echo statements were missing the -e flag for escape sequence interpretation. Fixed in #124.

Database Compatibility

This release uses the same database schema as v0.8.2. No migration needed.

When you run cupertino setup, it downloads databases from the v0.8.2 release. The CLI version (0.9.1) and database version (0.8.2) are now decoupled.

This means:

• CLI updates don’t require database re-downloads
• Database updates don’t require CLI updates
• Schema changes are tracked separately

Install or Update

# New install
brew install mihaelamj/tap/cupertino

# Update existing
brew update && brew upgrade cupertino

# Or one-line install
bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

Then:

cupertino setup  # Download databases (~30 seconds)
cupertino serve  # Start MCP server

Configure your AI tool using the guides above, and you’re ready.

Issues Closed

• #124 - Installer ANSI escape sequences
• #96 - Setup progress animation
• #131 - Remove Node.js dependency from MCP integration tests
• #130 - MCP protocol mismatch (2025-06-18 support)
• #134 - Better documentation for use with different agents
• #137 - Documentation improvements: MCP client configs and binary documentation

Links

• GitHub Repository
• Documentation
• Release Notes

TL;DR: SwiftSyntax-based AST indexing. Major codebase refactoring. Cleaner search results. Test suite grew from 93 to 698 tests.

This release is about foundations. Less visible features, more architectural work that makes everything else possible.

The Big Feature: AST Indexing

This is issue #81, and it’s been brewing for a while. Sample code search was purely keyword-based - you search “async”, you get files containing “async”. Comments, strings, documentation, actual code - all treated equally.

Now Cupertino extracts structured symbol data from Swift source:

// SwiftSourceExtractor analyzes this:
@MainActor
class NetworkManager: ObservableObject {
    @Published var isLoading = false

    func fetch() async throws -> Data { ... }
}

And extracts:

What This Enables

Better ranking, not magic. When you search “@Observable”, plain text search finds every file mentioning “Observable” - comments, strings, documentation, actual declarations. All ranked equally.

With AST indexing, Cupertino knows which results contain actual @Observable class declarations. These get boosted in ranking. The real symbol usages surface first.

$ cupertino search "@Observable" --source samples --format markdown

## Projects (5 found)

### 1. Migrating from the Observable Object protocol to the Observable macro
- **Frameworks:** swiftui
- **Files:** 14

## Matching Files

### Library.swift
> @Observable final class Library {
>     var books: [Book] = [Book(), Book(), Book()]
> }

### Book.swift
> @Observable final class Book: Identifiable {
>     var title = "Sample Book Title"
>     let id = UUID()
> }

The search still matches text, but files with actual @Observable declarations rank higher than files that just mention the word in comments.

Dedicated semantic tools. The symbol tables power these MCP tools:

• search_symbols - query by symbol type and attributes
• search_property_wrappers - find @Published, @State, @Binding usage
• search_conformances - find protocol implementations
• search_concurrency - find async/await patterns

These query extracted symbol data directly, not text. AI assistants can ask “find all async functions in SwiftUI samples” and get structured results.

How It Works

The new ASTIndexer package uses SwiftSyntax to parse Swift files and extract:

• Symbols: Classes, structs, enums, actors, protocols, functions
• Attributes: @MainActor, @Published, @Observable, etc.
• Conformances: Protocol adoptions
• Modifiers: async, throws, static, public

SwiftSyntax is Apple’s official Swift parser - the same one the compiler uses. No regex hacks, no fragile pattern matching.

The tradeoff? Build times. SwiftSyntax is a beast. First release build takes 10-15 minutes now. But the capability is worth it.

The Refactoring Story

This release involved substantial architectural changes that touch almost every part of the codebase. The goal: make search results cleaner and the system more capable.

Unified Search Service

Previously, each search source (docs, HIG, samples, videos) had its own formatting logic scattered across the codebase. Now there’s a unified SearchService that handles all sources consistently:

• Single entry point for all search types
• Consistent result formatting across sources
• Shared footer generation with tips and guidance
• Hierarchical numbering that works across all result types

Package Architecture Cleanup

The package structure got significant attention:

• Consolidated duplicate functionality across modules
• Clearer boundaries between Services, Core, and domain packages
• Better separation of CLI concerns from library logic
• Removed dead code paths and unused types

Result Formatter Protocol

A new ResultFormatter protocol standardizes how search results become output:

protocol ResultFormatter {
    associatedtype Input
    func format(_ result: Input) -> String
}

This enabled reusable formatters for different output contexts (CLI text, MCP markdown, JSON) while keeping the core search logic unchanged.

The refactoring wasn’t glamorous work, but it paid off immediately in cleaner search results and faster feature development.

Smarter Search Output

Here’s a subtle change that matters more than it sounds: hierarchical result numbering.

Before:

## Apple Documentation
### UIButton
### UIView
### UIControl

## Sample Code
### ButtonStyles
### CustomControls

After:

## 1. Apple Documentation (20)
### 1.1 UIButton
### 1.2 UIView
### 1.3 UIControl

## 2. Sample Code (5)
### 2.1 ButtonStyles
### 2.2 CustomControls

Why does this matter? When Claude is navigating search results, it can now reference specific items: “Looking at result 1.3…” or “Sample 2.1 shows this pattern…”

The count in headers (20, 5) also helps the AI understand result distribution. If one source has 50 results and another has 2, that’s useful context.

Small formatting changes, big impact on AI reasoning.

Display Bugs: Death by a Thousand Cuts

Sometimes bugs accumulate in strange ways. I noticed search results had weird formatting artifacts:

• Tabbars|AppleDeveloperDocumentation### - trailing garbage
• Tab bars - double spaces
• Goingfull screen - missing space in HIG titles
• Framework# SwiftUI - inline markdown headers

Each individually minor. Together, they made results look unprofessional and confused AI parsing.

The fix was a string extension that cleans display text:

var cleanedForDisplay: String {
    var result = self

    // Remove trailing ###
    while result.hasSuffix("###") { ... }

    // Remove |AppleDeveloperDocumentation
    result = result.replacingOccurrences(of: "|AppleDeveloperDocumentation", with: "")

    // Fix "Goingfull" -> "Going full"
    result = result.addingSpacesToCamelCase

    // Collapse double spaces
    while result.contains("  ") { ... }

    return result
}

Now there are 34 unit tests just for string formatting. Because every edge case that slipped through was a papercut in every search result.

The Test Suite Story

That’s not a typo. We went from 93 tests to 698.

Where did they come from?

1. AST Indexer tests - SwiftSyntax extraction needs thorough testing
2. String formatter tests - All those display edge cases
3. Service layer tests - Unified search service coverage
4. Symbol database tests - Integration tests for code analysis

The duration dropped despite 7x more tests because I fixed a race condition in the PriorityPackagesCatalog tests. The old code used defer { Task { await ... } } which created detached async tasks that didn’t complete before the next test ran. State leaked between tests, causing random failures.

The fix was embarrassingly simple: don’t use defer with async cleanup. Just await at the end of the test.

Doctor Command Gets Smarter

The cupertino doctor command now diagnoses package-related issues:

$ cupertino doctor

Cupertino v0.8.0 - Health Check

Databases:
  ✅ search.db (2.3GB, 302,424 docs)
  ✅ sample.db (156MB, 606 projects)

Package Status:
  ✅ User selections: ~/.cupertino/selected-packages.json (12 packages)
  ✅ Downloaded READMEs: 12/12
  ⚠️  Orphaned READMEs: 3 (packages no longer selected)

Priority Breakdown:
  📦 Apple Official: 31 packages
  📦 Ecosystem: 5 packages

MCP Tools: 8 registered
Resources: 3 providers active

The “orphaned READMEs” warning catches when you’ve unselected packages but their downloaded docs remain. Helpful for debugging unexpected search results.

What’s Next

The semantic tools (search_symbols, search_conformances, etc.) are built. Next steps:

1. Index all sample code - Run AST extraction across all 606 projects to populate symbol tables
2. Cross-referencing - Link extracted symbols to their documentation pages
3. Symbol coverage - Expand extraction to catch more edge cases

The infrastructure is in place. Now to fill the database and refine the queries.

Install or Update

# New install
brew install mihaelamj/tap/cupertino

# Update existing
brew upgrade cupertino

# Or one-line install
bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

Then:

cupertino setup  # Download databases (~30 seconds)
cupertino serve  # Start MCP server

Try the improved search:

# See hierarchical numbering
cupertino search "SwiftUI navigation" --source all

# Clean HIG results
cupertino search "tab bar" --source hig

# Check your installation health
cupertino doctor

Cupertino is an Apple Documentation MCP Server. 302,424 pages of Apple documentation, searchable by AI. Source at github.com/mihaelamj/cupertino.

TL;DR: Finally crawled all of Apple’s docs. Added OS version filtering. Made AI agents smarter about finding the right documentation.

Four days after v0.5.0, and I’ve shipped two more releases. At this point I’m not sure if this is momentum or obsession. Let’s call it momentum.

The Numbers

Three hundred thousand pages. That’s every framework, every class, every method Apple has documented. The crawl ran for almost two weeks total across multiple sessions.

Top Frameworks by Document Count

Kernel jumped from 25,000 to nearly 40,000 pages. That’s IOKit, BSD interfaces, Mach APIs, driver development - the low-level stuff that’s hardest to find and most valuable when you need it. Matter has 24,000+ docs for smart home development. Accelerate and SIMD documentation is fully indexed now - performance optimization guides that AI models probably didn’t see much of during training.

The Feature I’ve Been Waiting For: OS Version Filtering

This was issue #99, and it’s been on my mind since day one. Apple’s documentation includes version information - which iOS/macOS version introduced each API. We now extract this.

cupertino search "async" --min-ios 16

Or in Claude:

“Search for SwiftUI navigation APIs available in iOS 17+”

The AI agent can now filter results by platform version. No more suggestions for deprecated iOS 12 APIs when you’re building for iOS 17.

How It Works

Different documentation sources need different strategies:

For Apple’s modern docs, there’s a hidden JSON endpoint at /tutorials/data/documentation/ that returns structured metadata including availability. For older stuff, we derive from the framework - if it’s UIKit, we know the minimum versions.

The cool part? You can filter by any platform:

• --min-ios 16
• --min-macos 14
• --min-tvos 17
• --min-watchos 10
• --min-visionos 1

visionOS filtering. For when you’re building spatial computing apps and need APIs that actually exist on the platform.

Teaching AI Where to Look

Here’s something I discovered while using Cupertino with Claude: the AI doesn’t know what it doesn’t know.

When Claude searches for “CALayer animation”, it gets API reference - classes, methods, properties. Good stuff. But the conceptual documentation - the “why” behind Core Animation - lives in Apple Archive. And Claude had no idea.

The Problem

I had added archive support in v0.2.3. Users could search with --source apple-archive. But AI agents don’t read release notes. They read tool descriptions once, then forget. Every search was missing the deep conceptual guides.

The Solution: Teasers

Now every search result includes hints from alternate sources:

# Search Results for "CALayer animation"

## Results from apple-docs (5 found)

1. **CALayer** - The basic object for managing and presenting drawable content...
2. **CABasicAnimation** - An animation that applies a single keyframe...

---

**Other sources to explore:**

- **apple-archive**: 3 results (Core Animation Programming Guide, Animation Types...)
- **samples**: 2 results (LayerPlayer, AnimationExplorer)
- **swift-evolution**: 1 result (SE-0421: Generalize async sequence...)

Use `source` parameter to search: apple-archive, samples, hig, swift-evolution...

Every search response is now a teaching moment. Claude sees there are archive guides available. It sees sample code exists. It learns in context how to dig deeper.

Human Interface Guidelines: Design Docs for AI

Here’s something I didn’t expect to matter as much as it does: HIG support.

Apple’s Human Interface Guidelines aren’t just for designers. When Claude is helping you build a button, a navigation pattern, or a settings screen, it should know Apple’s design recommendations - not just the API.

cupertino search "buttons" --source hig

Now when you ask “what’s the recommended button style for destructive actions?”, Claude can actually look it up instead of guessing. Platform-specific guidance for iOS, macOS, watchOS, visionOS - all searchable.

The HIG docs are marked as “universal” for availability - they apply across all OS versions. Design principles don’t deprecate like APIs do.

One Tool to Rule Them All

Speaking of simplification - I consolidated the search tools.

Before v0.7.0:

• search_docs - Apple documentation
• search_hig - Human Interface Guidelines
• search_samples - Sample code
• …and more

Now:

• search - Everything, with a source parameter

# CLI
cupertino search "buttons" --source hig
cupertino search "networking" --source samples
cupertino search "actors" --source swift-evolution
cupertino search "everything" --source all

One tool, eight sources, cleaner mental model. The source parameter accepts:

• apple-docs (default) - API reference
• samples - Working code examples
• hig - Design guidelines
• apple-archive - Legacy conceptual guides
• swift-evolution - Language proposals
• swift-org - Swift.org documentation
• swift-book - The Swift Programming Language
• packages - Swift package docs
• all (searches everything)

The all option is surprisingly useful. When you’re not sure where something lives, just search everywhere.

What I Learned

Building for AI is different than building for humans.

Humans read documentation. They explore. They remember “oh yeah, there’s an archive section I should check.” AI agents don’t work that way. They have tool descriptions and search results. That’s it.

The best way to teach an AI agent? Put the lesson in every response it sees. Not in documentation it reads once. Not in tool descriptions it might forget. In the actual output, every single time.

That’s why teasers matter. That’s why source-aware messaging matters. Every search result is documentation.

The Road Ahead

With 302,424 pages indexed and version filtering working, the foundation is solid. What’s next:

1. Semantic code search - Search sample code by what it does, not just keywords
2. Framework relationships - Search UIKit, get relevant Foundation results too
3. Smarter ranking - Weight results by your target platform

The crawl is complete. The curation continues.

Install or Update

# New install
brew install mihaelamj/tap/cupertino

# Update existing
brew upgrade cupertino

# Or one-line install
bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

Then:

cupertino setup  # Download 2.3GB database (~30 seconds)
cupertino serve  # Start MCP server

Try the new features:

# Filter by OS version
cupertino search "SwiftUI navigation" --min-ios 17

# Search design guidelines
cupertino search "buttons destructive" --source hig

# Search legacy conceptual guides
cupertino search "Core Animation" --source apple-archive

# Search everything at once
cupertino search "async await" --source all

Cupertino is an Apple Documentation MCP Server. 302,424 pages of Apple documentation, searchable by AI. Source at github.com/mihaelamj/cupertino.

TL;DR: Documentation database nearly doubled. New release tooling. A roadmap for what’s next.

Two days after v0.4.0, we’re shipping v0.5.0. Why so fast? Because I finally finished a 5-day deep crawl of Apple’s documentation.

The Numbers

The crawl ran for 5 days because I wanted everything. Every framework, every page, every deprecated API. The result: nearly 100,000 more documents than before.

Top Frameworks by Document Count

1. Kernel - 24,747 docs
2. Matter - 22,013 docs
3. Swift - 17,466 docs
4. Foundation - 14,892 docs
5. UIKit - 12,341 docs

Kernel documentation alone has almost 25,000 pages. That’s IOKit, BSD interfaces, Mach APIs - the stuff that’s usually impossible to find.

What This Means for AI

When Claude searches Cupertino now, it has access to:

• Low-level APIs - Kernel programming, IOKit drivers, Mach ports
• Hardware interfaces - Matter protocol (24k+ docs for smart home development)
• Complete Swift coverage - Every proposal, every standard library type
• Obscure frameworks - The ones you forget exist until you need them

This is deterministic access to Apple’s documentation. No hallucination, no guessing from training data. Just the actual docs.

Why I Built Release Automation

I remember the release oopsie from v0.4.0 like it was just a few days ago. Wait, it was just a few days ago. 😅 I tagged before committing the version bump, had to delete tags, rebuild everything, update SHA256 checksums twice…

Almost happened again with v0.5.0. Caught it in time, but the close call was enough.

So I finally wrote the automation I’d been putting off. Not because users need it - they don’t. But because I was losing hours to release mechanics instead of building features.

The release process now touches 4 repositories (main repo, cupertino-docs for databases, Homebrew tap, and the blog). Miss one step, wrong order, typo in a version number - and you’re starting over.

Now it’s one command. I run it, go make coffee, come back to a published release. That’s the dream, anyway. We’ll see how v0.6.0 goes.

The Roadmap

The full roadmap is tracked in the Cupertino Roadmap GitHub project. Here’s what’s coming next, in dependency order:

Phase 1: Complete the Crawl (#88)

The crawl is extensive but not complete. Some frameworks have deep hierarchies that weren’t fully traversed. The goal is 100% coverage of Apple’s public documentation.

Status: In progress. Currently at depth level 8. No idea when it finishes - some frameworks go deep.

Phase 2: Prune the Database (#87)

Once we have everything, we need to clean it up. The database has:

• Duplicate entries (same doc indexed multiple times)
• Misclassified documents (wrong framework attribution)
• Orphaned entries from URL changes

This is blocked by #88 - no point pruning until the crawl is complete.

Phase 3: API Version Tracking (#99)

This is the big one. Apple’s documentation includes version information - which iOS/macOS version introduced each API. We can extract this.

Imagine searching with:

cupertino search "async" --min-os ios16

Or having Claude automatically filter out deprecated APIs when you’re targeting iOS 17+.

I’ve been investigating Apple’s /tutorials/data/documentation/ endpoint. It returns JSON with version metadata for most frameworks. Some older frameworks (Kernel, IOKit) don’t have it, but the coverage is good.

Status: Research complete. Implementation pending.

Phase 4: Version-Filtered Search (#100)

Once we have version data in the database, we can expose it as a search filter. Both CLI and MCP tool would support filtering by minimum OS version.

Blocked by: #99 (need the data first)

Phase 5: Semantic Code Search (#81)

The end goal: search sample code by what it does, not just by keyword.

cupertino search "async image loading with caching"

This requires:

1. Complete documentation (#88)
2. Clean database (#87)
3. SwiftSyntax AST indexing of sample code

It’s ambitious, but the foundation is being laid with each release.

Install or Update

# New install
brew install mihaelamj/tap/cupertino

# Update
brew upgrade cupertino

# Or instant setup
bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

After installing, databases download automatically:

cupertino setup

Takes about 30 seconds to download the pre-built 1.9GB database.

The Vision: Human-Curated Developer Docs

Here’s what I’ve learned: having all the docs isn’t enough. We need them in context.

When you’re building an app targeting iOS 15+, you don’t want to see iOS 12 APIs. When you’re learning Core Animation, you want the conceptual guides from Apple Archive, not just the API reference. When you’re debugging a Matter integration, you need the 22,000 Matter docs filtered to what’s actually relevant.

Raw documentation is noise. Curated documentation is signal.

That’s where Cupertino is heading. Not just “here’s 234,331 docs” but “here’s what you actually need for your specific context.” Version filtering is coming - ask for iOS 16+ APIs only. Source awareness is coming - archive guides surfaced alongside modern reference. Framework relationships are coming - search UIKit and get relevant Foundation results too.

The crawl is the foundation. The curation is the value.

234,331 documents today. Context-aware, version-filtered, human-curated search tomorrow.

Cupertino is an Apple Documentation MCP Server. Install with brew install mihaelamj/tap/cupertino. Source at github.com/mihaelamj/cupertino.

TL;DR: Human Interface Guidelines support, smarter framework search, and a hard lesson about release engineering.

Why jump from 0.3.4 to 0.4.0? Five issues closed: HIG support (#69), framework aliases (#91, #92), and Swift.org fixes (#93, #94). Enough new functionality to warrant a minor version bump.

What’s New

Human Interface Guidelines Support

Cupertino can now crawl and index Apple’s Human Interface Guidelines:

cupertino fetch --type hig

There’s also a new search_hig MCP tool that lets AI agents search design guidelines with platform and category filters. When you ask Claude “what are Apple’s recommendations for buttons?”, it can actually look it up instead of guessing from training data.

Everything available via MCP tools is also available via command line:

cupertino search "buttons" --source hig

This is something people might not realize: you can query Cupertino the same way AI does. Every MCP tool has a CLI equivalent. Want to see exactly what Claude sees when it searches? Run the same query yourself. Useful for testing, debugging, or when you just want quick answers without a conversation.

Framework Aliases

Before, searching for “Core Animation” might not find results indexed under “QuartzCore” (the actual import name). Now there are 249 framework aliases in the database:

• QuartzCore ↔ CoreAnimation ↔ Core Animation
• CoreGraphics ↔ Quartz2D ↔ Quartz 2D

Search works regardless of which name variant you use.

Swift.org Fixes

The Swift.org crawler was broken. The base URL had changed from docs.swift.org to www.swift.org/documentation/, and the indexer was looking for .md files when the crawler was saving .json files. Fixed.

Why This Matters

Here’s a real example from today. I asked Claude about Apple’s Foundation Models framework - the new on-device ML APIs. Claude’s response:

“The MCP server pulls the complete Foundation Models sample code documentation - straight from Apple’s current docs. No hallucinated API names!”

More examples of documentation you can search:

• FoundationModels - Apple’s new on-device ML framework
• Writing Tools - System-wide AI writing assistance
• Genmoji - Custom emoji generation
• Image Playground - On-device image generation

This is also why Cupertino needs a human touch - it can’t be fully automated. Someone has to notice when Apple adds new frameworks, when URLs change (like Swift.org did), when documentation structures shift. The crawler is automated, but the awareness isn’t.

That’s the whole point: deterministic, up-to-date docs instead of training data guesses.

Token Efficiency

A side benefit: Cupertino is more token-efficient than you’d expect.

Yes, tool results use tokens - documentation goes into context. But:

• Accurate = fewer turns - No hallucination means no correction loop
• Curated content - Returns exactly what’s needed, not web search noise
• Local search is free - No API cost for the search operation itself
• Truncated summaries - Results are summarized; full doc only when you call read_document

So not zero tokens, but more efficient token use. And no external API costs for search.

The Archive Discovery Problem

Here’s something interesting I discovered while testing. When Claude searched for “CALayer animation”, it got API reference pages - classes, methods, properties. Claude wanted to dig deeper:

“Let me try a more targeted search - something like the layer tree architecture or model/presentation layers that would be covered in the Core Animation Programming Guide.”

Then I suggested searching with source: "apple-archive". Claude’s reaction:

“Now THAT’s the difference! When searching with source: apple-archive, we get the Core Animation Programming Guide and the Animation Types and Timing Programming Guide - the real meat.”

The conceptual deep-dives that explain why things work the way they do.

Modern Apple docs = API reference (the what)
Archive docs = Conceptual guides (the why)

The problem? AI agents don’t know to search the archive. It’s an opt-in parameter buried in the tool description.

The Solution: Auto-Surface Archive Teasers

I’m planning to modify search results to automatically hint at archive content:

# Search Results for "CALayer animation"

## Modern Documentation
[1] CALayer - API reference...
[2] CABasicAnimation - API reference...

---

## 📚 Related Archive Guides

**Core Animation Programming Guide** - Layer geometry, animation timing...

> For full archive content, search with `source: "apple-archive"`

This way:

• Modern docs still come first
• AI agents always see archive exists
• They learn how to get more, in context

Only show the archive section if there are relevant results. Same principle could apply to sample code, Swift packages, or any other source.

The Release Process Disaster

Here’s where it gets interesting. I had all the code ready, all the tests passing, and I was ready to ship.

The process seemed simple:

1. Bump version in Constants.swift
2. Update README.md and CHANGELOG.md
3. Create git tag
4. Push tag (triggers GitHub Actions build)
5. Upload databases to cupertino-docs
6. Update Homebrew formula

What could go wrong?

The Tag Timing Problem

I merged my feature branch, created the tag, pushed it… and then realized I hadn’t committed the version bump to main yet. The tag pointed to a commit where Constants.swift still said 0.3.5.

GitHub Actions dutifully built a beautiful, signed, notarized universal binary… that reported version 0.3.5.

$ cupertino --version
0.3.5

When users ran cupertino setup, it tried to download databases from v0.3.5 instead of v0.4.0. Everything was broken.

The Fix

I had to:

1. Delete the tag on GitHub
2. Delete the local tag
3. Make sure the version bump commit was pushed to main
4. Verify the built binary reports correct version before tagging
5. Recreate the tag
6. Wait for GitHub Actions to rebuild
7. Update the Homebrew formula with the new SHA256

The SHA256 Dance

When I first updated the Homebrew formula, I grabbed the SHA256 from the old (broken) binary. After rebuilding, the checksum changed. Users got:

Error: Formula reports different checksum: cf035352...
SHA-256 checksum of downloaded file: 5c5cf7ab...

Another round of updating the tap.

The 11-Step Release Process

After today’s adventures, here’s what the release process actually looks like:

1. Update version in Constants.swift, README.md, CHANGELOG.md
2. Commit and push to main
3. Build locally and verify --version matches
4. Create and push tag
5. Wait for GitHub Actions (~5 min)
6. Create GitHub release with notes
7. Build locally and install
8. Upload databases with cupertino release
9. Get new SHA256 from release
10. Update Homebrew tap formula
11. Verify on fresh machine

That’s 11 steps across 4 repositories. Miss one, and you’re rebuilding everything.

Time for Automation?

I’m seriously considering writing a release script. Swift or Bash?

The pragmatic choice is Bash - it’s just orchestrating CLI commands. But I’m a Swift purist. The cupertino release command already handles database uploads with proper GitHub API integration. Extending it to handle the full workflow feels right.

Something like cupertino release --full that:

1. Checks for uncommitted changes
2. Verifies version consistency
3. Builds and validates --version
4. Creates and pushes the tag
5. Waits for GitHub Actions
6. Uploads databases
7. Updates the Homebrew tap

One command. No mistakes. Written in Swift.

Lessons Learned

1. Order matters. Commit the version bump before creating the tag.
2. Verify before you ship. Build locally and check --version before tagging.
3. Document your release process. I now have a detailed DEPLOYMENT.md with warnings.
4. Automate what hurts. If you make the same mistake twice, write a script.

What’s Next

• Enhanced search results - Auto-surface archive, samples, packages in every search (high priority)
• Release automation - cupertino release --full in Swift
• Fix setup animations - They’re broken
• Keep crawling - Fresh docs matter

This release taught me a lot. Not just about release engineering, but about how AI agents actually use documentation. The archive discovery problem was a surprise - valuable content hidden behind an opt-in flag that agents don’t know to use.

Building tools for AI is different. You’re not just building for humans who read documentation. You’re building for agents that learn from tool descriptions and in-context hints.

Key discovery: Claude reads tool descriptions once, but reads search results every time. If you want agents to use a feature, put it in the output - not buried in documentation they’ll forget. Every search result is a teaching moment.

Next up: implementing enhanced search results. Once that ships, every search will auto-surface relevant content from archives, samples, and packages - with the exact commands to dig deeper. No more hidden treasure.

Cupertino is an Apple Documentation MCP Server. Install with brew install mihaelamj/tap/cupertino. Check it out at github.com/mihaelamj/cupertino.

TL;DR: One command installs everything. Homebrew is also available.

bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

What Changed

In v0.3.0, I introduced cupertino setup to download pre-built databases. But you still had to clone the repo and build from source first. That’s two steps too many.

Now it’s one line:

bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

This:

1. Downloads a pre-built universal binary (arm64 + x86_64)
2. Installs to /usr/local/bin
3. Downloads documentation databases (~230 MB)

Total time: under a minute.

Signed and Notarized

Getting a command-line tool to “just work” on macOS is harder than it sounds. Without proper signing, users see scary “unidentified developer” warnings. Without notarization, Gatekeeper blocks execution entirely.

The release workflow now handles this automatically:

1. GitHub Actions builds a universal binary (arm64 + x86_64) on every release tag
2. Developer ID signing with my Apple Developer certificate
3. Apple notarization submits to Apple’s servers for malware scanning
4. Preserved signatures using ditto instead of cp to maintain code signing through the install process

The result: download, install, run. No security dialogs. No right-click workarounds. No “are you sure?” prompts.

This took several iterations to get right—the signing must happen in CI, notarization requires waiting for Apple’s servers, and even copying the file wrong can strip the signature. But now it’s automated and works every time.

Homebrew Support

Prefer Homebrew? Now available:

brew tap mihaelamj/tap
brew install cupertino
cupertino setup

Three lines instead of one, but integrates with your existing Homebrew workflow.

150,000+ Apple Documentation Pages

The database has grown significantly:

More coverage means better search results for your AI assistant.

Demo Video

Watch the one-line install and Claude Desktop in action:

Three Install Methods

1. One-Line Install (Recommended)

bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

Downloads binary and databases. Ready in under a minute.

2. Homebrew

brew tap mihaelamj/tap
brew install cupertino
cupertino setup

Integrates with Homebrew for updates via brew upgrade cupertino.

3. Build from Source

git clone https://github.com/mihaelamj/cupertino.git
cd cupertino && make build && sudo make install
cupertino setup

For those who want to inspect or modify the code.

What’s Inside

After installation, you have:

• /usr/local/bin/cupertino - The MCP server binary
• ~/.cupertino/search.db - 150K+ documentation pages
• ~/.cupertino/samples.db - 606 sample projects, 18K+ source files

Start the server and configure Claude Desktop:

cupertino serve

{
  "mcpServers": {
    "cupertino": {
      "command": "/usr/local/bin/cupertino"
    }
  }
}

Registry Submissions

I’ve submitted Cupertino to the major MCP server registries:

• mcpservers.org
• PulseMCP
• awesome-mcp-servers

These directories help developers discover MCP servers—getting listed would bring more visibility to the Apple developer community.

Links

• GitHub: github.com/mihaelamj/cupertino
• Homebrew Tap: github.com/mihaelamj/homebrew-tap
• Demo Video: YouTube

The best install experience is no install experience. One line is close enough.

TL;DR: cupertino setup now downloads pre-built databases in ~30 seconds. No more 20-hour crawls.

The Problem With v0.2.x

When I released Cupertino, the setup process looked like this:

cupertino fetch --type docs --max-pages 15000  # ~20-24 hours
cupertino fetch --type evolution               # ~5 minutes
cupertino save                                 # ~5 minutes

Twenty hours. To respect Apple’s servers, the crawler waits 0.5 seconds between requests. 21,000 pages × 0.5s = a very long initial setup.

Users loved the tool but hated the onboarding. Fair.

The Solution: Pre-built Databases

Instead of everyone crawling Apple’s documentation independently, I now publish pre-built databases on GitHub Releases. The new setup flow:

cupertino setup   # ~30 seconds
cupertino serve   # Start MCP server

That’s it. Two commands. Under a minute.

How It Works

For Users

The setup command downloads a zip file from GitHub Releases containing:

• search.db (~1.1 GB) - 138,000+ documentation pages
• samples.db (~183 MB) - 606 sample projects, 18,000+ source files

$ cupertino setup

📦 Cupertino Setup

⬇️  Downloading Databases...
   ⠹ [████████████████░░░░░░░░░░░░░░]  53% (121.0 MB/228.1 MB)
   ✓ Databases (228.1 MB)
📂 Extracting databases...
   ✓ Extracted

✅ Setup complete!
   Documentation: /Users/you/.cupertino/search.db
   Sample code:   /Users/you/.cupertino/samples.db

💡 Start the server with: cupertino serve

If databases already exist, it skips the download:

$ cupertino setup

📦 Cupertino Setup

✅ Databases already exist
   Documentation: /Users/you/.cupertino/search.db
   Sample code:   /Users/you/.cupertino/samples.db

💡 Use --force to overwrite with latest version
💡 Start the server with: cupertino serve

For Me (Maintainer)

A new release command automates publishing:

$ cupertino release

📦 Cupertino Release v0.3.0

📊 Database sizes:
   search.db:  1.2 GB
   samples.db: 192.2 MB

📁 Creating cupertino-databases-v0.3.0.zip...
   ✓ Created (228.3 MB)

🔐 Calculating SHA256...
   17dac4b84adaa04b5f976a7d1b9126630545f0101fe84ca5423163da886386a6

🚀 Creating release v0.3.0...
   ✓ Release created

⬆️  Uploading cupertino-databases-v0.3.0.zip...
   ✓ Upload complete

✅ Release v0.3.0 published!
   https://github.com/mihaelamj/cupertino-docs/releases/tag/v0.3.0

When I refresh the documentation (re-crawl Apple’s docs), I bump the version and run cupertino release. Users get the update with cupertino setup --force.

Version Parity

The CLI version matches the database release tag:

This ensures schema compatibility. If I change the database structure in v0.4.0, users with CLI v0.4.0 will download v0.4.0 databases.

Three Ways to Set Up Cupertino

Now you have options:

1. Instant Setup (Recommended)

cupertino setup    # ~30 seconds
cupertino serve

Download pre-built databases. Fastest option.

2. Build from GitHub

cupertino save --remote    # ~45 minutes
cupertino serve

Stream documentation from GitHub and build locally. Useful if you want to verify the build process or can’t download the 228MB zip.

3. Full Crawl (Advanced)

cupertino fetch --type docs --max-pages 15000    # ~20-24 hours
cupertino fetch --type evolution
cupertino save
cupertino serve

Crawl Apple’s documentation yourself. Only needed if you want to modify the crawler or need documentation not in the pre-built database.

Compression Matters

The uncompressed databases total ~1.3 GB. The zip file is 228 MB - about 1/6 the size. SQLite databases compress extremely well because they contain repetitive text data.

This makes the download fast and keeps GitHub Release storage reasonable.

Database Updates

I’m actively crawling Apple’s documentation and updating the databases several times a week. Run cupertino setup --force to get the latest version.

The documentation is hosted in two public repositories:

• cupertino-docs - Pre-crawled documentation and database releases
• cupertino-sample-code - 606 Apple sample code projects

What’s Next

• Automatic updates - Check for new database versions on startup
• Delta updates - Download only changed documents instead of full database
• More documentation sources - WWDC transcripts, Apple Tech Notes

Try It

# Install
git clone https://github.com/mihaelamj/cupertino.git
cd cupertino && make build && sudo make install

# Setup (the new way)
cupertino setup
cupertino serve

Configure Claude Desktop and you’re done. Full Apple documentation access in under a minute.

Links

• GitHub: github.com/mihaelamj/cupertino
• Release: v0.3.0
• Databases: cupertino-docs releases

The best feature is the one that removes friction. Twenty hours of crawling was friction.

I’m not alone. Developers everywhere report the same issues: AI suggesting @ObservableObject and @Published when Apple now recommends @Observable. Xcode 26’s AI integration hallucinating 100% of the time when asked about new 2025 frameworks. One developer described fixing AI-generated Swift code as “whack-a-mole”—fix one obsolete API, another pops up.

That frustration is why I built Cupertino.

In my previous post, I introduced it—an MCP server that gives Claude offline access to 22,000+ Apple documentation pages. That was version 0.1.x. Since then, things have evolved rapidly: nine releases in 72 hours, two new companion repositories, and a complete ecosystem for AI-assisted Apple development.

I need this tool. I use it every day. And I’m building it in public because I know I’m not the only one frustrated with AI that hallucinates Apple APIs.

What Changed: v0.1.6 → v0.2.3

The original Cupertino solved the core problem—searching Apple docs locally. But real-world usage revealed gaps: ranking wasn’t smart enough, storage was bloated, and legacy documentation was missing. Here’s what shipped:

Intelligent Ranking (v0.2.1)

The initial BM25 search treated all documents equally. A query for “View” might return some random extension before SwiftUI.View itself. Eight ranking heuristics now prioritize:

• Core types over extensions - View ranks above View+Accessibility
• URL depth analysis - /documentation/swiftui/view beats /documentation/swiftui/view/some/nested/thing
• Title pattern detection - Exact matches surface first
• Modern over deprecated - Current APIs rank higher

The result: sub-100ms queries that actually return what you’re looking for.

Storage Cleanup (v0.1.8, v0.2.0)

The initial crawl produced ~27GB of data. Most of it was cruft: .git folders from sample code downloads, .DS_Store files, Xcode user data. A new cleanup command reduced storage to 2-3GB—a 90% reduction.

Version 0.2.0 fixed a critical bug where cleanup was accidentally deleting source code instead of just metadata. Now 99.8% of sample ZIPs retain intact source.

Language Filtering (v0.1.9)

Not everyone wants Objective-C results. The CLI and MCP tools now accept a language parameter:

cupertino search "NSObject" --language swift

Claude can filter too—just ask for “Swift-only results.”

Apple Archive Support (v0.2.3)

Apple’s modern documentation is great, but some topics only exist in the legacy archive: Core Animation Programming Guide, Quartz 2D Programming Guide, Core Text Programming Guide. These are still the authoritative sources for low-level graphics work.

Cupertino now crawls developer.apple.com/library/archive/ and integrates results with smart ranking that prioritizes modern docs while keeping legacy content searchable.

The Ecosystem: Three Repositories

Cupertino grew from one repo to three:

cupertino — The MCP Server

The main Swift package. Crawls, indexes, and serves documentation via MCP protocol. Install it, point Claude at it, done.

# Quick setup with Claude Code
claude mcp add cupertino --scope user -- /usr/local/bin/cupertino

cupertino-docs — Pre-Crawled Documentation

Don’t want to crawl everything yourself? Clone this repo:

git clone https://github.com/mihaelamj/cupertino-docs ~/.cupertino

Currently includes:

Swift Evolution, Swift.org, and package docs are pre-indexed and ready. Apple Developer Documentation and Archive still require running cupertino fetch yourself due to size—but having the infrastructure in place is a start. The tooling exists; full pre-crawled distribution is coming.

cupertino-sample-code — 606 Apple Samples

This is the fun one. Every official Apple sample code project, cleaned and ready to build:

• 100+ frameworks covered: SwiftUI, ARKit, RealityKit, Metal, CoreML, Vision, AVFoundation, HealthKit, HomeKit, and more
• 606 projects: From “Hello World” to complex GPU shaders
• Build-ready: No .git folders, no xcuserdata, no cruft
• MIT Licensed: Use them however you want

When you ask Claude “show me how Apple implements ARKit face tracking,” it can now search actual Apple sample code—not hallucinate an approximation.

Example projects include:

• arkit-* — Augmented reality implementations
• swiftui-* — Modern UI patterns
• metal-* — GPU programming examples
• coreml-* — Machine learning integrations
• avfoundation-* — Video and audio capture

The 72-Hour Sprint

Nine releases shipped in three days. Here’s the changelog:

Each release addressed real issues discovered while using Cupertino with Claude Code. Fast iteration, real-world testing.

Using the Full Ecosystem

Here’s the quickest path to AI-assisted Apple development with accurate documentation:

# 1. Get pre-crawled docs (skip the 20-hour crawl)
git clone https://github.com/mihaelamj/cupertino-docs ~/.cupertino

# 2. Build the MCP server
git clone https://github.com/mihaelamj/cupertino
cd cupertino
swift build -c release
sudo cp .build/release/cupertino /usr/local/bin/

# 3. Configure Claude Code
claude mcp add cupertino --scope user -- /usr/local/bin/cupertino

# 4. (Optional) Get sample code for reference
git clone https://github.com/mihaelamj/cupertino-sample-code ~/Apple-Samples

Now when you ask Claude about Apple APIs, it searches 22,000+ pages of real documentation. No hallucinations. No deprecated patterns. Just accurate, current information.

What’s Next

The ranking heuristics work well but aren’t perfect. Planned improvements:

• make install — One command to install everything: the MCP server, pre-crawled docs from cupertino-docs, and sample code from cupertino-sample-code
• Semantic search — Embeddings-based similarity for conceptual queries
• Version awareness — Filter by iOS/macOS version
• Cross-reference linking — “See also” connections between related docs
• Sample code search — Full-text search across all 606 projects

Join Me

If you’re an Apple developer tired of AI hallucinations, give Cupertino a try. If you find bugs or have ideas, open an issue—27 closed so far, plenty more to go.

This isn’t a polished product yet. It’s a tool I’m building because I need it, and I’m sharing it because you might need it too.

Repositories

• cupertino — MCP Server (Swift)
• cupertino-docs — Pre-crawled documentation
• cupertino-sample-code — 606 Apple samples (MIT)

No more AI hallucinations about Apple APIs. Just real documentation that compiles.

TL;DR: I built an MCP server that gives Claude Desktop offline access to 22,000+ Apple documentation pages across 261 frameworks. No more hallucinated APIs.

The Problem

If you’ve used Claude or ChatGPT for Swift/iOS development, you’ve seen this:

“Use the NavigationView with .navigationBarTitle() modifier…”

Except NavigationView is deprecated. It’s NavigationStack now. And the modifier is .navigationTitle().

AI models hallucinate APIs. They mix up iOS 14 patterns with iOS 17. They invent methods that don’t exist. And when you’re deep in a coding session, these small errors cost you hours.

The Solution: Cupertino

Cupertino is an MCP (Model Context Protocol) server that:

1. Crawls Apple Developer documentation, Swift Evolution proposals, and Swift.org
2. Indexes everything into a local SQLite FTS5 database with BM25 ranking
3. Serves documentation to Claude Desktop via MCP

When Claude needs to answer a SwiftUI question, it searches your local documentation instead of relying on training data.

What You Get

22,044 documents across 223 frameworks:

The documentation index contains 22,044 documents across 223 frameworks, including all major Apple platforms.

Two MCP tools:

• search_docs - Full-text search with BM25 ranking
• list_frameworks - Discover available documentation

Example search result:

# Search Results for "SwiftUI View"

## 1. View | Apple Developer Documentation
- **Framework:** swiftui
- **URI:** apple-docs://swiftui/documentation_swiftui_view
- **Score:** 1.82
- **Words:** 2,682

Protocol# View
A type that represents part of your app's user interface...

Claude Desktop using Cupertino’s MCP tools to search documentation and list available frameworks

Installation

1. Build from source

git clone https://github.com/mihaelamj/cupertino.git
cd cupertino
make build
sudo make install

2. Fetch documentation

# Quick start: Swift Evolution only (~5 minutes)
cupertino fetch --type evolution
cupertino save

# Full documentation (~20-24 hours, one-time)
cupertino fetch --type docs --max-pages 15000
cupertino fetch --type evolution
cupertino save

Expected output after indexing:

✅ Search index built successfully!
   Total documents: 22044
   Frameworks: 261
   Database: /Users/mm/.cupertino/search.db
   Size: 163.6 MB

💡 Tip: Start the MCP server with 'cupertino serve' to enable search

Why 20+ hours? The crawler respects Apple’s servers with a 0.5s delay between requests. 21,000 pages × 0.5s = many hours. But it’s a one-time operation.

3. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cupertino": {
      "command": "/usr/local/bin/cupertino"
    }
  }
}

Restart Claude Desktop. Done.

4. Verify it works

cupertino doctor

✅ MCP Server
   ✓ Server can initialize
   ✓ Transport: stdio
   ✓ Protocol version: 2024-11-05

📚 Documentation Directories
   ✓ Apple docs: ~/.cupertino/docs (21,114 files)
   ✓ Swift Evolution: ~/.cupertino/swift-evolution (429 proposals)

🔍 Search Index
   ✓ Database: ~/.cupertino/search.db
   ✓ Size: 156.0 MB
   ✓ Frameworks: 261

✅ All checks passed - MCP server ready

How It Works

1. Fetch:  cupertino fetch --type docs
   → WKWebView renders JavaScript-heavy pages
   → HTML converted to Markdown
   → Saved to ~/.cupertino/docs/

2. Save:   cupertino save
   → Markdown files indexed into SQLite FTS5
   → BM25 ranking for relevance scoring
   → ~160MB database for full index

3. Serve:  cupertino serve
   → MCP server starts on stdio
   → Claude Desktop connects via JSON-RPC
   → Search queries hit local database

Architecture

Built with Swift 6.2 and strict concurrency:

Packages/
├── MCP/                 # Model Context Protocol implementation
├── Search/              # SQLite FTS5 search engine
├── Core/                # Crawlers (WKWebView, GitHub API)
├── CLI/                 # Command-line interface
└── Resources/           # Bundled catalogs (9,699 packages, 606 samples)

Key decisions:

• Swift 6.2 with 100% strict concurrency checking
• Actor isolation for thread-safe state management
• SQLite FTS5 with BM25 for fast, relevant search
• WKWebView to render Apple’s JavaScript-heavy documentation

Room for Improvement

Honest feedback from testing: the search works, but it’s not perfect.

Current limitation: BM25 treats all documents equally. A search for “SwiftUI” returns mouseEntered(with:) alongside View protocol because both contain “SwiftUI” with similar frequency.

Planned improvements:

1. Boost by word count - Comprehensive docs (2000+ words) rank higher than stub pages (61 words)
2. Boost by path depth - /swiftui/view ranks higher than /swiftui/nshostingview/mouseentered
3. Document type weighting - Overview pages rank higher than individual method docs
4. Curated importance flags - Mark foundational docs for priority ranking

The search is still useful for targeted queries like “SwiftUI NavigationStack” or “SE-0001”. Broad queries need work.

Why I Built This

I was tired of:

• Claude inventing deprecated APIs
• Switching to Safari to verify every code suggestion
• Losing flow state to documentation lookups

Now Claude searches my local 160MB documentation database. Same query, same results, every time. Offline. Fast.

Links

• GitHub: github.com/mihaelamj/cupertino
• Requirements: macOS 15+, Swift 6.2+, Xcode 16+
• License: MIT

Built with Swift, frustration, and too many hours debugging WKWebView concurrency issues.

The Problem

When working with OpenAPI Runtime in Swift, you often need to:

• Inject an Authorization: Bearer <token> header into API requests
• Update tokens dynamically (after login, token refresh, etc.)
• Skip authentication for certain endpoints (like login or public routes)
• Ensure thread-safety in concurrent environments

While this sounds straightforward, getting it right with Swift 6’s strict concurrency checking requires careful design. You need proper actor isolation, Sendable conformance, and a clean API that doesn’t fight the type system.

The Solution: BearerTokenAuthenticationMiddleware

I built BearerTokenAuthenticationMiddleware—a minimal, zero-dependency package that solves these problems elegantly. Here’s what makes it special:

1. Actor-Isolated Token Storage

The heart of the middleware is a private TokenStorage actor that manages the authentication token:

private actor TokenStorage {
    var token: String?

    func getToken() -> String? {
        token
    }

    func setToken(_ newToken: String?) {
        token = newToken
    }
}

This ensures that token reads and writes are never concurrent, eliminating race conditions completely.

2. Clean, Composable API

Setting up the middleware is straightforward:

import OpenAPIRuntime
import BearerTokenAuthMiddleware

let authMiddleware = BearerTokenAuthenticationMiddleware(
    initialToken: "my-secret-token"
)

let client = Client(
    serverURL: URL(string: "https://api.example.com")!,
    transport: AsyncHTTPClientTransport(),
    middlewares: [authMiddleware]
)

Every request now automatically includes Authorization: Bearer my-secret-token.

Wrapping Up

Building authentication middleware might seem like boilerplate, but doing it right—especially with modern Swift concurrency—requires thoughtful design. BearerTokenAuthenticationMiddleware provides:

• Thread-safe token management via actors
• Selective authentication with operation-level control
• Dynamic token updates
• Zero dependencies
• Clean composition with other middlewares

Repository: github.com/mihaelamj/BearerTokenAuthMiddleware

But then came the next step: Could this same architecture host a complete OpenAPI workflow — with generated clients, servers, and full middleware integration — without losing its elegance?

That’s how the new reference implementation, swift-openapi-extremepackaging-example, was born.

🧩 The Foundation — ExtremePackaging

The original ExtremePackaging repository introduced a clean, layered structure:

• Shared packages for models and protocols
• Independent feature modules for UI, data, and networking
• No cross-package leaks
• Unified Xcode workspace that felt like a monolith but built like microservices

The guiding philosophy: Each feature should be an island, communicating only through well-defined contracts.

That foundation made it ideal for integrating OpenAPI-generated code — which naturally fits into modular boundaries like SharedApiModels, ApiClient, and ApiServer.

🚀 Evolving Toward OpenAPI

The OpenAPI version added an entire new layer of automation and functionality — transforming a static architecture into a living, self-describing API ecosystem.

1. OpenAPI Schema & Code Generation

At the heart of the project is the OpenAPI specification (openapi.yaml) — defining endpoints, models, and responses for a DummyJSON-compatible API.

Newly introduced elements:

• 🧱 Full schema definitions for Users, Posts, Products, Todos, and Carts
• 🧩 Error schemas (404, validation, authentication)
• ⚙️ Integration with Swift OpenAPI Generator
• 🔁 Automatic generation of clients, models, and server stubs
• 📦 Separation of generated code into SharedApiModels

This turned the architecture into a self-contained API ecosystem — one that can generate, serve, and consume its own endpoints.

2. API Server Implementation

A complete Vapor-based local server (ApiServer) was added to simulate real-world backend behavior:

• 17 endpoints fully implemented from the OpenAPI spec
• Realistic mock data mirroring DummyJSON
• Pagination and validation logic
• Centralized error responses
• 🖥️ Prefixed logging for easy tracing in the console

The server runs locally at http://localhost:8080, serving as both a mock backend and a test harness for the generated client.

3. Enhanced API Client Architecture

The client evolved from a simple abstraction into a fully concurrent, actor-based networking layer.

Highlights

• ApiClient actor manages shared state safely across async contexts
• Middleware chain introduced: Logging → Authentication → Correction
• Runtime environment switching between .production, .local, and .mock
• Shared singleton ApiClientState stores token, settings, and preferences

Example flow:

try await ApiClient.initializeShared(environment: .production)
let client = ApiClient.shared!
let auth = try await client.login(username: "emilys", password: "emilyspass")
await ApiClient.setToken(auth.accessToken)
let users = try await client.getUsers(limit: 10)

A clear separation between environment configuration and runtime state ensures deterministic, thread-safe behavior.

4. Middleware Integration

The client leverages two reusable middlewares from sibling packages:

• OpenAPILoggingMiddleware
  Provides structured, console + JSON logging with full request/response capture.
• BearerTokenAuthMiddleware
  Manages JWT token injection with a concurrency-safe actor and public operation rules.

Together, they demonstrate the power of middleware chaining in OpenAPI Runtime — clean, modular extensions without inheritance or global state.

5. YAMLMerger — The Key to Structured API Specs

The project uses YamlMerger — a Swift package that merges multiple YAML files into a single combined OpenAPI specification.
If your project doesn’t already include an openapi.yaml, YamlMerger ensures you have one — and helps you maintain a structured, predictable folder layout under Tests/ or Sources/SharedApiModels/schemas/.

🧠 Why It Must Be Copied into the Project

YamlMerger cannot simply be added as a SwiftPM dependency for build-time merging because of SPM’s read-only resolution model:

1. Swift Package Manager stores dependencies in a cached, read-only location (.build/checkouts/).
2. The OpenAPI generator, however, needs write access to output the merged openapi.yaml file directly into your source tree.
3. SPM build scripts are not allowed to write to source folders outside their sandboxed build directory.

✅ Solution: Copy the YamlMerger executable directly into your project (e.g. Tools/YamlMerger/) and call it from a pre-build script or CI pipeline.
This guarantees write permissions and makes the tool available to everyone checking out the repo.

🧩 What It Does

YamlMerger scans subdirectories (01 → 08) and merges YAML fragments in deterministic order:

1. Folders are processed numerically.
2. __*.yaml files merge first within each folder.
3. Remaining files merge alphabetically.
4. The final output is a complete OpenAPI spec, suitable for Swift OpenAPI Generator.

🧱 Example Schema Layout

Schema/
├── 01_Info/
├── 02_Servers/
├── 03_Tags/
├── 04_Paths/
├── 05_Webhooks/
├── 06_Components/
├── 07_Security/
└── 08_ExternalDocs/

Each folder corresponds to a section of the OpenAPI spec, allowing multiple developers to work on different endpoints, schemas, or components without conflicts.

⚙️ Typical Workflow

# Merge schemas before build
./Tools/YamlMerger merge   --input Sources/SharedApiModels/schemas/   --output Sources/SharedApiModels/openapi.yaml

You can run this manually, in a pre-build phase, or as part of CI/CD automation.

💡 Pro Tip

If your project starts without an openapi.yaml, placing schema fragments in structured folders under Tests/ ensures your API structure remains organized — even before full code generation.
YamlMerger gives your tests (and your teammates) a shared, visual map of your API’s evolving shape.

6. Test Coverage Expansion

Two new test suites validate both local and production APIs:

• 🧪 ApiClientLocalTests.swift — 25 tests targeting the local Vapor server
• 🌐 ApiClientProductionTests.swift — 29 integration tests against DummyJSON API

Tests cover:

• Authentication and token persistence
• Pagination behavior
• Error responses and invalid IDs
• Concurrent request handling

Together they form a 54-test safety net proving both architecture and OpenAPI compliance.

🧠 Architecture Snapshot

Packages/
├── Sources/
│   ├── ApiClient/
│   ├── ApiServer/
│   └── SharedApiModels/
└── Tests/
    └── ApiClientTests/

Each target is self-contained — just like in the original ExtremePackaging — but now with full OpenAPI integration, client/server symmetry, and end-to-end testability.

⚡ Key Improvements Over ExtremePackaging

🧭 Lessons Learned

1. OpenAPI fits perfectly into modular Swift architectures — generated code belongs in its own layer, and SwiftPM makes that separation effortless.
2. Actors are the future of shared state — simple, safe, and transparent.
3. Middleware > Managers — function composition scales better than class hierarchies.
4. Automation beats documentation — with OpenAPI, the spec is the documentation.

💬 Closing Thoughts

This evolution of ExtremePackaging into a full OpenAPI reference app is more than a demo — it’s a blueprint for modular API-driven development in Swift.

From YAML schemas to live servers and typed clients, everything now exists in one unified, testable ecosystem — powered by Apple’s official OpenAPI tools and guided by the ExtremePackaging philosophy.

👉 Explore the project: swift-openapi-extremepackaging-example

“Architecture should scale not by adding layers, but by removing assumptions.”

In the world of OpenAPI-driven Swift servers, visibility is everything.
You can’t fix what you can’t see — and you can’t optimize what you don’t understand.

When I started building modular, OpenAPI-first architectures in Swift, one thing stood out: logging was either overwhelming or absent.
Either you got a raw dump of everything (headers, binary data, and stack traces), or you got nothing at all. Neither is particularly helpful when debugging or tracing an issue across microservices.

Frameworks like OpenAPIRuntime and OpenAPIVapor provide a strong foundation, but they deliberately avoid opinions about logging. They leave that up to you.
And that’s where most developers end up adding scattered print() statements or ad-hoc logger.info() calls inside handlers just to see what’s going on.

That’s not clean architecture. It’s noise.

So I built OpenAPILoggingMiddleware, a small, composable middleware that gives you just enough visibility — not too much, not too little — when working with OpenAPI-based servers.

The Problem: Logging in a Generated World

OpenAPI code generation has revolutionized how backend systems are written. You define your contracts, generate both server and client, and everything should “just work.”
But once requests start flowing, visibility often becomes a blind spot.

If you’ve ever tried debugging an OpenAPI-generated Swift server, you might recognize these problems:

• Middleware logs every byte of the body, even binary data.
• Multi-part and SSE requests produce unreadable noise.
• Response logs are buried under system output.
• There’s no consistent way to see request duration or endpoint performance.
• You can’t easily toggle verbosity levels or redact sensitive data.

You end up either drowning in log output or adding print calls just to survive the debugging process.

This middleware solves that.

The Solution: A Lightweight Logging Layer

OpenAPILoggingMiddleware sits quietly in the pipeline — between your generated routes and the transport layer.
It listens to every incoming request and outgoing response, measures duration, and prints a structured summary of what happened.

At its core, the idea is simple:

Log exactly what you’d want to see if you were reading someone else’s code.

Here’s how it looks in your Vapor or OpenAPI setup:

import OpenAPILoggingMiddleware

app.middleware.use(OpenAPILoggingMiddleware(level: .info))

That one line transforms your debugging experience.

Under the Hood

The middleware implements the OpenAPIMiddleware protocol, which lets it intercept the lifecycle of each OpenAPI operation — before the request is handled and after the response is sent.

Here’s a conceptual overview:

public struct OpenAPILoggingMiddleware: OpenAPIMiddleware {
    public func intercept(
        _ request: Request,
        operationID: String,
        next: (Request) async throws -> Response
    ) async throws -> Response {
        let start = Date()
        let response = try await next(request)
        let duration = Date().timeIntervalSince(start) * 1000

        print("[\(request.method)] \(request.url.path) -> \(response.status.code) [\(Int(duration)) ms]")
        return response
    }
}

Of course, the real implementation handles errors, structured formatting, and configurable verbosity, but the essence is the same:
it’s a transparent layer of introspection that doesn’t alter your data flow.

Logging Philosophy

There’s a fine balance between too much and too little information.

Traditional logging tools either dump everything (which nobody reads) or show too little (which leaves you guessing).
OpenAPILoggingMiddleware follows a minimalist principle inspired by Apple’s own frameworks — log what matters, hide what doesn’t.

It’s designed around three key ideas:

1. Contextual logging — every entry includes method, path, status, and duration.
2. Progressive verbosity — higher log levels show headers and bodies.
3. Human readability first — logs are meant to be scanned, not parsed by machines.

Here’s an example of what a single request looks like in .info mode:

[POST] /mocks/messages/agent-responses (200 OK)
Duration: 123 ms
Body: {"message":"You shall not pass!"}

And at .debug level, you get more detail:

[POST] /mocks/messages/agent-responses
Headers:
  Content-Type: application/json
  Authorization: Bearer Gandalf-Was-Here-1
Duration: 123 ms
Body: {"message":"You shall not pass!"}

Readable. Structured. Useful.

Why Not Just Use Vapor’s Logger?

That’s a valid question.

Vapor already includes a powerful logging system based on SwiftLog, so why add another layer?
Because Vapor’s logger is request-agnostic — it’s not aware of OpenAPI operations, generated endpoints, or typed models.

OpenAPILoggingMiddleware is contract-aware.
It sits in the OpenAPI pipeline, so it can access the operation ID, typed body, and structured response — all without touching your route handlers. That distinction is crucial for OpenAPI-based architectures, where most of your server logic is generated.

Integration Examples

Adding it to a Vapor-based OpenAPI server is trivial:

import Vapor
import OpenAPIRuntime
import OpenAPIVapor
import OpenAPILoggingMiddleware

let app = try Application(.detect())

let server = try! MyOpenAPIServer(app: app)

app.middleware.use(OpenAPILoggingMiddleware(level: .info))
try app.run()

If you’re using OpenAPIRuntime directly (without Vapor), it’s equally simple:

var server = try OpenAPIServer()
server.middleware.append(OpenAPILoggingMiddleware(level: .debug))
try server.start()

No configuration files. No dependencies. It just works.

Extensibility and Customization

Logging needs vary between environments.
In development, you might want to see every detail. In production, you want concise summaries. The middleware supports multiple log levels, allowing you to tailor verbosity to your needs:

• .error — log only failed requests.
• .info — log all requests with method, path, duration, and status.
• .debug — include headers and bodies.

In future releases, I plan to add filters and formatters — so you could, for instance, redact specific headers (Authorization, Cookie) or export logs in JSON format for ingestion into a centralized system.

Example:

let middleware = OpenAPILoggingMiddleware(
    level: .debug,
    redactHeaders: ["Authorization", "Cookie"]
)

Design Details: Why Simplicity Wins

Many logging libraries start small and end up as frameworks. They introduce dependency graphs, adapters, output sinks, configuration DSLs — and complexity sneaks in through the back door.

I deliberately avoided that path.

OpenAPILoggingMiddleware does one thing: it shows what your OpenAPI server is doing.
Nothing else.

No JSON serialization frameworks. No dependency injection. No external configuration.
Just clean Swift and a single dependency on OpenAPIRuntime.

The codebase is small enough to read in one sitting — and that’s intentional. In my opinion, you should be able to understand every line of code that runs in your server’s core path.

Performance Considerations

Logging always comes at a cost, but the impact here is minimal.
The middleware measures request duration using Date().timeIntervalSince(start), which is negligible compared to network latency or I/O.

You can safely keep it enabled even in staging or pre-production environments.
In production, switching to .error mode will keep your logs clean while still providing visibility into failures.

Testing and Debugging

The middleware is fully testable using Vapor’s Application test harness or plain XCTest with mock requests.
Here’s a simple test that validates duration and structure:

func testMiddlewareLogsRequestAndResponse() async throws {
    let app = Application(.testing)
    app.middleware.use(OpenAPILoggingMiddleware(level: .info))
    try await app.test(.POST, "/ping", afterResponse: { res in
        XCTAssertEqual(res.status, .ok)
    })
}

You can also inject your own logger conforming to LogHandler if you prefer structured output rather than printing to stdout.

Future Work

The roadmap includes:

1. JSON Formatter — for structured logs in production environments.
2. Redaction Rules — for headers and sensitive body fields.
3. Metrics Hooks — integration with Swift Metrics or Prometheus.
4. Pluggable Output Destinations — allowing streaming to files or external monitoring systems.
5. Async Logging — offloading logging I/O to background tasks for ultra-high performance scenarios.

Each of these will follow the same guiding principles: clarity, composability, and minimalism.

Philosophy: Clean Visibility

Logging is not just a developer tool — it’s part of the interface between humans and systems.
A well-designed logging layer doesn’t scream for attention; it quietly reveals how the system behaves.

When I was designing this package, I thought about the elegance of Apple’s own frameworks — the way their APIs feel inevitable, obvious in hindsight. That’s what I aim for here: a logging middleware that feels invisible until you need it, and indispensable once you use it.

Example Output in Context

Here’s a real-world example of multiple concurrent requests hitting the same endpoint:

[GET] /user/profile (200 OK)
Duration: 87 ms

[POST] /mocks/messages/agent-responses (200 OK)
Duration: 121 ms
Body: {"message":"You shall not pass!"}

[PATCH] /user/preferences (204 No Content)
Duration: 96 ms

Notice how easy it is to see patterns — which endpoints are slow, which ones are frequent, which ones failed.
That’s the essence of observability — not more data, but useful data.

Real-World Use

I use OpenAPILoggingMiddleware in all my OpenAPI projects — from small prototypes to complex SSE (Server-Sent Events) systems. It’s particularly valuable when debugging streamed responses or multipart form uploads, where conventional logs become unreadable.

Because it’s a simple OpenAPIMiddleware, it works with any generated server conforming to the OpenAPI ecosystem — including custom transports and pure SwiftNIO backends.

Closing Thoughts

This middleware is a reminder that sometimes the simplest tools make the biggest difference.
It’s easy to underestimate the power of well-designed visibility — until you remove it and start guessing again.

Whether you’re debugging mock routes, profiling API latency, or simply curious about what your server is doing, OpenAPILoggingMiddleware gives you that quiet transparency every developer deserves.

👉 GitHub: mihaelamj/OpenAPILoggingMiddleware

“Clean code should be composable, testable, and visible when it runs.”

Introduction

Extreme Packaging is a methodology for structuring Swift projects with maximal modularity and minimal responsibility per module.
Each module represents a single, isolated unit of logic — small enough to reason about, easy to test, and replaceable without side effects.

The core idea is separation:
modules depend on stable interfaces, not on each other’s implementations. This enables scalable architectures that remain flexible as projects evolve, while keeping build times short and dependencies explicit.

Table Of Contents:

• Part 1 — Project Setup
• Part 2 — Tooling

Goals

• Promote clean boundaries between domains and features
• Enable independent development and testing per package
• Simplify refactoring and dependency management
• Keep compilation fast and the architecture transparent

Process

The repository is organized into stages, each representing a self-contained checkpoint in the project’s evolution.
When moving between stages — especially when reverting to earlier ones — always reset and clean your workspace to ensure it matches the intended state.

Here’s the example for stage 01:

# Ensure you're on the branch you want
git checkout stage/01-init-packages

# Fetch the latest version
git fetch origin

# Reset your branch to the remote version
git reset --hard stage/01-init-packages

# Delete untracked files and directories
git clean -fdx

Philosophy

In most projects, modularization is an afterthought — introduced when the codebase becomes too large to manage.
Extreme Packaging inverts that approach: modularization is the starting point.
By treating each package as an autonomous component from day one, you gain clarity, resilience, and a foundation that naturally scales with complexity.

Part 1 — Project Setup

The first step in Extreme Packaging is establishing a clear and reproducible project structure that can evolve gradually through defined stages.
Each stage in the repository builds upon the previous one — from the initial package setup, to workspace creation, and finally to adding the app target that ties everything together.

Overview

The project begins as a Swift Package Manager–based structure, designed for modularity from the start.
At its core is a single Packages directory that houses all functional modules (such as AppFeature, SharedModels, and later others).
Every addition to the project — whether a new feature, UI layer, or platform target — is layered on top of this foundation in small, trackable increments.

Here is the link to the project used:
https://github.com/mihaelamj/ExtremePackaging

1.1 Stage 01 — Initialize Packages

Purpose

This stage ensures a working, self-contained Swift package that compiles and passes initial linting checks.

Parts

At stage/01-init-packages, the repository contains:

• A minimal package structure with Sources and Tests
• Core configuration files:
  • .swiftlint.yml for linting rules
  • .swiftformat for consistent formatting
  • .gitignore, LICENSE, and README.md
• Two base modules:
  • AppFeature — serves as the entry feature for the app
  • SharedModels — holds simple model definitions

Folder Structure snapshot

Example folder structure:

Inside the folder:

➜  ExtremePackaging git:(main) ✗ ls -all
 .
 ..
 .git
 .gitignore
 .swiftformat
 .swiftlint.yml
 Apps
 LICENSE
 Packages
 README.md

Inside the Packages folder:

➜  ExtremePackaging git:(main) cd Packages
➜  Packages git:(main) ls -all
 .
 ..
 Package.swift
 Sources
 Tests

Inside the Apps folder:

.
..
.gitkeep

Basic Package Code:

I start with package structure like this:

// swift-tools-version: 6.0

import PackageDescription

let package = Package(
    name: "Main",
    platforms: [
        .iOS(.v17),
        .macOS(.v14),
    ],
    products: [
        .singleTargetLibrary("AppFeature"),
    ],
    dependencies: [
        .package(url: "https://github.com/realm/SwiftLint", exact: "0.52.3"),
    ],
    targets: [
        .target(
            name: "AppFeature",
            dependencies: [
                "SharedModels",
            ]
        ),
        .testTarget(
            name: "AppFeatureTests",
            dependencies: [
                "AppFeature"
            ]
        ),
        .target(
            name: "SharedModels"
        )
    ]
)

// Inject base plugins into each target
package.targets = package.targets.map { target in
    var plugins = target.plugins ?? []
    plugins.append(.plugin(name: "SwiftLintPlugin", package: "SwiftLint"))
    target.plugins = plugins
    return target
}

extension Product {
    static func singleTargetLibrary(_ name: String) -> Product {
        .library(name: name, targets: [name])
    }
}

Dummy Files

AppView

import SharedModels
import SharedViews
import SwiftUI

public struct AppView: View {
    public var body: some View {
        VStack {
            Text("Extreme Packaging!")
                .font(.title)
                .fontWeight(.bold)
                .multilineTextAlignment(.center)
                .padding()
        }
    }
}

DummyModel

import Foundation

public struct DummyModel: Identifiable {
    public var id: UUID = .init()
    public var title: String
    public init(
        id: UUID = .init(),
        title: String
    ) {
        self.id = id
        self.title = title
    }
}

Stage 01-init-packages

Here’s the code for stage 01:

# Clone repo if needed
git clone git@github.com:mihaelamj/ExtremePackaging.git

# Ensure you're on the branch you want
git checkout stage/01-init-packages

# Fetch the latest version
git fetch origin

# Reset your branch to the remote version
git reset --hard stage/01-init-packages

# Delete untracked files and directories
git clean -fdx

To see how it looks in Xcode we need to switch to subfolder packages, since we haven’t created the workspace yet.

➜  ExtremePackaging git:(stage/01-init-packages) ✗ cd Packages
➜  Packages git:(stage/01-init-packages) ✗ xed .

1.2 Stage 02 — Add Workspace

Purpose

In stage/02-workspace-added, an Xcode workspace named Main.xcworkspace is introduced at the project root.
It includes the Packages folder, allowing smooth integration of multiple modules while keeping them decoupled.
This step establishes the foundation for a multi-target environment.

Workspace creation steps

Create a new workspace (I name it Main), in the root of our folder.

Add folder Packages to the workspace.
It will add our package structure to the project:

Stage 02-add—to-workspace

Here’s the code for stage 02:

# Clone repo if needed
git clone git@github.com:mihaelamj/ExtremePackaging.git

# Ensure you're on the branch you want
git checkout stage/02-add—to-workspace

# Fetch the latest version
git fetch origin

# Reset your branch to the remote version
git reset --hard stage/02-add—to-workspace

# Delete untracked files and directories
git clean -fdx

Now we have the workspace, so we just need to open Xcode:

➜  Packages git:(stage/02-add—to-workspace) ✗ xed .
➜  Packages git:(stage/02-add—to-workspace) ✗

1.3 Stage 03 — Add iOS and macOS App Targets

Platform targets creation

Add new iOS and a new macOS project
Repeat this for each target:

Create a new project in Xcode:

Add each to Apps folder:

Adding them to workspace

We will be adding each app target to the workspace, below Packages.
Open the current repository folder and drag both new projects (iOS and macOS) into the workspace sidebar.

Each target remains isolated within its own folder, but both share the same logic through the AppFeature module.
This ensures that all common code — views, models, and reducers — stays within shared packages, while each platform target keeps its own configuration files.

Open the current repo folder:

Add macOS target:

Choose “Reference files in place”

This is how it looks when added:

Add iOS target:

This is how it looks when added:

Explanation: Why separate targets

Keeping iOS and macOS projects distinct allows:

• Independent platform configuration (e.g. Info.plist, app icons, signing settings)
• Platform-specific features when needed (e.g. menu commands on macOS, touch gestures on iOS)
• Consistent architecture and shared logic through modular Swift packages

This structure aligns perfectly with the Extreme Packaging philosophy — shared foundation, platform-specific shells.

Configuration steps

• Delete automatically added ContentView.swift
• Add AppFeature package to the our target:

Now our project looks like this:

And the main app starts with the fully testable AppFeature

import SwiftUI
import AppFeature

@main
struct SwiftUIAppApp: App {
    var body: some Scene {
        WindowGroup {
            AppView()
        }
    }
}

Final structure

At this point, the project has evolved into a fully cross-platform modular setup.

The screenshot below illustrates the final structure after completing Stage 03 (iOS & macOS targets added):

• The Packages directory defines the shared Swift Package with AppFeature and SharedModels modules.
• Both iOS and macOS apps live inside the Apps folder, each with its own assets, entry point, and platform-specific configuration files.
• The Package.swift file defines a single modular product, with SwiftLint integrated as a plugin and dependencies kept cleanly separated.
• This structure enables both platforms to share logic and UI built with SwiftUI, while still allowing native customization per platform.

Result:
A clean, modular workspace where shared code resides in packages, and each platform acts only as a thin presentation shell — the essence of Extreme Packaging.

Stage 03-apps-added

In stage/03-apps-added, we create two separate app targets — one for iOS and one for macOS — both sharing the same SwiftUI core logic.

Each app lives inside the Apps folder and imports the AppFeature module, demonstrating how the same feature package can power multiple platforms with no duplicated code.

After adding the targets:

• Delete the automatically generated ContentView.swift
• Add the AppFeature package dependency to both targets
• Verify that both apps build successfully

This stage concludes with a fully functional cross-platform setup where both iOS and macOS share a unified architecture driven by modular packages.

Here’s the code for stage 03:

# Clone repo if needed
git clone git@github.com:mihaelamj/ExtremePackaging.git

# Ensure you're on the branch you want
git checkout stage/03-apps-added

# Fetch the latest version
git fetch origin

# Reset your branch to the remote version
git reset --hard stage/03-apps-added

# Delete untracked files and directories
git clean -fdx

Summary

Each stage corresponds to a dedicated branch in the repository, allowing you to switch between checkpoints and observe the project’s evolution step by step.
This structure provides a transparent history of how a modular Swift project grows from a single package into a fully multi-platform architecture.

Part 2 — Tooling

• Every project includes SwiftLint and SwiftFormat for enforcing consistent code style and quality
• Each stage of the repository introduces incremental improvements, from initializing packages to adding app targets and integrations
• These are applied from the very first stage but can be customized at any point.

GitIgnore

# Xcode
#
# gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore

## User settings
xcuserdata/

## Obj-C/Swift specific
*.hmap

## App packaging
*.ipa
*.dSYM.zip
*.dSYM

## Playgrounds
timeline.xctimeline
playground.xcworkspace

# Swift Package Manager
.build/
.swiftpm/
Package.resolved

# Xcode workspace & projects
*.xcworkspace/xcshareddata/WorkspaceSettings.xcsettings
*.xcworkspace/xcuserdata/
DerivedData/
*.xcuserstate
*.xcscmblueprint
*.xccheckout

# macOS system files
.DS_Store

# Carthage
Carthage/Build/

# fastlane
fastlane/report.xml
fastlane/Preview.html
fastlane/screenshots/**/*.png
fastlane/test_output

# Custom folders used in ExtremePackaging
Stage/
Tasks/.build/

SwiftFormat Config

This is my .swiftformat

# General Options
--swiftversion 5.7

# File Options
--exclude Stage,Tasks/.build,ThirdParty,**/SwiftGen/*,**/Sourcery/*,Frameworks/swift-composable-architecture,**.generated.swift

# Format Options

--allman false
--binarygrouping none
--closingparen balanced
--commas always
--conflictmarkers reject
--decimalgrouping none
--elseposition same-line
--exponentcase lowercase
--exponentgrouping disabled
--fractiongrouping disabled
--fragment false
--header ignore
--hexgrouping none
--hexliteralcase lowercase
--ifdef no-indent
--importgrouping alphabetized
--indent 4
--indentcase false
# make sure this matches .swiftlint
--maxwidth 180
--nospaceoperators ..<,...
--octalgrouping none
--operatorfunc no-space
--selfrequired
--stripunusedargs closure-only
--trailingclosures
--wraparguments before-first
--wrapcollections before-first
--wrapparameters before-first

# Rules
--disable hoistAwait
--disable hoistPatternLet
--disable hoistTry
--disable wrapMultilineStatementBraces
--disable extensionAccessControl

SwiftLint Config

disabled_rules: # rule identifiers to exclude from running
  - opening_brace
  - operator_whitespace
  - orphaned_doc_comment

opt_in_rules:
  - empty_count
  - force_unwrapping
  - shorthand_optional_binding
  - weak_delegate

excluded:
  - "*.generated"

custom_rules:
  # check's for Combine's .assign(to: xxx, on: self) ref-cycle
  combine_assign_to_self:
    included: ".*\\.swift"
    name: "`assign` to self"
    regex: '\.assign\(to: [^,]*, on: self\)'
    message: "For assigning on self, use assignNoRetain(to: ..., on: self)."
    severity: error
  duplicate_remove_duplicates:
    included: ".*\\.swift"
    name: "Duplicate `removeDuplicates()`"
    message: "ViewStore's publisher already does `removeDuplicates()`"
    regex: 'publisher\.[^(|{|,]*removeDuplicates\(\)'
    severity: error
  dont_scale_to_zero:
    included: ".*\\.swift"
    name: "Don't scale down to 0."
    regex: "\\.scaleEffect\\([^\\)]*(\\ 0\\ [^\\)]*\\)|0.0(\\ |\\))|\\ 0(\\)|,))"
    message: "Please make sure to pass a number not equal zero, so transformations don't throw warnings like `ignoring singular matrix`."
    severity: error
  use_data_constructor_over_string_member:
    included: ".*\\.swift"
    name: "Do not use String.data(using: .utf8)"
    regex: "\\.?data\\(using: \\.utf8\\)"
    message: "Please use Data(string.utf8) instead of String.data(using: .utf8) because the Data constructor is non-optional and Strings are guaranteed to be encodable as .utf8"
    severity: error
  tca_explicit_generics_reducer:
    included: ".*\\.swift"
    name: "Explicit Generics for Reducer"
    regex: 'Reduce\s+\{'
    message: "Use explicit generics in ReducerBuilder (Reduce<State, Action>) for successful autocompletion."
    severity: error
  tca_scope_unused_closure_parameter:
    name: "TCA Scope Unused Closure Parameter"
    regex: '\.scope\(\s*state\s*:\s*\{\s*\_'
    message: "Explicitly use closure parameter when scoping store (ensures the right state is being mutated)"
    severity: error
  tca_use_observe_viewstore_api:
    name: "TCA ViewStore observe API"
    regex: 'ViewStore\(store\.scope'
    message: "Use modern observe: api instead of store.scope"
    severity: error

trailing_comma:
    mandatory_comma: true

cyclomatic_complexity:
  ignores_case_statements: true
  warning: 20

file_length:
  warning: 1000
  error: 1000

identifier_name:
  severity: warning
  allowed_symbols: "_"
  min_length: 2
  max_length:
    warning: 90
    error: 90
  excluded:
    - iO
    - id
    - vc
    - x
    - y
    - i
    - pi
    - d

legacy_constant: error
legacy_constructor: error

line_length:
  warning: 180
  error: 180
  ignores_comments: true
  ignores_urls: true

nesting:
  type_level:
    warning: 3
    error: 3
  function_level:
    warning: 5
    error: 5

function_parameter_count:
  warning: 5

force_cast: warning
force_unwrapping: warning

type_body_length:
  - 300 # warning
  - 300 # error

large_tuple:
  - 3  # warning
  - 10 # error%

Why CVBuilder?

In today’s digital world, professionals often need to maintain their CVs in multiple formats and keep them in sync. Traditional word processors make this process tedious and error-prone. CVBuilder solves this by:

• Providing a strongly-typed data model for CVs
• Supporting multiple output formats (Markdown, HTML, plain text)
• Making it easy to maintain a single source of truth
• Enabling programmatic CV generation and updates

Core Features

1. Strongly Typed Data Model

CVBuilder provides a comprehensive data model that covers all aspects of a professional CV:

CV
├── ContactInfo
├── Education
├── WorkExperience
│   ├── Company
│   ├── Role
│   └── ProjectExperience
│       ├── Project
│       └── Tech
└── Period

Each component is strongly typed, ensuring data integrity and making it impossible to create invalid CVs.

2. Multiple Renderers

CVBuilder supports three different renderers out of the box:

1. MarkdownCVRenderer: Generates clean, well-formatted Markdown
2. StringCVRenderer: Produces plain text output
3. IgniteRenderer: Creates beautiful HTML using the Ignite static site generator

3. Modular Architecture

The package is split into two main components:

• CVBuilder: Core types and basic rendering
• CVBuilderIgnite: Optional HTML rendering support

This separation ensures that projects that don’t need HTML rendering don’t have to pull in unnecessary dependencies.

Getting Started

Installation

Add CVBuilder to your project using Swift Package Manager:

.package(url: "https://github.com/mihaelamj/cvbuilder.git", branch: "main")

Then add the desired product:

.product(name: "CVBuilder", package: "cvbuilder"),
.product(name: "CVBuilderIgnite", package: "cvbuilder") // if using Ignite

Creating a CV

Here’s a simple example of creating a CV:

import CVBuilder

// Create contact info
let contactInfo = ContactInfo(
    email: "jane.doe@example.com",
    phone: "+1 (555) 123-4567",
    linkedIn: URL(string: "https://linkedin.com/in/janedoe"),
    github: URL(string: "https://github.com/janedoe"),
    website: URL(string: "https://janedoe.dev"),
    location: "San Francisco, CA"
)

// Create education
let education = Education(
    institution: "Stanford University",
    degree: "B.S.",
    field: "Computer Science",
    period: Period(
        start: .init(month: 9, year: 2010),
        end: .init(month: 6, year: 2014)
    )
)

// Create the CV
let cv = CV.create(
    name: "Jane Doe",
    title: "Senior Mobile Developer",
    summary: "Passionate mobile developer with 5+ years experience...",
    contactInfo: contactInfo,
    education: [education],
    projects: [project1, project2]
)

Generating Output

Once you have your CV data model, generating different formats is straightforward:

// Generate Markdown
let markdown = MarkdownCVRenderer(cv: cv).render()

// Generate plain text
let plainText = StringCVRenderer(cv: cv).render()

// Generate HTML (requires CVBuilderIgnite)
let html = IgniteRenderer(cv: cv).render()

Advanced Features

Project Builder Pattern

CVBuilder includes a builder pattern for creating project experiences:

let project = try! Project.Builder()
    .withName("iOS App Redesign")
    .withCompany(appleCompany)
    .withRole(seniorIOS)
    .withPeriod(start: (month: 3, year: 2020), end: (month: 9, year: 2021))
    .addDescription("Led a team of 5 developers...")
    .withTechs([swift, swiftUI])
    .build()

Tech Stack Management

The package includes a Tech type for managing technical skills:

let swift = Tech(name: "Swift", category: .language)
let swiftUI = Tech(name: "SwiftUI", category: .framework)
let restAPI = Tech(name: "REST API", category: .concept)

How I Use It on This Webpage

My blog is built using Ignite, a static site generator for Swift. I’ve integrated CVBuilder into my website to maintain and display my CV in a clean, professional format.

Package Dependencies

I include CVBuilder in my website’s package file:

let package = Package(
    name: "IgniteStarter",
    platforms: [.macOS(.v13)],
    dependencies: [
        .package(url: "https://github.com/twostraws/Ignite.git", branch: "main"),
        .package(url: "https://github.com/mihaelamj/cvbuilder.git", branch: "main")
    ],
    targets: [
        .executableTarget(
            name: "IgniteStarter",
            dependencies: [
                .product(name: "Ignite", package: "Ignite"),
                .product(name: "CVBuilder", package: "cvbuilder"),
                .product(name: "CVBuilderIgnite", package: "cvbuilder")
            ]
        ),
    ]
)

Personal Information

I maintain my personal information in a dedicated Swift file (CV+Mihaela.swift):

public extension CV {
    static func createForMihaela() -> CV {
        let contactInfo = ContactInfo(
            email: "me@me.com",
            phone: "+12233445566",
            linkedIn: URL(string: "https://www.linkedin.com/in/mylinkedin"),
            github: URL(string: "https://github.com/mygithub"),
            website: URL(string: "https://mywebsite.com"),
            location: "City, Country"
        )
        
        let education = Education(...)
        
        // ... rest of the implementation
    }
}

Project History

My professional experience is organized in a separate file (CV+Projects.swift), which contains detailed information about all my projects:

public extension CV {
    static func createMihaelasProjects() -> [Project] {
        var result = [Project]()
        
        // Create companies
        let undabot = Company(name: "Undabot")
        let token = Company(name: "Token")
        // ... more companies
        
        // Create tech skills
        let swift = Tech(name: "Swift", category: .language)
        let uiKit = Tech(name: "UIKit", category: .framework)
        // ... more tech skills
        
        // Create projects using the builder pattern
        let project1 = try! Project.Builder()
            .withName("SomeProject")
            .withCompany(Company name)
            .withRole(juniorIOS)
            .withPeriod(start: (month: 9, year: 20XX), end: (month: 12, year: 20XX))
            .addDescription("iOS (iPad) book application about...)
            .withTechs([swift, uiKit])
            .build()
        
        // ... more projects
        
        return result
    }
}

This modular approach allows me to:

1. Keep my CV data in a strongly-typed format
2. Easily update my experience and skills
3. Generate both HTML and Markdown versions of my CV
4. Maintain consistency across different platforms

The CV is automatically generated when the website is built, ensuring that my professional information is always up-to-date and consistently formatted.

Markdown Generation

I also generate a Markdown version of my CV that I can use to create a fresh PDF whenever needed. This is done using a simple function:

func generateMihaelasCVMarkdownInContentFolder() {
    let cv = CV.createForMihaela()
    let markdown = MarkdownCVRenderer().render(cv: cv)

    let fileURL = URL(fileURLWithPath: "Assets/mihaela-cv.md")

    do {
        try markdown.write(to: fileURL, atomically: true, encoding: .utf8)
        print("✅ Written to \(fileURL.path)")
    } catch {
        print("❌ Failed to write Mihaela's CV: \(error.localizedDescription)")
    }
}

This function:

1. Creates my CV using the createForMihaela() function
2. Renders it to Markdown using MarkdownCVRenderer
3. Saves the output to Assets/mihaela-cv.md
4. Provides feedback about the success or failure of the operation

I can then use this Markdown file to generate a fresh PDF whenever I need to update my CV for job applications or other purposes.

Future Plans

CVBuilder is actively maintained and has several planned improvements:

1. Command-line interface for CV generation
2. Additional renderers (PDF, LaTeX)
3. Import/export functionality for common formats
4. Template system for customizing output

Conclusion

CVBuilder provides a robust solution for managing professional CVs in Swift. Its type-safe design, multiple renderers, and modular architecture make it an excellent choice for developers who want to maintain their CVs programmatically.

Whether you’re building a personal website, managing multiple CV versions, or creating a CV management system, CVBuilder can help streamline your workflow and ensure consistency across all your professional documents.

Resources

• GitHub Repository
• Sample CV
• Documentation

The Challenge

SwiftUI’s animation system is powerful but can behave differently across platforms. While iOS and macOS share the same SwiftUI framework, there are subtle differences in how animations are handled, especially when dealing with:

• Gesture recognizers
• View transitions
• Animation timing
• Platform-specific UI elements

My goal was to create a unified codebase that would work flawlessly on both platforms while maintaining the original animations’ elegance and performance.

Project Structure

I organized the project to make it easy to understand and extend:

SwiftUILab_AA/
├── Examples/
│   ├── Animation1/
│   ├── Animation2/
│   └── ...
├── Shared/
│   ├── Views/
│   ├── Models/
│   └── Extensions/
└── App/
    ├── iOS/
    └── macOS/

Each animation example has its own folder, making it easy to:

• Study individual animations in isolation
• Copy and paste specific animations into other projects
• Modify and experiment with different parameters

Key Features

1. Cross-Platform Compatibility

The project uses SwiftUI’s platform-agnostic features while handling platform-specific requirements:

#if os(iOS)
    // iOS-specific code
#elseif os(macOS)
    // macOS-specific code
#endif

2. Reusable Components

I created a set of reusable components that work on both platforms:

struct AnimatedButton: View {
    @State private var isPressed = false
    
    var body: some View {
        Button(action: {}) {
            Text("Animate")
                .scaleEffect(isPressed ? 0.95 : 1.0)
                .animation(.spring(), value: isPressed)
        }
        .buttonStyle(PlainButtonStyle())
        .onHover { hovering in
            isPressed = hovering
        }
    }
}

3. Gesture Handling

The project includes platform-appropriate gesture handling:

struct DragGestureView: View {
    @State private var offset = CGSize.zero
    
    var body: some View {
        Rectangle()
            .fill(Color.blue)
            .frame(width: 100, height: 100)
            .offset(offset)
            .gesture(
                DragGesture()
                    .onChanged { value in
                        offset = value.translation
                    }
                    .onEnded { _ in
                        withAnimation(.spring()) {
                            offset = .zero
                        }
                    }
            )
    }
}

Example Animations

1. Morphing Shapes

One of the most impressive animations is the shape morphing effect:

struct MorphingShape: View {
    @State private var isMorphed = false
    
    var body: some View {
        Circle()
            .fill(Color.blue)
            .frame(width: 100, height: 100)
            .scaleEffect(isMorphed ? 1.5 : 1.0)
            .animation(.spring(response: 0.6, dampingFraction: 0.6), value: isMorphed)
            .onTapGesture {
                isMorphed.toggle()
            }
    }
}

2. Custom Transitions

The project includes several custom transitions that work on both platforms:

extension AnyTransition {
    static var customScale: AnyTransition {
        .scale(scale: 0.1)
        .combined(with: .opacity)
    }
}

Implementation Details

1. View Extensions

I created several extensions to make animations more reusable:

extension View {
    func animateOnHover() -> some View {
        self.modifier(HoverAnimationModifier())
    }
}

2. Animation Timing

Careful attention was paid to animation timing to ensure smooth performance:

struct TimingAnimation: View {
    @State private var isAnimating = false
    
    var body: some View {
        Circle()
            .fill(Color.red)
            .frame(width: 50, height: 50)
            .offset(y: isAnimating ? -100 : 0)
            .animation(
                .timingCurve(0.68, -0.6, 0.32, 1.6, duration: 1),
                value: isAnimating
            )
            .onAppear {
                isAnimating = true
            }
    }
}

Benefits for Developers

1. Cross-Platform Learning: Developers can learn SwiftUI animations that work on both iOS and macOS
2. Ready-to-Use Examples: Each animation is self-contained and can be easily copied into other projects
3. Performance Optimized: Animations are optimized for smooth performance on both platforms
4. Educational Resource: The project serves as a comprehensive guide to SwiftUI animations

Future Improvements

The project is actively maintained with several planned enhancements:

1. Adding more complex animation examples
2. Implementing accessibility features
3. Creating a documentation site with interactive examples
4. Adding support for visionOS

Conclusion

SwiftUILab_AdvancedAnimations bridges the gap between iOS and macOS animation development in SwiftUI. By providing a unified codebase and clear examples, it helps developers create beautiful, performant animations that work across Apple’s platforms.

Whether you’re building for iOS, macOS, or both, this project provides valuable insights into SwiftUI’s animation capabilities and best practices for cross-platform development.

Resources

• GitHub Repository
• Original SwiftUILab Article
• SwiftUI Documentation

I’ve been researching Core Animation framework for the past few months.
I’ve started with several books on the subject, but I found watching related WWDC videos most rewarding. The presenters put the content in a relevant context which makes it easier to apprehend and learn from it.

1. Introduction

One WWDC session particularly intrigued me: “2011–421 Core Animation Essentials”. They presented their demo named: “Layers in Perspective”, and it showed six layers, forming a flattened cube:

The sixth layer is hiding behind the layer number 5. It has a lower zPosition then the layer above it.

They have also demonstrated opening and closing the cube formation.

So, I have decided to demonstrate that.

Here’s a link to a GitHub repo with the source code:
Core Animation 3D Cube

Here’s the animation:

You can also see it on You Tube

Layers in Core Animation live in 3D geometry. But a layer is a 2D construct, so Core Animation coordinate space is called a 2.5D geometry.

To illustrate that just see what happens when you mess up your transformations.

Layers are 2D objects, they don’t understand the third dimension.
They are like playing cards in space., and there is no depth buffer available.

And also, intersecting layers should be avoided because in the image above, Core Animation needs to do a lot of work.
So just to draw the red layer intersecting only the blue layer, Core Animation needs to

• cut the red layer into two pieces
• render back part of the red layer
• then render the full blue layer
• then render the front part of the red layer again
  And all that work is for just intersection, and here we have multiple.

2. Building the Cube in 3D

2.1. Setting up the multi-platform project

I wanted the project to fun on the macOS , iOS and iPadOS, so I used AllApples Swift package.

After removing the storyboards and pimping up the AppDelegate and main.swift for the macOS version, and SceneDelegate for the mobile versions, I was ready to start.

2.1.1. main.swift for the macOS

import Cocoa
let delegate = AppDelegate()
NSApplication.shared.delegate = delegate
_ = NSApplicationMain(CommandLine.argc, CommandLine.unsafeArgv)

2.1.2. AppDelegate for the macOS

import Cocoa
import AllApples

class AppDelegate: NSObject, NSApplicationDelegate {
  private var window: NSWindow?
  func applicationDidFinishLaunching(_ aNotification: Notification) {
    window = AppSceneDelegate.makeWindow_Mac(theVC: CommonViewController())
  }
}

2.1.3. SceneDelegate for the iOS and iPadOS

import UIKit
import AllApples

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
  var window: UIWindow?
  func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    guard let aScene = (scene as? UIWindowScene) else { return }
    window = AppSceneDelegate.makeWindow_iOS(theScene: aScene, theVC: CommonViewController())
  }
}

2.2. Building the Basic Blocks

The first I did is make a PlainLayerView .
It is an AView descendant, which means that it is typedef-ed to be either a UIView or a NSView.

It is an intermediary object just to set up a thing on the macOS as well (doesn’t work yet).

I then created CustomLayerView to have nice sides for the cube, with CATextLayer as the number of the cube side, and a nice rounded border, so that we can peek into our cube while rotating.

Here’s the image of all six layers drawn by using a CustomLayerView

This layout was abandoned because I couldn’t make the transformation of purple view to work when transforming in 3D.

The solution is to add an additional CATransformLayer to the green layer, and mount the purple layer onto it. As explained in this blog post by Oliver Drobnik Cubed CoreAnimation Conundrum.

But I didn’t want to lose the linearity of the solution, and I used the approach demonstrated in the mentioned WWDC session: “2011–421 Core Animation Essentials”

They used the zOrder property of a layer, and so I put purple layer on top of the red layer to achieve that.

    if number == 4 {
      view.layer.zPosition = 1
    }

As you can see in the image below, the purple layer is in front of the red layer, which is obvious when we rotate the flattened cube.

2.3. Turning the Transform On and Off

I did take the approach that Over Drobnik did in his article: Cubed CoreAnimation Conundrum , and used it like this:

	side4.layer?.zPosition = on ? CACube3DView.sideWidth : 1
    side1.layer?.transform = on ? CATransform3D.transformFor3DCubeSide(1, zWidth: CACube3DView.sideWidth)  : CATransform3DIdentity
    side2.layer?.transform = on ? CATransform3D.transformFor3DCubeSide(2, zWidth: CACube3DView.sideWidth)  : CATransform3DIdentity
    side3.layer?.transform = on ? CATransform3D.transformFor3DCubeSide(3, zWidth: CACube3DView.sideWidth)  : CATransform3DIdentity
    side4.layer?.transform = on ? CATransform3D.transformFor3DCubeSide(4, zWidth: CACube3DView.sideWidth)  : CATransform3DIdentity
    side5.layer?.transform = on ? CATransform3D.transformFor3DCubeSide(5, zWidth: CACube3DView.sideWidth)  : CATransform3DIdentity
    side6.layer?.transform = on ? CATransform3D.transformFor3DCubeSide(6, zWidth: CACube3DView.sideWidth)  : CATransform3DIdentity

2.4. Transforming the Layers to Form a Cube

I didn’t use his transform code, since he used that additional CATransformLayer, so it wouldn’t work. So, here’s a small extension on the CATransform3D

public extension CATransform3D {
  static func transformFor3DCubeSide(_ number: Int, zWidth: CGFloat) -> CATransform3D {

    let halfPi = CGFloat(Double.pi) / 2.0
    var trans = CATransform3DIdentity
    switch number {
      case 1:
        trans = CATransform3DMakeRotation(halfPi, 0, 1, 0)
        break
      case 2:
        trans = CATransform3DIdentity
        break
      case 3:
        trans = CATransform3DMakeRotation(-halfPi, 0, 1, 0)
        break
      case 4:
        trans = CATransform3DMakeTranslation(0, 0, zWidth)
        break
      case 5:
        trans = CATransform3DMakeRotation(-halfPi, 1, 0, 0)
        break
      case 6:
        trans = CATransform3DMakeRotation(halfPi, 1, 0, 0)
        break
      default:
        break
    }
    return trans
  }
}

I actually used the approach form that WWDC session, and also used anchorPoint properties of the CALayer.

2.5. Positioning Cube Sides

Here’s a little extension on CGPoint that returns a tuple of our cube side positions and anchor points:

public extension CGPoint {
  static func anchorPointAndPositionForCubeSideLayer(number: Int, sideSize: CGFloat) -> (anchorPoint: CGPoint, position: CGPoint) {
    var resultAnchorPoint = CGPoint(x:0.5, y:0.5)
    var resultPosition = CGPoint(x:0.0, y:0.0)
    let halfSideSize: CGFloat = sideSize / 2.0
    switch number {
      case 1:
        resultAnchorPoint = CGPoint(x:1.0, y:0.5)
        resultPosition = CGPoint(x:-halfSideSize, y:0.0)
        break
      case 2:
        resultAnchorPoint = CGPoint(x:0.5, y:0.5)
        resultPosition = CGPoint(x:0.0, y:0.0)
        break
      case 3:
        resultAnchorPoint = CGPoint(x:0.0, y:0.5)
        resultPosition = CGPoint(x:halfSideSize, y:0.0)
        break
      case 4:
        resultAnchorPoint = CGPoint(x:0.5, y:0.5)
        resultPosition = CGPoint(x:0.0, y:0.0)
        break
      case 5:
        resultAnchorPoint = CGPoint(x:0.5, y:1.0)
        resultPosition = CGPoint(x:0.0, y:-halfSideSize)
        break
      case 6:
        resultAnchorPoint = CGPoint(x:0.5, y:0.0)
        resultPosition = CGPoint(x:0.0, y:halfSideSize)
        break
      default:
        break
    }
    return (anchorPoint: resultAnchorPoint, position: resultPosition)
  }
}

In the image below I have marked where the anchor points are for each layer:

The only fallacy in the image above, is that the purple layer is actually above our red layer, but I wanted to show where those anchor points are.
So, the actual image looks like this, but we now don’t see the red layer.

An Anchor point is a center of rotation. It determines how will the layer rotate.
Imagine holding a playing card with two fingers. Then try to spin the card. The anchor point of that card is where you are holding it with fingers.

3. Responding to Gestures

I made a small GestureRecognizerView to be able to respond to gestures and move, rotate and scale our layers.

It hooks-up:

• NSPanGestureRecognizer and UIPanGestureRecognizer
• func rotate(with event: NSEvent) and UIRotationGestureRecognizer
• NSClickGestureRecognizer and UITapGestureRecognizer
• func magnify(with event: NSEvent) and UIPinchGestureRecognizer

It then exposes all those events to the developer to use:

public extension GestureRecognizerView {
  @objc func rotationChanged(degrees: Float) {}
  @objc func rotationChanged(radians: Float) {}
  @objc func displacementChanged(displacement: CGPoint) {}
  @objc func scaleChanged(scale: CGFloat) {}
  @objc func tapHappened() {}
}

4. Building a Layer to hold a Cube

CACube3DView will hold the six layers than (can) make a cube.
In order for Core Animation to render the transformed views in perspective, there is a property sublayerTransform.

You either use that property of your parent layer, or add another layer class to your layer hierarchy: CATransformLayer. I opted to use that.

private(set) public lazy var transformedLayer: CALayer = {
    let l = CATransformLayer()
    l.name = "Transform Layer"
    #if os(OSX)
    l.isGeometryFlipped = true
    #endif
    return l
}()

When adding sublayers, I add them to this transformedLayer property, and not my view’s layer.

func addSideSubview(_ subview: AView) {
    addSubview(subview)

    #if os(iOS) || os(tvOS)
    transformedLayer.addSublayer(subview.layer)
    #endif

    #if os(OSX)
    if let aLayer = subview.layer {
      transformedLayer.addSublayer(aLayer)
    } else {
      fatalError("`subview.layer` == `nil`")
    }
    #endif
}

5. Perspective & Rotation

When the app first runs it shows in perspective.
I made a little extension:

public extension CATransform3D {
  static func somePerspectiveTransform() -> CATransform3D {
    var perspective = CATransform3DIdentity;
    perspective.m34 = -1.0 / 500.0;
    perspective = CATransform3DRotate(perspective, CGFloat(Double.pi) / 8, 1, 0, 0);
    perspective = CATransform3DRotate(perspective, CGFloat(Double.pi) / 8, 0, 1, 0);
    perspective = CATransform3DScale(perspective, 0.7, 0.7, 0.7)
    return perspective
  }
}

The part: perspective.m34 = -1.0 / 500.0; sets the perspective.
The .34 field of a matrix shows the amount of perspective distortion applied.
The amount 500 is often used in examples. If it were smaller, the layers would seem very close and distorted, like a fish-eye effect.

This is the initial transform, but we want to be able to move and rotate our cube (flattened or not) with our fingers.

Here’s the code:

public extension CATransform3D {

  func rotationFromDisplacement(_ displacement: CGPoint, sideWidth: CGFloat, is3D: Bool) -> CATransform3D {

    var currentTransform = self

    let totalRotation: CGFloat = sqrt(displacement.x * displacement.x + displacement.y * displacement.y)
    let angle: CGFloat = totalRotation * .pi / 180.0

    let xRotationFactor = displacement.x / angle
    let yRotationFactor = displacement.y / angle

    if is3D {
      currentTransform = CATransform3DTranslate(currentTransform, 0, 0, sideWidth / 2.0)
    }

    var rotationalTransform = CATransform3DRotate(currentTransform, angle,
                                                  (xRotationFactor * currentTransform.m12 - yRotationFactor * currentTransform.m11),
                                                  (xRotationFactor * currentTransform.m22 - yRotationFactor * currentTransform.m21),
                                                  (xRotationFactor * currentTransform.m32 - yRotationFactor * currentTransform.m31))

    if (is3D) {
      rotationalTransform = CATransform3DTranslate(rotationalTransform, 0, 0, -sideWidth / 2.0);
    }

    return rotationalTransform
  }
}

We call it from our pan-gesture methods

  override func displacementChanged(displacement: CGPoint) {
    guard !(displacement.x == 0 && displacement.y == 0) else { return }

    let rotationTransform = transformedLayer.sublayerTransform.rotationFromDisplacement(displacement, sideWidth: CACube3DView.sideWidth, is3D: isOn)
    transformedLayer.sublayerTransform = rotationTransform
  }

We hooked up the pan-gestures prior:

#if os(OSX)
private func setupPanGestureRecognizer() {
    let panGR = NSPanGestureRecognizer(target: self, action: #selector(handlePanGesture(_:)))
    addGestureRecognizer(panGR)
}
@objc func handlePanGesture(_ gestureRecognizer: NSPanGestureRecognizer) {
    let displacement: CGPoint = gestureRecognizer.translation(in: self)
    handlePan(displacement: displacement, changed: gestureRecognizer.state == .changed)
}
#endif

#if os(iOS) || os(tvOS)
private func setupPanGestureRecognizer() {
    let panGR = UIPanGestureRecognizer(target: self, action: #selector(handlePanGesture(_:)))
    addGestureRecognizer(panGR)
}

@objc func handlePanGesture(_ gestureRecognizer: UIPanGestureRecognizer) {
    let displacement: CGPoint = gestureRecognizer.translation(in: self)

    handlePan(displacement: displacement, changed: gestureRecognizer.state == .changed)

    if gestureRecognizer.state == .changed {
      gestureRecognizer.setTranslation(.zero, in: self)
    }
}
#endif

We can also add a simple rotation transform for the rotation events/ gestures.

  override func rotationChanged(radians: Float) {
    let transform = transformedLayer.sublayerTransform
    let rot = CATransform3DRotate(transform, CGFloat(radians), 0, 1, 0)
    transformedLayer.sublayerTransform = rot
  }

And scale, in all three axes:

  override func scaleChanged(scale: CGFloat) {
    let scaleTransform = CATransform3DScale(transformedLayer.sublayerTransform, scale, scale, scale)
    transformedLayer.sublayerTransform = scaleTransform
  }

The tap turns on and off our 3D transform

  override func tapHappened() {
    set3DCube(on: isOn)
  }

Here’s the 3D cube code

  func set3DCube(on: Bool) {
    side4.layer.zPosition = on ? CACube3DView.sideWidth : 1
    side1.layer.transform = on ? CATransform3D.transformFor3DCubeSide(1, zWidth: CACube3DView.sideWidth) : CATransform3DIdentity
    side2.layer.transform = on ? CATransform3D.transformFor3DCubeSide(2, zWidth: CACube3DView.sideWidth) : CATransform3DIdentity
    side3.layer.transform = on ? CATransform3D.transformFor3DCubeSide(3, zWidth: CACube3DView.sideWidth) : CATransform3DIdentity
    side4.layer.transform = on ? CATransform3D.transformFor3DCubeSide(4, zWidth: CACube3DView.sideWidth) : CATransform3DIdentity
    side5.layer.transform = on ? CATransform3D.transformFor3DCubeSide(5, zWidth: CACube3DView.sideWidth) : CATransform3DIdentity
    side6.layer.transform = on ? CATransform3D.transformFor3DCubeSide(6, zWidth: CACube3DView.sideWidth) : CATransform3DIdentity
  }

We either set the identity transform, which means no transform, to our cube sides, or the transform appropriate for that particular side.

6. macOS Troubles

I suppose I need to do further investigation in how macOS treats layers of NSView, for this little experiment is not working on the macOS, yet.
Here’s how the flattened cube looks on the macOS

So, the positioning of the layers is not respected.

And here is the cube in 3D:

I did try to force the isGeometryFlipped = true everywhere. Anyway this needs more work.

If you want to help with the macOS implementation, please, be my guest.

Here’s a link to a GitHub repo with the source code:
Core Animation 3D Cube