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

> Learn how to contribute to the CodexBar project. Follow this developer's guide to fork the repo, implement changes, and submit your pull request.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: how-to-guide
- Published: 2026-07-10

---

**To contribute to the CodexBar project, fork the repository, execute [`./Scripts/compile_and_run.sh`](https://github.com/steipete/CodexBar/blob/main/./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:

```bash
./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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/Providers.swift):

```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:

```swift
// 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>/`:

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

```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:

```bash

# Run all tests

make test

# Or use the dev script

./Scripts/compile_and_run.sh --test

```

Ensure your code passes linting before submission:

```bash
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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/Package.swift): SwiftPM manifest defining targets and dependencies
- [`Sources/CodexBar/CodexBarApp.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/CodexBarApp.swift): Main entry point and app lifecycle
- [`docs/architecture.md`](https://github.com/steipete/CodexBar/blob/main/docs/architecture.md): High-level architecture overview
- [`Scripts/compile_and_run.sh`](https://github.com/steipete/CodexBar/blob/main/Scripts/compile_and_run.sh): Helper script for the development loop

## Summary

- **Fork and clone** the repository, then use [`./Scripts/compile_and_run.sh`](https://github.com/steipete/CodexBar/blob/main/./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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/./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.