How to Contribute to the CodexBar Project: A Complete Developer's Guide

To contribute to the CodexBar project, fork the repository, execute ./Scripts/compile_and_run.sh to enter the development loop, implement your changes in the modular provider architecture under Sources/CodexBarCore/, and submit a pull request after validating with make test and make check.

CodexBar is a macOS-only menu-bar application built in Swift 6+ that aggregates usage-quota information from dozens of AI coding providers. Contributing to this open-source project requires understanding its strict separation between core logic and UI layers, along with its provider-based plugin architecture for fetching usage data.

Setting Up Your Development Environment

Before you can contribute to the CodexBar project, you need to configure your local workspace. The repository uses Swift Package Manager (SwiftPM) alongside an Xcode project for UI development.

Start by forking and cloning the repository. You can open CodexBar.xcodeproj for visual interface work, or use the SwiftPM build scripts for faster iteration. The project requires macOS and Swift 6+ compatibility, utilizing Swift concurrency throughout with strict Sendable conformance and @MainActor hops for UI updates.

Run the development script to build, test, and launch the application in one command:

./Scripts/compile_and_run.sh

For test-only validation without launching the app, append the --test flag or use make test. To ensure code quality before committing, run make check, which executes swiftformat and swiftlint --strict to maintain consistent formatting across the codebase.

Understanding the CodexBar Architecture

The repository follows a strict modular design split between core logic and presentation layers. All background processing lives in Sources/CodexBarCore/, while the SwiftUI/AppKit glue resides in Sources/CodexBar/.

The architecture centers on four key components:

• UsageFetcher (Sources/CodexBarCore/UsageFetcher.swift): Drives the background refresh loop, runs provider probes in parallel using Swift concurrency, and writes aggregated results to the shared store.
• UsageStore (Sources/CodexBar/UsageStore.swift): An @Observable class that holds the latest usage snapshots and drives the status-item UI updates.
• SettingsStore (Sources/CodexBar/SettingsStore.swift): Persists user preferences including enabled providers, refresh cadence, and icon style, notifying UsageFetcher of configuration changes.
• Provider descriptors (Sources/CodexBarCore/Providers/Providers.swift): An enum registering all supported providers and mapping them to their respective fetcher and UI adapter implementations.

The app follows a strict menu-bar app pattern with LSUIElement = true, using NSStatusBar for the icon and maintaining a hidden 1×1 window to keep the SwiftUI lifecycle active.

Adding a New AI Provider

The most common contribution to CodexBar is adding support for a new AI coding provider. This requires touching three specific areas: the core descriptor, the fetch implementation, and the UI adapter.

Step 1: Define the Provider Descriptor

Register your provider in the central enum at Sources/CodexBarCore/Providers/Providers.swift:

public enum Provider: String, CaseIterable {
    // existing cases…
    case newai               // <-- add your case here
}

Step 2: Implement the Fetch Logic

Create a new directory under Sources/CodexBarCore/Providers/<YourProvider>/ and implement the UsageProvider protocol:

// Sources/CodexBarCore/Providers/NewAI/NewAIProvider.swift
import Foundation

public final class NewAIProvider: UsageProvider {
    public func fetchUsage() async throws -> ProviderUsage {
        // Example: HTTP GET request; replace with actual API logic
        let url = URL(string: "https://api.newai.com/v1/usage")!
        let (data, _) = try await URLSession.shared.data(from: url)
        let json = try JSONDecoder().decode(NewAIUsageResponse.self, from: data)
        return ProviderUsage(
            used: json.usedTokens,
            total: json.quotaTokens,
            reset: Date(timeIntervalSince1970: json.resetTimestamp)
        )
    }
}

Step 3: Create the UI Adapter

Map the core data model to the UI representation in Sources/CodexBar/Providers/<YourProvider>/:

// Sources/CodexBar/Providers/NewAI/NewAIProviderAdapter.swift
import CodexBarCore

public struct NewAIProviderAdapter: ProviderAdapter {
    public init() {}

    public func toUsageModel(_ raw: ProviderUsage) -> UsageModel {
        UsageModel(
            provider: .newai,
            used: raw.used,
            total: raw.total,
            resetDate: raw.reset,
            status: raw.used < raw.total ? .ok : .over
        )
    }
}

Step 4: Register in UsageStore

Finally, register the adapter in Sources/CodexBar/UsageStore.swift:

private static let providerAdapters: [Provider: ProviderAdapter] = [
    // …existing mappings…
    .newai: NewAIProviderAdapter()
]

Testing and Validation

Every contribution must include comprehensive test coverage. Add unit tests under Tests/CodexBarTests/ that exercise both the parsing logic and the UI-model conversion.

Run the full validation pipeline using:

# Run all tests

make test

# Or use the dev script

./Scripts/compile_and_run.sh --test

Ensure your code passes linting before submission:

make check

This command runs swiftformat for code formatting and swiftlint --strict to catch style violations.

Submitting Your Contribution

When you contribute to the CodexBar project, documentation is as important as code. Every new provider requires a markdown file in the docs/ directory and an entry in docs/providers.md.

Create a clean pull request with a concise title following the pattern "Add support for [ProviderName] provider". The CI pipeline will automatically run the full validation suite including tests, linting, and build verification.

Key files to reference during development:

• Package.swift: SwiftPM manifest defining targets and dependencies
• Sources/CodexBar/CodexBarApp.swift: Main entry point and app lifecycle
• docs/architecture.md: High-level architecture overview
• Scripts/compile_and_run.sh: Helper script for the development loop

Summary

• Fork and clone the repository, then use ./Scripts/compile_and_run.sh for rapid development iteration.
• Understand the architecture: Core logic lives in Sources/CodexBarCore/, UI adapters in Sources/CodexBar/, connected via UsageStore and UsageFetcher.
• Add providers by updating Providers.swift, implementing UsageProvider in the core layer, and creating a ProviderAdapter for the UI layer.
• Validate changes using make test for unit tests and make check for formatting and linting.
• Document thoroughly: Add provider documentation in docs/ and update the provider list before submitting your PR.

Frequently Asked Questions

What programming language is CodexBar written in?

CodexBar is written in Swift 6+ and uses modern Swift concurrency features including strict Sendable conformance and @MainActor isolation for UI components. The project targets macOS exclusively and uses SwiftUI combined with AppKit for the menu-bar interface.

Do I need a paid Apple Developer account to contribute?

No, you can build and run CodexBar using a free Apple Developer account for local development and testing. However, to test features like Sparkle auto-updates or to distribute builds, you would need a paid membership. The ./Scripts/compile_and_run.sh script handles local signing automatically for development purposes.

How do I test my provider implementation without API keys?

You can write unit tests in Tests/CodexBarTests/ that mock the network layer or use local JSON files to test your parsing logic. The UsageProvider protocol is designed to be testable—inject mock URLSession configurations or create stub implementations that return static ProviderUsage objects to verify your ProviderAdapter mapping logic without requiring live API credentials.

Where should I add unit tests for my changes?

Add unit tests under Tests/CodexBarTests/ following the existing directory structure. Create tests for your provider's parsing logic in a file named <YourProvider>Tests.swift, and include tests for the UI adapter conversion to ensure ProviderUsage objects correctly map to UsageModel instances. Run the full suite with make test before submitting your pull request.

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