Building Native macOS Apps with Claude Is a Different Beast Than Web Dev
Building Native macOS Apps with Claude Is a Different Beast Than Web Dev
If you have used Claude to build a React app, you know it is remarkably good. Drop in a description, get working code. But try building a native macOS app in Swift and the experience changes completely.
The reason is simple - training data. There are millions of React tutorials, Stack Overflow answers, and open source repos. For AppKit? Maybe a few thousand relevant posts, many of them outdated. SwiftUI is better but still has gaps, especially for macOS-specific features that differ from iOS.
Where Claude Hallucinates
The most common failure mode is Claude inventing APIs that do not exist. It will confidently write NSWindow.setFloatingBehavior(.alwaysOnTop) - a method that sounds right but has never existed. The real approach involves setting window.level to .floating and configuring the collection behavior.
Accessibility APIs are even worse. Claude will suggest AXUIElementCopyAttributeValue calls with attribute names that are close to real ones but slightly wrong. kAXTitleAttribute exists, but Claude sometimes uses kAXLabelAttribute (which does not) or mixes up the attribute constants with their string values.
What Actually Works
The fix is a detailed CLAUDE.md file. Not a generic one - a file that contains actual working code snippets for the patterns your app uses.
Include things like:
- How your app creates and manages windows
- Working accessibility API call patterns with correct attribute names
- SwiftUI view patterns that compile on macOS (not iOS)
- Which APIs require specific entitlements or permissions
When Claude has concrete examples of working code in context, it extends those patterns correctly. Without them, it falls back to interpolating from its training data - and for native macOS, that training data has too many gaps.
The Investment Pays Off
Building the CLAUDE.md takes time upfront. But once it covers your core patterns, Claude can extend them reliably. The second accessibility API wrapper takes 30 seconds. The twentieth SwiftUI view follows the same structure automatically. The key is giving Claude ground truth rather than letting it guess.
Fazm is an open source macOS AI agent. Open source on GitHub.