Switcher

A macOS menu bar app for effortlessly switching Claude Code API configurations

Features • Installation • Usage • Building • Contributing

---

Overview

Switcher is a native macOS menu bar application that helps developers manage multiple Claude Code API configurations. Whether you're switching between the official Anthropic API, third-party proxies, or different model configurations, Switcher makes it seamless with just a click or keyboard shortcut.

The app automatically updates your shell environment variables and injects them into running terminal sessions, so you don't need to restart your terminal or manually source configuration files.

Features

🚀 Quick Switching

• Menu Bar Access: Click the menu bar icon to instantly switch between configurations
• Global Hotkeys:
  • Cmd+Shift+Right Arrow: Switch to next config
  • Cmd+Shift+Left Arrow: Switch to previous config
• Visual Indicators: See which configuration is currently active at a glance

⚙️ Configuration Management

• Store multiple API configurations (auth token, base URL, model settings)
• Add, edit, delete, and activate configurations through an intuitive UI
• Duplicate existing configs for quick setup of similar configurations

🔄 Automatic Environment Updates

• Automatically updates ~/.zshrc with the active configuration
• Terminal Auto-Refresh: Injects new environment variables into running terminal sessions
  • ✅ Terminal.app (macOS built-in)
  • ✅ iTerm2
  • ⚠️ Warp and other terminals: Manual sourcing required
• No need to restart terminals or manually run source ~/.zshrc

🔐 Security

• All configurations stored locally in macOS UserDefaults
• No data is sent to external servers (except your configured Claude API endpoint)
• Sandboxed application with minimal permissions

Installation

Download Pre-built Release

1. Download the latest Switcher-{version}.dmg from the Releases page
2. Open the DMG file
3. Drag Switcher.app to the Applications folder
4. Launch Switcher from your Applications folder

First Launch Notes:

• If you see a Gatekeeper warning, right-click the app and select "Open"
• Or go to System Settings > Privacy & Security > Click "Open Anyway"

Grant Permissions

On first use, macOS will prompt for automation permissions:

• Automation: Allow Switcher to control Terminal, iTerm2, and System Events
• This enables automatic environment variable injection into running terminals

You can manually grant these permissions at: System Settings > Privacy & Security > Automation

Usage

First Time Setup

1. Click the Switcher icon in the menu bar
2. Click the "+" button to add a new configuration
3. Fill in your API details:
   • Name: A friendly name (e.g., "Official API", "Proxy 1")
   • Auth Token: Your Claude API key
   • Base URL: API endpoint (e.g., https://api.anthropic.com)
   • Model (optional): Default model to use
   • Small/Fast Model (optional): Model for quick operations
4. Click Save
5. Double-click the config to activate it (or click the play icon)

Switching Configurations

Via Menu Bar:

• Click the Switcher menu bar icon
• Double-click any configuration to activate it
• Or hover over a config and click the play icon (▶️)

Via Hotkeys:

• Press Cmd+Shift+Right Arrow to switch to the next config
• Press Cmd+Shift+Left Arrow to switch to the previous config

Via Right-Click Menu:

• Right-click the menu bar icon
• Select a configuration from the list
• Or choose "Quit" to exit the app

Environment Variables Managed

Switcher manages the following environment variables in your ~/.zshrc:

export ANTHROPIC_AUTH_TOKEN="your-api-key"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
export ANTHROPIC_MODEL="claude-sonnet-4-5-20250929"  # Optional
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-20250131"  # Optional

These variables are used by Claude Code and other Claude API clients.

Terminal Compatibility

Terminal	Auto-Refresh	Notes
Terminal.app	✅ Yes	Fully supported
iTerm2	✅ Yes	Fully supported
Warp	❌ No	Manual source ~/.zshrc required
VS Code	❌ No	Manual source ~/.zshrc required
Alacritty	❌ No	Manual source ~/.zshrc required

For unsupported terminals, the app will still update ~/.zshrc, but you need to manually run:

source ~/.zshrc

Or restart your terminal to apply the changes.

Building from Source

Prerequisites

• macOS 10.15 (Catalina) or later
• Xcode 14.0 or later
• Apple Developer account (optional, for code signing)

Build Commands

Development Build:

xcodebuild -project Switcher.xcodeproj -scheme Switcher -configuration Release build

Build DMG Installer (Unsigned):

./build-dmg.sh

Build DMG Installer (Signed):

CODE_SIGN_IDENTITY="Developer ID Application: Your Name (TEAM_ID)" ./build-dmg.sh

Clean Build Artifacts:

xcodebuild clean -project Switcher.xcodeproj -scheme Switcher
rm -rf build/ *.dmg dmg-staging/

Distribution Notes

• Unsigned builds will trigger Gatekeeper warnings on other users' computers
• Signed builds require an Apple Developer account ($99/year)
• Notarization is recommended for public distribution (see CLAUDE.md for details)

Architecture

Switcher is built with SwiftUI and follows modern macOS app patterns:

• SwitcherApp.swift: Main app entry point with AppDelegate
• ConfigModel.swift: Configuration data model and persistence logic
• HotKeyManager.swift: Global hotkey registration using Carbon API
• ContentView.swift: SwiftUI views and UI components

Key features:

• Configs stored in UserDefaults with JSON encoding
• AppleScript for terminal command injection
• Popover UI for quick access
• Native menu bar integration

For detailed architecture documentation, see CLAUDE.md.

Contributing

Contributions are welcome! Here's how you can help:

1. Report Bugs: Open an issue with details about the problem
2. Suggest Features: Share your ideas in the issues section
3. Submit Pull Requests: Fork the repo, make your changes, and submit a PR
4. Improve Documentation: Help make the docs clearer and more comprehensive

Development Setup

# Clone the repository
git clone https://github.com/yourusername/switcher.git
cd switcher

# Open in Xcode
open Switcher.xcodeproj

# Or build from command line
xcodebuild -project Switcher.xcodeproj -scheme Switcher build

Adding Terminal Support

To add support for a new terminal that has AppleScript capabilities:

1. Open ConfigModel.swift
2. Add a new case to the SupportedTerminal enum (around line 343)
3. Implement the commandInjectionScript() method for your terminal
4. Test the integration

See CLAUDE.md for detailed instructions.

Troubleshooting

"Not authorized to send Apple events"

Grant automation permissions:

1. Open System Settings > Privacy & Security > Automation
2. Enable Switcher for Terminal, iTerm2, and System Events
3. Restart Switcher

Environment variables not updating in terminal

• Ensure automation permissions are granted
• Check if your terminal is supported (see Terminal Compatibility)
• For unsupported terminals, manually run source ~/.zshrc

Config section in .zshrc got corrupted

1. Open ~/.zshrc in a text editor
2. Manually remove the section between the markers:

   # ========== Claude Code Config - Managed by ClaudeConfigSwitcher ==========
   

3. Restart Switcher (it will recreate the section correctly)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with SwiftUI
• Icon design inspired by macOS design guidelines
• Created for the Claude Code community

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for the Claude Code community

⬆ Back to Top