How to Update steipete/CodexBar: Build, Sign, and Release Workflow

To update steipete/CodexBar, pull the latest SwiftPM source, bump version strings in Package.swift and WidgetExtension/Info.plist, run ./Scripts/release.sh to build, sign, and notarize the universal binary, then publish a GitHub release with an updated Sparkle appcast.

CodexBar is a Swift 6 macOS 14+ menu-bar application that aggregates usage, quota, and cost data from dozens of AI coding providers. Updating the project involves three distinct layers: source-level version bumps, automated build-and-sign workflows, and distribution refreshes across GitHub Releases, Sparkle, and Homebrew Cask. This guide walks through the exact files, scripts, and commands required to update steipete/CodexBar from repository pull to verified production release.

Pull the Latest Source and Prepare the Environment

Start by syncing the repository. According to the source code, CodexBar is a SwiftPM-only project with no Xcode workspace to manage.

git clone https://github.com/steipete/CodexBar.git
cd CodexBar
git checkout main
git pull

The modular architecture separates the core logic from the UI, allowing updates to the background UsageFetcher → UsageStore pipeline without touching the menu-bar interface. See docs/architecture.md for the full data flow diagram.

Bump Version Strings and Validate Code

Version numbers appear in three locations that must remain synchronized before building.

1. Package.swift – Update the version constant in the SwiftPM manifest.
2. WidgetExtension/Info.plist – Increment CFBundleShortVersionString for the app bundle version displayed in the UI.
3. CHANGELOG.md – Add human-readable release notes to the top section.

After editing these files, run the formatting and linting checks enforced by the CI pipeline:

swiftformat Sources Tests
swiftlint --strict
make check   # Runs both tools sequentially

Regenerate Assets and Build the Release

If the application icon changed, regenerate the .icns bundle before building:

./Scripts/build_icon.sh Icon.icon CodexBar

This script uses Xcode’s ictool under the hood. Next, execute the automated release pipeline:

./Scripts/release.sh

Internally, this script performs four critical steps:

• Universal build – Compiles swift build -c release for both arm64 and x86_64 architectures.
• Packaging – Assembles CodexBar.app with the Sparkle framework and regenerated icon.
• Deep signing – Applies codesign --deep --timestamp to ensure macOS 14+ compatibility.
• Notarization – Submits the zip to Apple’s notarization service and staples the returned ticket.

For manual control over signing without the full pipeline, use ./Scripts/sign-and-notarize.sh directly.

Generate and Verify the Sparkle Appcast

Sparkle delivers automatic updates by reading an XML feed. Generate the new appcast entry pointing to your signed zip:

./Scripts/make_appcast.sh CodexBar-macos-universal-0.4.2.zip \
  https://raw.githubusercontent.com/steipete/CodexBar/main/appcast.xml

The script generates an edSignature using the private Sparkle key stored in .mac-release.env. Verify the entry resolves correctly before publishing:

./Scripts/verify_appcast.sh 0.4.2

Publish the Release and Refresh Distribution Channels

Create a GitHub release with the semantic tag (e.g., v0.4.2) and attach the following assets:

• CodexBar-macos-universal-0.4.2.zip (the notarized application bundle)
• CodexBar-macos-universal-0.4.2.dSYM.zip (debug symbols for crash reporting)
• CLI tarballs for Linux and macOS (built automatically by the CI workflow)

Copy the release notes verbatim from the top section of CHANGELOG.md.

Refresh Homebrew Cask

The CI workflow automatically updates ../homebrew-tap/Casks/codexbar.rb to point at the new zip. Verify the distribution path works:

brew uninstall --cask codexbar || true
brew tap steipete/tap
brew install --cask codexbar

Validate CLI and Sparkle Updates

Confirm the CLI binary reflects the new version:

codexbar --version

Test the Sparkle update path by keeping an older CodexBar.app in /Applications, launching it, and confirming it prompts to download the new version. For manual testing of the data pipeline, trigger a refresh that bypasses the standard SettingsStore cadence:

codexbar refresh --provider all

Testing Updates via the Command Line

The CLI in Sources/CodexBarCLI reuses the same UsageStore as the GUI, ensuring parity between versions. Test provider configuration after updating:

codexbar config enable --provider openai
codexbar config set-api-key --provider openai --stdin <<<"$OPENAI_API_KEY"

Validate cost aggregation matches the UI:

codexbar cost --provider codex

Summary

• Synchronize versions in Package.swift, WidgetExtension/Info.plist, and CHANGELOG.md before building.
• Automate the build with ./Scripts/release.sh to generate universal binaries, apply deep code signing, and staple Apple notarization tickets.
• Update Sparkle using ./Scripts/make_appcast.sh and verify signatures with ./Scripts/verify_appcast.sh.
• Distribute via GitHub Releases and verify Homebrew Cask updates with brew install --cask codexbar.
• Test the CLI using commands like codexbar refresh --provider all to ensure the UsageFetcher → UsageStore pipeline functions correctly after the update.

Frequently Asked Questions

What files must be edited to bump the version in CodexBar?

You must update three files: Package.swift (SwiftPM version constant), WidgetExtension/Info.plist (CFBundleShortVersionString), and CHANGELOG.md (release notes). These are verified during the build process and displayed in the application’s About panel.

How does the automated release script differ from manual signing?

./Scripts/release.sh orchestrates the entire workflow—building universal binaries, packaging the app, applying codesign --deep --timestamp, notarizing with Apple, and generating the Sparkle appcast. Manual signing via ./Scripts/sign-and-notarize.sh handles only the signing and notarization steps, requiring you to manage builds and appcast generation separately.

Where does CodexBar store usage data during updates?

The background UsageFetcher writes snapshot data to UsageStore, which both the menu-bar UI (Sources/CodexBar) and CLI (Sources/CodexBarCLI) read. Updating the app preserves this data in the user’s keychain and app group containers, ensuring continuity across versions.

Can I build CodexBar without Apple notarization?

You can compile a local debug build using swift build, but distributing or updating the application requires notarization for macOS 14+ compliance. The ./Scripts/release.sh script automates notarization using credentials stored in .mac-release.env, which is required for Sparkle auto-updates to function on Gatekeeper-enabled systems.

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