Cross-Platform Differences for CodexBar CLI Builds: macOS vs Linux Guide

CodexBarCLI ships with different binary packaging, installation methods, and feature capabilities between macOS and Linux, primarily due to macOS-exclusive WebKit integration for browser cookie import and the need for musl versus glibc variants on Linux.

The steipete/CodexBar repository distributes CodexBarCLI as both a bundled helper within the macOS menu-bar app and a standalone command-line tool. While the core Swift codebase compiles across platforms using standard Swift Package Manager commands, the build artifacts, supported features, and installation workflows diverge significantly between Apple's ecosystem and Linux distributions.

Binary Packaging and Architecture Support

Distribution artifacts are platform-specific, reflecting different linker requirements and system library dependencies.

macOS Tarballs

macOS distributes two architecture-specific archives following the naming convention CodexBarCLI-v<version>-macos-arm64.tar.gz and CodexBarCLI-v<version>-macos-x86_64.tar.gz. These binaries link against system Apple frameworks including AppKit and WebKit, as documented in the CLI release section at cli.md#L22-L24.

Linux Variants

Linux ships four distinct artifacts to accommodate different C library implementations:

• glibc builds: CodexBarCLI-v<version>-linux-aarch64.tar.gz and CodexBarCLI-v<version>-linux-x86_64.tar.gz
• static-musl builds: CodexBarCLI-v<version>-linux-musl-aarch64.tar.gz and CodexBarCLI-v<version>-linux-musl-x86_64.tar.gz

According to cli.md#L23-L24, the musl variants provide broader distribution compatibility by embedding the C library, while glibc builds depend on the host system's libc.

Installation Methods and Paths

macOS App-Based Installation

When running the menu-bar app, users can navigate to Preferences → Advanced → Install CLI to automatically create symlinks at /usr/local/bin/codexbar and /opt/homebrew/bin/codexbar. Manual linking is also supported:

ln -sf "/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI" /usr/local/bin/codexbar

Linux Homebrew and Manual Setup

Linux users install via the Homebrew tap steipete/tap/codexbar, which pulls the glibc variant as specified in releasing-homebrew.md#L35-L39. No automatic symlink creation exists from a GUI app; users must manually copy or link the binary:

brew install steipete/tap/codexbar

# Or manual extraction

tar -xzf CodexBarCLI-v1.0.0-linux-x86_64.tar.gz
sudo mv CodexBarCLI /usr/local/bin/codexbar

Build Configuration

Both platforms use the same Swift build command:

swift build -c release --product CodexBarCLI

On macOS, the resulting binary is bundled into CodexBar.app/Contents/Helpers/ by the ./Scripts/package_app.sh script. For Linux static builds, the musl variant requires explicit target specification:

swift build -c release --product CodexBarCLI -target x86_64-unknown-linux-musl

Feature Parity and Limitations

Browser Cookie Import

WebKit-based browser cookie import is macOS-only. On macOS, the web source mode can automatically fall back to browser import using native WebKit APIs. Linux lacks this capability entirely, requiring users to rely on manual cookie configuration or local SQLite usage databases (such as those provided by OpenCode Go).

File System Permissions

When writing configuration or cache files, both platforms set permissions to 0600 for consistency, ensuring sensitive credential data remains accessible only to the owner regardless of operating system.

Runtime Dependencies

macOS binaries depend on Apple-provided system libraries. Linux presents two distinct runtime profiles:

• glibc builds: Require the host system to provide the standard C library
• musl builds: Self-contained with embedded libc, runnable on any Linux distribution without additional packages

Summary

• Packaging: macOS provides two architecture builds; Linux provides four (glibc and musl for both arm64 and x86_64)
• Installation: macOS supports GUI-based symlink creation; Linux relies on Homebrew or manual extraction
• Features: Browser cookie import and automatic web source mode are exclusive to macOS due to WebKit dependency
• Portability: Linux musl builds offer maximum portability by embedding the C library, while glibc builds have external dependencies

Frequently Asked Questions

Can I use browser cookie import on Linux?

No. Browser cookie import requires WebKit frameworks that are only available on macOS. Linux users must configure cookies manually or use local SQLite databases for authentication.

What is the difference between glibc and musl builds for Linux?

glibc builds link against the host system's GNU C Library, requiring compatible system versions. musl builds statically link the musl libc implementation, creating a self-contained binary that runs on any Linux distribution without external dependencies.

How do I install CodexBarCLI manually on macOS without Homebrew?

Extract the appropriate tarball and create a symbolic link to the binary location inside the app bundle:

ln -sf "/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI" /usr/local/bin/codexbar

This bypasses the automatic installation available in the app's Preferences menu.

Why does the Linux version lack automatic symlink creation from the GUI?

The Linux build of CodexBar does not include the menu-bar app helper that manages /usr/local/bin and /opt/homebrew/bin symlinks on macOS. Linux installation requires explicit manual copying or Homebrew formula management, as the platform typically lacks the standardized GUI-to-CLI integration paths available on macOS.

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