ClaudexDual (formerly ClaudeDual) is a macOS desktop app for managing third-party inference profiles, isolated instances, and local proxies for Claude Desktop and Codex. Both clients share a profile list with separate API endpoints and model mappings. Claude Developer Mode can be enabled with one click.
The product is now named ClaudexDual. The GitHub repository URL and internal ClaudeDual identifiers remain unchanged to preserve existing settings, credentials, and updates. When manually upgrading from ClaudeDual, install ClaudexDual.app and remove the old ClaudeDual.app after verifying the new app works; keep your user data.
| Configuration | Logs |
|---|---|
 |
 |
- Independent Running: Launch completely isolated instances from main Claude Desktop via
--user-data-dirparameter - Codex Isolation: Uses a separate
CODEX_HOMEand desktop data directory, preserving existing Codex settings - Status Monitoring: Real-time display of instance running status, PID and more
- One-Click Control: Convenient start/stop control with graceful termination
- Configuration System: Create, edit, copy, delete multiple model configurations
- Flexible Switching: Quick switching between different model providers and settings
- Parameter Customization: Configure separate Claude (Anthropic) and Codex (OpenAI) API base URLs, keys, authentication methods, model names, etc.
- Built-in Proxy: Integrated Python HTTP proxy supporting request forwarding and model name mapping
- Authentication Conversion: Supports multiple authentication methods: Bearer, x-api-key, anthropic-api-key
- Port Adaptation: Automatically detects port conflicts, dynamically allocates available ports
- Seamless Integration: Direct integration with CC-Switch local gateway service
- Independent Configuration: Uses CC-Switch's built-in model mapping and authentication configuration
- Mode Switching: Freely switch between CC-Switch mode and local proxy mode
- Intuitive Interface: Modern SwiftUI interface with real-time status cards
- Developer Mode: One-click enable Claude Desktop Developer Mode
- Log Tracking: Detailed operation logs and status information
open -n -a /Applications/Claude.app --args --user-data-dir=~/Library/Application\ Support/ClaudeDual-3p- Run Claude Desktop in an independent data directory, completely isolated from the main app
- Avoids configuration conflicts, allows running multiple Claude instances simultaneously
The app generates and writes configuration files to the isolated instance's configLibrary/ directory before launching:
Inference Configuration (7595758f-...json):
{
"coworkEgressAllowedHosts": ["*"],
"inferenceProvider": "gateway",
"inferenceGatewayBaseUrl": "http://127.0.0.1:3456/",
"inferenceGatewayApiKey": "claude-dual-local-proxy",
"inferenceGatewayAuthScheme": "bearer",
"inferenceModels": [
"claude-fable-5",
"claude-opus-5",
"claude-sonnet-5",
"claude-haiku-4-5-20251001"
]
}- Request Reception: Proxy server listens on specified port (default 3456)
- Model Mapping: Converts Claude frontend model names to upstream actual model names
- Authentication Processing: Adds appropriate authentication headers based on configuration
- Request Forwarding: Forwards processed requests to upstream API
- Response Return: Streams upstream response back to Claude
When CC-Switch mode is enabled:
- Bypass local proxy, directly point gateway address to CC-Switch service
- No need to duplicate model mapping and authentication in ClaudexDual
- Leverage CC-Switch's advanced routing and load balancing features
- macOS 13.0 or higher
- Claude Desktop or Codex installed, depending on the client you use
- Python 3 for the built-in proxy
- Download the latest released DMG
- Drag to Applications folder
- First run requires allowing in privacy settings
If macOS blocks the app with "unverified developer", run:
sudo xattr -r -d com.apple.quarantine /Applications/ClaudexDual.appClaudexDual checks GitHub Releases at startup. You can also check manually under About → Online Update. When a new version is available:
- Click Download and Install
- ClaudexDual verifies both the asset size and the SHA-256 digest provided by GitHub
- After verification it replaces the app in place and relaunches automatically — no dragging required
If the automatic install cannot proceed (for example the install directory is not writable), ClaudexDual restores the previous version and opens the DMG so you can install manually.
ClaudexDual is a single-file SwiftUI app — no Xcode project required.
# Compile a standalone executable
swiftc -parse-as-library ClaudexDualApp.swift -o ClaudexDual
# Or package a full .app bundle (icon + proxy script + Info.plist)
tools/PackageApp.shRequires macOS 13.0+, Swift toolchain (Xcode Command Line Tools), and Python 3 for the built-in proxy.
- Check Status: Select Claude or Codex and confirm that client is installed; enable Developer Mode when using Claude
- Create Configuration: Add your third-party model provider settings in configuration page
- Select Mode:
- Local Proxy Mode: ClaudexDual manages all configurations
- CC-Switch Mode: Connect to existing CC-Switch service
- Start Instance: Click start button, wait for isolated instance to load
- Start Using: Experience third-party models in the new instance
Claude requires Anthropic Messages compatibility (/v1/messages); Codex requires OpenAI Responses compatibility (/v1/responses). An OpenAI-compatible service that only supports Chat Completions is not sufficient. The local proxy handles mapping and authentication, not conversion between these protocols.
- Claude: configure display aliases and upstream models for Sonnet, Opus, Fable, and Haiku; use Subagent as the fallback target for unmatched models.
- Declare one-million-token context support; actual context availability depends on the upstream service and client.
- Codex: configure an independent local model ID and upstream request model. The client menu may still show
Custom; mapping controls the actual request. - Fetch the provider model list and apply its first model to the selected client with one click.
- Browsing profiles does not proactively read Keychain; leaving the key blank while editing preserves the saved credential.
Customize coworkEgressAllowedHosts to control external domains accessible to Claude.
Through the proxy server, map Claude frontend displayed model names to actual upstream model names.
Use CC-Switch as the upstream gateway when you want model routing, authentication, and load balancing to be managed outside ClaudexDual.
- API keys are stored in macOS Keychain and used to authenticate requests to your configured upstream service
- Isolated instances ensure third-party model configurations don't affect main app
- The local proxy forwards request content to your configured upstream service; its data policies apply
- 第三方模型配置指南 — Full guide to Developer Mode and third-party inference (Chinese)
- Codex 隔离实例 — Share inference profiles while isolating Codex state and desktop data (Chinese)
- 安装说明 — Installation notes (Chinese)
- 发布流程规范 — Release process and versioning rules (Chinese)
Codex uses the OpenAI Responses API (
/v1/responses). An Anthropic-Messages-only upstream will return 404; use an OpenAI Responses-compatible endpoint or gateway for Codex.
Welcome to submit Issues and Pull Requests to improve ClaudexDual!
ClaudexDual lets you easily experience various third-party models in Claude and Codex and enjoy the fun of AI development!