Development Setup Guide

Reducing Keychain Permission Prompts

When developing CodexBar, you may see frequent keychain permission prompts like:

CodexBar wants to access key "Claude Code-credentials" in your keychain.

This happens because each rebuild creates a new code signature, and macOS treats it as a "different" app. That can affect both CodexBar-owned entries (com.steipete.CodexBar, com.steipete.codexbar.cache) and third-party items such as Claude Code-credentials, so an ad-hoc-signed rebuild can keep re-triggering password/keychain approval dialogs even after you previously chose Always Allow.

Quick Fix (Temporary)

When the prompt appears, click "Always Allow" instead of just "Allow". This grants access to the current build.

Permanent Fix (Recommended)

Use a stable development certificate that doesn't change between rebuilds:

1. Create Development Certificate

./Scripts/setup_dev_signing.sh

This creates a self-signed certificate named "CodexBar Development".

2. Trust the Certificate

1. Open Keychain Access.app
2. Find "CodexBar Development" in the login keychain
3. Double-click it
4. Expand the "Trust" section
5. Set "Code Signing" to "Always Trust"
6. Close the window (enter your password when prompted)

3. Configure Your Shell

Add this to your ~/.zshrc (or ~/.bashrc if using bash):

export APP_IDENTITY='CodexBar Development'

Then restart your terminal:

source ~/.zshrc

4. Rebuild

./Scripts/compile_and_run.sh

Now your builds will use the stable certificate, and keychain prompts will be much less frequent!

Note: compile_and_run.sh now auto-detects a valid signing identity (Developer ID or CodexBar Development). Set APP_IDENTITY to override the auto-detected choice.

Cleaning Up Old App Bundles

If you see multiple CodexBar *.app bundles in your project directory, you can clean them up:

# Remove all numbered builds
rm -rf "CodexBar "*.app

# The .gitignore already excludes these patterns:
# - CodexBar.app
# - CodexBar *.app/

The build script creates CodexBar.app in the project root. Old numbered builds (like CodexBar 2.app) are created when Finder can't overwrite the running app.

Development Workflow

Standard Build & Run

./Scripts/compile_and_run.sh

This script:

1. Kills existing CodexBar instances
2. Runs swift build (release mode)
3. Runs swift test (all tests)
4. Packages the app with ./Scripts/package_app.sh
5. Launches CodexBar.app
6. Verifies it stays running

When the script falls back to ad-hoc signing, it preserves CodexBar-owned keychain state by default. That means you may still see keychain prompts for existing CodexBar cache entries, but allowing those prompts keeps the cached browser/OAuth state available across normal rebuilds. If you want a clean reset of CodexBar-owned keychain state for an ad-hoc build, run ./Scripts/compile_and_run.sh --clear-adhoc-keychain before relaunching. Third-party keychain items still need stable signing if you want macOS to remember Always Allow across rebuilds.

Quick Build (No Tests)

swift build -c release
./Scripts/package_app.sh

Run Tests Only

swift test

Debug Build

swift build  # defaults to debug
./Scripts/package_app.sh debug

Troubleshooting

"CodexBar is already running"

The compile_and_run script should kill old instances, but if it doesn't:

pkill -x CodexBar || pkill -f CodexBar.app || true

"Permission denied" when accessing keychain

Make sure you clicked "Always Allow" or set up the development certificate (see above).

Multiple app bundles keep appearing

This happens when the running app locks the bundle. The compile_and_run script handles this by killing the app first.

If you still see old bundles:

rm -rf "CodexBar "*.app

App doesn't reflect latest changes

Always rebuild and restart:

./Scripts/compile_and_run.sh

Or manually:

./Scripts/package_app.sh
pkill -x CodexBar || pkill -f CodexBar.app || true
open -n CodexBar.app