mobius: Instructions file for Claude Code

Mobius (뫼비우스) — Claude·Codex 계정 매니저

Claude Code CLI + Claude Desktop + OpenAI Codex CLI 계정을 전환/자동 전환 하는 macOS 메뉴바 앱 + mobius CLI. Swift Package (SwiftUI, macOS 14+). 프로바이더(claude/codex)별 독립 풀 — 각 풀에서 primary 소진 → fallback 자동 전환 → primary 회복 시 자동 복귀. 사용자 노출 용어는 '자동 전환'(구 '자동 fallback').

이 파일은 항상 최신 상태로 유지한다. 구조·핵심 사실·실패 기록이 바뀌면 같은 커밋에서 갱신할 것.

빌드 / 실행

swift test                    # 유닛 테스트 (MobiusCore)
swift build                   # 컴파일 확인
Scripts/make-app.sh           # dist/Mobius.app 번들 조립 + 서명
Scripts/make-dmg.sh           # dist/Mobius-<ver>.dmg 배포 이미지 (드래그 설치)
open dist/Mobius.app          # 실행 (메뉴바 ∞ 아이콘)
Scripts/setup-signing.sh      # (1회) 고정 서명 인증서 생성 — 아래 '서명' 참조

구조

Sources/MobiusCore/       앱·CLI 공유 코어 (전부 의존성 주입 → 테스트 가능)
  MobiusEnvironment.swift  모든 경로 컨테이너 (MOBIUS_HOME/CODEX_HOME 오버라이드)
  Models.swift             Provider / AccountProfile / AccountsFile(프로바이더별 풀) / RateLimitInfo
                           AccountKey(이메일+조직 열쇠 — 계정 대조는 firstIndex(provider:matching:) 한 곳)
  ProviderConfigIO.swift   프로바이더 어댑터 프로토콜 (secret data = 프로바이더 정의 바이트)
  KeychainClient.swift     SystemKeychain + InMemoryKeychain(테스트)
  ClaudeConfigIO.swift     Claude 자격증명 읽기/쓰기 (★ 아래 '진실의 원천' 필독)
  AccountStore.swift       프로필 영속(accounts.json) + 비밀 스냅샷(0600 파일, opaque Data)
  CodexConfigIO.swift      Codex 자격증명 읽기/쓰기 (auth.json 통째 스왑, JWT 신원)
  Switcher.swift           전환/되저장/롤백/reconcile/adopt — 등록된 어댑터 풀 전체에 적용
                           backfillOrganizationUUIDs: 구버전 프로필 조직 채우기(저장 스냅샷 기준)
  RateLimitParser.swift    Claude 세션 로그 rate-limit 이벤트 파서 (실측 기반)
  CodexRateLimitParser.swift Codex rate_limits 상태 파서 (매 턴 in-band, 게이지+소진 판정)
  CodexStatusRouter.swift  Codex 상태의 계정 귀속 — 전환 전 세션 파일 격리 (오염 방지 ★아래)
  SessionLogWatcher.swift  세션 로그 tail — (루트, 파서, 정책) 주입 제네릭 (네트워크 0)
  AutoSwitchEngine.swift   순수 상태머신, 풀당 1인스턴스 (쿨다운/마진/autoSwitchedFromPrimary,
                           on/off는 풀별 autoSwitchByProvider — 기록 없는 풀은 켬; 모델스코프 pin;
                           modelBlocked = 호출자가 usage 캐시로 계산한 "모델 창 소진" 계정 집합)
  UsageFetcher.swift       Claude usage 엔드포인트 조회 (게이지용, 팝오버 열 때만; Codex는 로그로 대체)
                           모델 스코프 주간 한도(weekly_scoped)도 파싱 → ScopedUsageLimit
  UsageRateLimitBackoff.swift usage 엔드포인트 429의 계정별 대기 시각 (모든 조회 경로가 먼저 본다)
  PendingHitTrigger.swift  판정 못 한 창 소진 트리거와 그 갱신 규칙 (hit 신뢰 판정은 도착 순간 한 번)
  SyncEngine.swift         멀티 Mac 동기화 (클라우드 폴더 미러, ★ 아래 '동기화 원칙')
  UpdateChecker.swift      GitHub 릴리스 업데이트 확인 (하루 1회)
Sources/mobius/           CLI (list/switch/status/capture/auto)
Sources/MobiusApp/        SwiftUI 메뉴바 앱 + AppState + Views/ + LoginFlow + DesktopCoordinator