marshaljlee/jxrouter

Purpose and Entry Points

JXRouter is a native macOS SwiftUI/AppKit menu-bar proxy for redirecting Claude, OpenAI, Codex, and SDK API traffic to configured remote or local LLM providers. The application entry point is Sources/JXRouter/JXRouterApp.swift; its primary UI and lifecycle controls are in Sources/JXRouter/JXRouterView.swift and Sources/JXRouter/StatusItemManager.swift. Installation builds the Xcode project and installs CLI launchers via install.sh.

UI, Settings, and Persistent State

The settings UI configures providers, model-tier routes, application rules, proxy behavior, and certificate actions. Sources/JXRouter/SettingsView.swift presents this surface, while Sources/JXRouter/ConfigManager.swift owns non-secret configuration. API keys are isolated in the macOS Keychain through Sources/JXRouter/KeychainManager.swift; settings import may seed empty key slots from existing shell configuration. Sources/JXRouter/ClaudeSettingsWriter.swift manages the Claude Code loopback configuration boundary.

Proxy Lifecycle and System Integration

Starting the service creates a local HTTP/HTTPS proxy, defaulting to port 5255. Sources/JXRouter/ProxyManager.swift coordinates lifecycle and settings, and Sources/JXRouter/ProxyServer.swift accepts proxy traffic. Optional system-wide routing is delegated to macOS proxy settings through Sources/JXRouter/SystemProxyManager.swift; per-application policy is represented by Sources/JXRouter/AppRouteRule.swift and identified through Sources/JXRouter/Services/AppIdentifier.swift.

The design explicitly avoids DNS /etc/hosts changes and pf firewall rules. Files named Sources/JXRouter/DNSRedirectionManager.swift remain in the tree but are not part of the documented current routing approach.

Traffic Classification and Relay Boundary

Incoming requests are classified to distinguish targeted AI API traffic from ordinary connections by Sources/JXRouter/RequestClassifier.swift. Requests for supported AI hosts cross the interception/routing pipeline; unrelated HTTP(S) traffic is preserved as an unmodified raw relay through Sources/JXRouter/NetworkRelay.swift. HTTP parsing and outbound request mechanics are concentrated in Sources/JXRouter/HTTPUtils.swift and Sources/JXRouter/CurlClient.swift.

TLS Interception and Trust

TLS termination is restricted to the targeted AI API hosts and depends on a locally trusted CA. Sources/JXRouter/CertificateAuthority.swift creates/manages the CA, Sources/JXRouter/PEMIdentityLoader.swift loads identities, and Sources/JXRouter/MITMHandler.swift handles intercepted TLS sessions. Non-targeted TLS connections instead remain on the relay path; Sources/JXRouter/DirectTLSHandler.swift supports direct tunnel behavior.

Provider Routing and Protocol Translation

Sources/JXRouter/ProviderRouter.swift selects the active provider/model route and executes fallback chains. Provider definitions and validation are separated into Sources/JXRouter/ProviderPresets.swift and Sources/JXRouter/ProviderValidator.swift. The proxy adapts incoming API formats to provider-specific requests via Sources/JXRouter/MessageTranslator.swift, with request/response models in Sources/JXRouter/MessagesRequest.swift and Sources/JXRouter/ProviderResponse.swift; streaming responses are formatted through Sources/JXRouter/SSEFormatter.swift.

Local Models, External Providers, and Observability

Remote providers are external OpenAI- or Anthropic-compatible APIs authenticated by Keychain-held keys. Local backends are discovered and managed by Sources/JXRouter/LocalProviderDetector.swift and Sources/JXRouter/LocalModelManager.swift, covering Ollama and llama.cpp variants. Routing and operational events are recorded in Sources/JXRouter/TrafficLog.swift. The project has no third-party dependency runtime; it is built as a macOS Xcode application in JXRouter.xcodeproj/project.pbxproj.