Modular Swift for Agent Apps

When you're building a macOS app that AI agents help develop, the architecture needs to account for how agents work. They operate on files. They read, modify, and create code. If your entire app is one monolithic target, every agent change risks breaking something unrelated.

The fix is modular Swift frameworks with clear boundaries.

The Split

A typical macOS agent app breaks down into at least four frameworks:

• Models - data types, protocols, and pure logic with zero dependencies
• Networking - API clients, WebSocket handlers, and serialization
• Accessibility - everything touching the accessibility tree, permissions, and element inspection
• UI - SwiftUI views, view models, and navigation

Each framework is its own Xcode target with explicit imports. The UI framework depends on Models and Networking. Accessibility depends on Models. Networking depends on Models. Models depends on nothing.

Why Agents Love This

When you tell an AI agent to "add a new API endpoint," it only needs to touch the Networking and Models frameworks. The UI and Accessibility code is untouched, so it can't accidentally break the overlay rendering or the element inspector.

Better yet, you can run multiple agents in parallel - one working on a networking feature, another on a UI change - and they're modifying completely separate targets. The compile step catches any interface mismatches immediately.

Practical Considerations

Keep framework boundaries strict. If you find yourself importing Accessibility into Networking, something is wrong with the design. Use protocols in Models to define interfaces that frameworks implement independently.

The upfront cost of splitting into frameworks is real - maybe a day or two of Xcode configuration. But it pays back quickly when you have AI agents making changes multiple times per day and you need confidence that changes in one area don't cascade into failures elsewhere.

Fazm is an open source macOS AI agent. Open source on GitHub.