# CodexBar System Requirements: macOS Compatibility and Build Prerequisites

> Discover CodexBar system requirements including macOS 13 Ventura compatibility Xcode 15 Swift 6 support and native performance on Apple Silicon and Intel Macs.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: getting-started
- Published: 2026-07-07

---

**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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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:

```bash

# 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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/Package.swift)
- **Xcode 15** (Swift 6) is required to build from source, documented in [`docs/DEVELOPMENT_SETUP.md`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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.