CodexBar System Requirements: macOS Compatibility and Build Prerequisites

CodexBar requires macOS 13 Ventura or newer, Xcode 15 with Swift 6, and runs natively on both Apple Silicon and Intel Macs.

CodexBar is a native macOS menu-bar application written in Swift 6. To install or build the app from the steipete/CodexBar repository, your system must meet specific operating system, hardware, and toolchain requirements defined in the project's Package.swift and accompanying documentation.

Minimum Hardware and Software Requirements

The following specifications represent the baseline environment needed to run CodexBar:

Requirement	Details
Operating System	macOS 13 Ventura or newer (tested on macOS 14 Sonoma)
CPU Architecture	Universal binary supporting Apple Silicon (ARM64) and x86_64
Swift Toolchain	Swift 6 (bundled with Xcode 15+)
Xcode Command-Line Tools	Required for building from source via swift build

Operating System Support

According to the Package.swift file in the repository root, CodexBar explicitly targets macOS 13 as its minimum platform version. The Swift package manifest declares platform constraints that prevent compilation on earlier macOS versions. While the app is tested primarily on macOS 14 Sonoma, macOS 13 Ventura provides the necessary AppKit and MenuBar APIs required for the menu-bar functionality.

CPU Architecture Support

CodexBar ships as a universal binary containing both arm64 and x86_64 slices. While the application runs on Intel-based Macs, the best experience is on Apple Silicon (M1, M2, M3, and later). The architecture documentation in docs/architecture.md confirms the app is optimized for ARM64 but maintains compatibility with x86_64 through universal binary packaging.

Swift Toolchain and Xcode Requirements

The Package.swift file specifies Swift 6 as the language version, which requires Xcode 15 or newer. For development or building from source, you must install the Xcode Command-Line Tools to access the swift compiler and build system. The docs/DEVELOPMENT_SETUP.md file documents that Xcode 15 is the minimum supported version for compilation.

Required Frameworks and Permissions

Built-in macOS Frameworks

CodexBar relies exclusively on system frameworks bundled with macOS. As detailed in docs/architecture.md, the application uses AppKit for the user interface, MenuBar-specific APIs for the status bar integration, and Sparkle for automatic updates. These frameworks are part of the standard macOS SDK, meaning no additional third-party libraries are required at runtime.

Keychain and Accessibility Permissions

The application reads from the macOS Keychain to retrieve API tokens, as documented in docs/KEYCHAIN_FIX.md. On first launch, CodexBar may request permission to access the Keychain item storing your credentials. Additionally, if you configure menu-bar shortcuts, the app may request accessibility permissions to register global hotkeys. No network ports need to be opened for standard operation.

Building from Source

To verify your system meets all requirements and build CodexBar locally, run the following commands in Terminal:

# Install Xcode Command-Line Tools (if not already installed)

xcode-select --install

# Clone the repository

git clone https://github.com/steipete/CodexBar.git
cd CodexBar

# Build and run the debug build

swift build
swift run CodexBar

These steps assume you are running macOS 13 or newer with the Swift 6 toolchain available. The swift build command references the Package.swift manifest to verify platform compatibility before compilation. After successful execution, the app appears as an icon in the system menu bar.

Optional CLI Dependencies

If you enable the codexbar command-line interface, ensure a compatible Swift runtime is available on your $PATH. While the GUI application bundles its own runtime dependencies, CLI usage requires the host system to resolve Swift runtime libraries for shell execution.

Summary

• macOS 13 Ventura is the minimum supported operating system, as defined in Package.swift
• Xcode 15 (Swift 6) is required to build from source, documented in docs/DEVELOPMENT_SETUP.md
• The app uses standard AppKit and Sparkle frameworks with no external runtime dependencies
• Keychain access is required for API token storage, with optional accessibility permissions for shortcuts
• Universal binary supports both Apple Silicon and Intel Macs, though ARM64 is recommended

Frequently Asked Questions

Can I run CodexBar on macOS 12 Monterey?

No. The Package.swift file explicitly sets the platform minimum to macOS 13, and the codebase relies on MenuBar APIs introduced in Ventura. Attempting to build or run the app on macOS 12 will result in compilation errors or runtime failures due to missing system framework support.

Does CodexBar work on Intel-based Macs?

Yes. Although optimized for Apple Silicon, CodexBar ships as a universal binary supporting both arm64 and x86_64 architectures. Intel Macs running macOS 13 or newer can run the application, though performance characteristics are best on ARM64 hardware.

Do I need to install additional libraries to run CodexBar?

No. The application uses only built-in macOS frameworks including AppKit and Sparkle. As noted in docs/architecture.md, all dependencies are either bundled with the macOS SDK or statically linked, requiring no separate package managers or third-party installations.

Why does CodexBar request Keychain access?

The app stores API tokens securely in the macOS Keychain rather than in plain text files. According to docs/KEYCHAIN_FIX.md, this permission is necessary to read and write credential data. The request appears only when the app attempts to access stored tokens for the first time.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}