{"id":47712248,"url":"https://github.com/irons163/codex-pool-manager","last_synced_at":"2026-06-08T08:00:55.580Z","repository":{"id":347750941,"uuid":"1195059022","full_name":"irons163/codex-pool-manager","owner":"irons163","description":"A macOS app for managing multiple Codex accounts, switching active auth quickly, and tracking usage in one dashboard.","archived":false,"fork":false,"pushed_at":"2026-05-15T09:15:22.000Z","size":31939,"stargazers_count":23,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-15T11:28:10.634Z","etag":null,"topics":["account-management","account-switcher","ai","aitools","chatgpt","codex","codex-tools","desktop-app","macos","openai"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/irons163.png","metadata":{"files":{"readme":"README.es.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T06:47:50.000Z","updated_at":"2026-05-15T09:08:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/irons163/codex-pool-manager","commit_stats":null,"previous_names":["irons163/codex-pool-manager"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/irons163/codex-pool-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irons163%2Fcodex-pool-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irons163%2Fcodex-pool-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irons163%2Fcodex-pool-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irons163%2Fcodex-pool-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/irons163","download_url":"https://codeload.github.com/irons163/codex-pool-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irons163%2Fcodex-pool-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34053435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["account-management","account-switcher","ai","aitools","chatgpt","codex","codex-tools","desktop-app","macos","openai"],"created_at":"2026-04-02T18:39:41.950Z","updated_at":"2026-06-08T08:00:55.501Z","avatar_url":"https://github.com/irons163.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codex Pool Manager\n\n\u003cp\u003e\u003cimg src=\"docs/images/app-icon.png\" alt=\"Codex Pool Manager Icon\" width=\"96\" /\u003e\u003c/p\u003e\n\nCodex Pool Manager es una app para macOS para operar un pool de cuentas Codex/OpenAI OAuth desde un solo panel de control.\n\nTe ayuda a:\n- seguir cuota y restante por cuenta,\n- cambiar rápido la cuenta activa,\n- rotar cuentas automáticamente con política inteligente,\n- monitorear estado desde Widget y barra de menú,\n- mantener flujos de backup/export para recuperación.\n\nIdiomas: [English](README.md) · [繁體中文](README.zh-Hant.md) · [简体中文](README.zh-Hans.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md)\n\n## Índice\n\n1. [Capturas](#capturas)\n2. [Funciones clave](#funciones-clave)\n3. [Cómo funciona el cambio inteligente](#cómo-funciona-el-cambio-inteligente)\n4. [Widget + barra de menú](#widget--barra-de-menú)\n5. [Comprobación de actualizaciones integrada](#comprobación-de-actualizaciones-integrada)\n6. [Autenticación e importación de cuentas](#autenticación-e-importación-de-cuentas)\n7. [Espacios de trabajo](#espacios-de-trabajo)\n8. [Instalación](#instalación)\n9. [Compilar desde código fuente](#compilar-desde-código-fuente)\n10. [Pipeline de Release DMG](#pipeline-de-release-dmg)\n11. [Estructura del proyecto](#estructura-del-proyecto)\n12. [Pruebas](#pruebas)\n13. [Solución de problemas](#solución-de-problemas)\n14. [Notas de seguridad y privacidad](#notas-de-seguridad-y-privacidad)\n15. [Contribuir](#contribuir)\n\n## Capturas\n\nTodas las capturas usan datos mock o no sensibles.\n\n### Dashboard principal (Dark, Mock)\n\n![Main Dashboard (Dark, Mock Data)](docs/images/app-screenshot.png)\n\n### Resumen superior (Light, Mock)\n\n![Header Overview (Light, Mock Data)](docs/images/dashboard-light.png)\n\n### Estado en barra de menú (Mock)\n\n![Menu Bar Status](docs/images/menu-bar.png)\n\n### Widget (estado vacío, Mock)\n\n![Widget Empty State](docs/images/widget-empty-state.png)\n\n### OpenAI Reset Alert (Mock)\n\n![OpenAI Reset Alert](docs/images/openai-reset-alert.png)\n\n## Funciones clave\n\n### 1) Gestión del pool de cuentas\n\n- Agregar, editar, duplicar y eliminar cuentas.\n- Gestionar grupos (`Add`, `Rename`, `Delete`).\n- Al borrar un grupo, se eliminan también sus cuentas.\n- Orden y layouts para pools grandes.\n- El layout `Minimal` usa ancho de tarjeta adaptable y ajusta automáticamente cuántas columnas caben según el ancho de la ventana.\n- Estadísticas (`Accounts`, `Available`, `Pool Usage`) con deduplicación para evitar doble conteo.\n\n### 2) Múltiples modos de cambio\n\n- `Intelligent`: selecciona automáticamente la mejor cuenta según capacidad restante y umbrales.\n- `Manual`: mantiene la cuenta elegida manualmente.\n- `Focus`: fija la cuenta actual y desactiva la rotación inteligente.\n\n### 3) Sync de uso y diagnóstico\n\n- Sincroniza uso de Codex/OpenAI para cuentas elegibles.\n- Maneja exclusiones de sync (token faltante, account id faltante, error API/red).\n- Muestra hora del último sync exitoso y detalles de error.\n- Incluye JSON de uso en bruto y logs de cambio para diagnóstico.\n\n### 4) Flujos OAuth sign-in\n\n- OAuth sign-in dentro de la app e importación directa.\n- Flujo manual: copiar URL de autorización, pegar URL callback e importar.\n- Descubrimiento local de auth en rutas comunes.\n- Importa OAuth sessions/accounts locales al pool administrado.\n\n### 5) Integración de escritorio\n\n- Notificaciones nativas macOS (fallo/recuperación de sync, low usage, auto-switch).\n- Extra de barra de menú con resumen en vivo del restante.\n- Widget de macOS para vistazo rápido.\n\n### 6) Backup y restore\n\n- Exportar snapshot JSON.\n- Exportar snapshot refetchable (sensible; incluye campos para re-fetch).\n- Importar snapshot JSON para migración/recuperación.\n\n### 7) UI y localización\n\n- Dark mode + Light mode.\n- Cambio de idioma desde settings.\n- Formato de tiempo según locale en app/widget.\n\n### 8) Analítica de uso y planificación en Schedule\n\n- Workspace `Schedule` para planificar resets entre múltiples cuentas.\n- Análisis diario/semanal de uso para entender hábitos de consumo.\n- Vista de cobertura para detectar ventanas sin cobertura entre resets.\n- Líneas de tendencia por cuenta, eventos de umbral y resumen de anomalías.\n- Exportación de analítica en JSON/CSV.\n\n### 9) Monitoreo de reset de OpenAI\n\n- Workspace dedicado `OpenAI Reset Alert` para cuentas de pago.\n- Monitorea juntos reset semanal y reset de 5 horas.\n- Detecta reset anticipado (con tolerancia configurable).\n- Notificaciones desktop e historial de eventos.\n- Límite diario de notificaciones para reducir ruido por falsos positivos en periodos de inestabilidad de API.\n\n## Cómo funciona el cambio inteligente\n\n### Elegibilidad de cuentas\n\nSolo cuentas **no excluidas de sync/scheduling** se consideran para cambio automático.\n\nRazones típicas de exclusión:\n- falta API token,\n- falta ChatGPT account id,\n- estado de error de sync.\n\n### Lógica paid vs no-paid\n\n- Cuenta no pagada: usa ratio restante semanal (`remainingUnits / quota`).\n- Cuenta pagada (por defecto): usa **restante de 5 horas**.\n- Caso especial pagada: si restante semanal = `0%`, se toma semanal como referencia.\n\n### Selección de candidato\n\nEl motor elige el mejor candidato por mayor ratio restante inteligente.\n\nCuentas con restante semanal `\u003c= 0` no son elegibles.\n\n### Condiciones de disparo\n\nEn modo `Intelligent`, solo cambia si se cumplen todas:\n\n1. hay candidato válido,\n2. la cuenta activa está bajo el umbral,\n3. el candidato es mejor que la actual,\n4. expiró el cooldown.\n\n### Comportamiento Focus\n\nEn `Focus`, la cuenta actual queda fijada.\n\nNo hay auto-switch inteligente en Focus.\n\n### Umbral low-usage separado\n\nHay dos umbrales independientes:\n\n- umbral inteligente: **cuándo se permite cambiar**,\n- umbral de low remaining alert: **cuándo mostrar aviso/notificación**.\n\n## Widget + barra de menú\n\n### Widget\n\n- Lee snapshot desde un bridge local expuesto por la app principal.\n- Si no hay snapshot, muestra estado vacío amigable.\n- Política de refresh:\n  - ~`60s` con snapshot,\n  - ~`10s` sin snapshot.\n\n### Barra de menú\n\n- Título compacto con estado (restante %, paid 5h left, edad de actualización).\n- Menú con detalles de cuenta activa, resets y edad de actualización.\n- Refresh periódico (~15s) y refresh manual.\n\n## Comprobación de actualizaciones integrada\n\n- Consulta la última Release de GitHub y la compara con la versión actual.\n- Normaliza formatos de versión (por ejemplo `v1.8.0` y `1.8.0`).\n- Selecciona preferentemente el instalador según arquitectura (`Apple Silicon` / `Intel`) cuando exista.\n- El diálogo de actualización ofrece `Install now`, `Manual download` y `Skip this version`.\n\n## Autenticación e importación de cuentas\n\n### Rutas de descubrimiento local\n\n- `~/.codex/auth.json`\n- `~/.config/codex/auth.json`\n- `~/.openai/auth.json`\n\n### Public OAuth client\n\nPor defecto soporta flujo de public client y también parámetros de tu propio OAuth client.\n\n### Flujo callback manual\n\nSi el callback del navegador no puede completarse dentro de la app:\n\n1. clic en `Copy URL and Manual sign in`,\n2. completar sign-in en navegador,\n3. pegar callback URL,\n4. clic en `Import`.\n\n## Espacios de trabajo\n\n### Authentication\n\n- panel OAuth sign-in\n- Advanced OAuth parameters\n- escaneo/import de cuentas OAuth locales\n\n### Runtime Strategy\n\n- selector de modo (`Intelligent`, `Manual`, `Focus`)\n- umbral de cambio inteligente\n- umbral de low-usage alert\n- selección de app objetivo para `Switch and launch`\n- panel de recomendación\n\n### Schedule\n\n- vista timeline de resets para cuentas gestionadas\n- resumen analítico diario/semanal de uso\n- detección de gaps de cobertura para planificar mejor\n- líneas por cuenta y eventos de umbral/anomalías\n- exportación de analítica (`Copy JSON`, `Export CSV`, `Export JSON`)\n\n### OpenAI Reset Alert\n\n- tracking de objetivos de reset en cuentas de pago\n- configuración de tolerancia de early-reset\n- resumen y registros de señales detectadas\n- alertas desktop y gestión de eventos\n\n### Settings\n\n- comportamiento al iniciar\n- toggle e intervalo de auto-sync\n- idioma\n- apariencia (system/dark/light)\n\n### Safety\n\n- controles de backup/export/import\n- superficie de diagnóstico para datos/logs en bruto\n\n## Instalación\n\n### Opción A: Descargar DMG prebuild desde Releases\n\n- `CodexPoolManager-\u003cversion\u003e-apple-silicon.dmg`\n- `CodexPoolManager-\u003cversion\u003e-intel.dmg`\n\nElige el DMG según la arquitectura de tu Mac.\n\n### Opción B: Ejecutar desde código fuente en Xcode\n\nVer siguiente sección.\n\n## Compilar desde código fuente\n\n### Requisitos\n\n- macOS\n- Xcode 16+\n\n### Pasos\n\n```bash\ncd /path/to/AIAgentPool\nopen CodexPoolManager.xcodeproj\n```\n\nEn Xcode:\n\n1. seleccionar el scheme `CodexPoolManager`,\n2. elegir tu Mac local como destination,\n3. Build and Run.\n\nSi también pruebas widget, firma los targets relacionados con la misma Team.\n\n## Pipeline de Release DMG\n\nEmpaquetado DMG + notarization automatizado en:\n\n- `.github/workflows/release-dmg.yml`\n- `scripts/build_and_notarize_dmg.sh`\n\n### Puntos clave\n\n- build de `arm64` y `x86_64`,\n- nombre de artifacts por versión/tag release (no hash),\n- firma con certificado Developer ID Application,\n- notarize + staple para cada DMG,\n- upload a artifacts de workflow y assets de GitHub Release.\n\n### GitHub secrets requeridos\n\n- `APPLE_CERTIFICATE_P12_BASE64`\n- `APPLE_CERTIFICATE_PASSWORD`\n- `KEYCHAIN_PASSWORD`\n- `APPLE_TEAM_ID`\n- `APPLE_API_KEY_ID`\n- `APPLE_API_ISSUER_ID`\n- `APPLE_API_PRIVATE_KEY_BASE64`\n\nPara setup detallado, ver [RELEASE_DMG.md](RELEASE_DMG.md).\n\n## Estructura del proyecto\n\n```text\nAIAgentPool/\n├─ CodexPoolManager/                 # target principal macOS app\n├─ CodexPoolWidget/                  # target widget extension\n├─ CodexPoolWidgetHost/              # host companion para bridge/tests del widget\n├─ Domain/Pool/                      # estado core, reglas de switch, snapshot model\n├─ Features/PoolDashboard/           # UI + coordinadores de flujo\n├─ Infrastructure/Auth/              # OAuth, acceso a auth file, servicios de switch\n├─ Infrastructure/Usage/             # cliente/servicio de sync de uso\n├─ CodexPoolManagerTests/            # tests unitarios\n├─ CodexPoolManagerUITests/          # tests UI\n├─ .github/workflows/release-dmg.yml # workflow release\n└─ scripts/build_and_notarize_dmg.sh # script DMG local/CI\n```\n\n## Pruebas\n\nEn Xcode o por línea de comandos:\n\n```bash\nxcodebuild \\\n  -project CodexPoolManager.xcodeproj \\\n  -scheme CodexPoolManager \\\n  -destination 'platform=macOS' \\\n  test\n```\n\nBuild en configuración Release:\n\n```bash\nxcodebuild \\\n  -scheme CodexPoolManager \\\n  -destination 'platform=macOS' \\\n  -configuration Release \\\n  build\n```\n\nComprobación básica de archivos de localización:\n\n```bash\nfor f in CodexPoolManager/en.lproj/Localizable.strings \\\n         CodexPoolManager/zh-Hans.lproj/Localizable.strings \\\n         CodexPoolManager/zh-Hant.lproj/Localizable.strings; do\n  plutil -lint \"$f\"\ndone\n```\n\n## Solución de problemas\n\n### \"Syncing...\" se queda bloqueado\n\n- Confirmar disponibilidad de red/API.\n- Revisar callout de Sync Error.\n- Verificar token y account id válidos en cuentas activas.\n- Reintentar sync manual tras unos segundos.\n\n### Widget muestra \"No snapshot available\"\n\n- Abrir CodexPoolManager al menos una vez (la app principal publica el bridge).\n- Esperar unos segundos y refrescar widget.\n- Verificar que firewall/reglas de red no bloqueen localhost loopback.\n\n### El escaneo OAuth local no encuentra nada\n\n- Usar `Choose auth.json` y conceder permiso manualmente.\n- Verificar que exista auth en una de las rutas conocidas.\n\n### No cambia cuenta en modo Intelligent\n\n- Revisar si la cuenta actual está bajo el umbral.\n- Revisar intervalo de cooldown.\n- Revisar elegibilidad de candidatos y valores restantes.\n- En Focus, el cambio inteligente está desactivado por diseño.\n\n## Notas de seguridad y privacidad\n\n- Los exports refetchable pueden incluir datos sensibles.\n- No compartas logs/exports en bruto sin redacción.\n- Guarda snapshots internos en almacenamiento seguro.\n- Maneja credenciales OAuth/client según tu política de seguridad.\n\n## Contribuir\n\nIssues y PRs bienvenidos.\n\nAlcance recomendado de PR:\n- un cambio de comportamiento por PR,\n- cobertura de tests para lógica de domain/coordinator,\n- capturas before/after para cambios de UI.\n\n---\n\nSi este proyecto te ayuda, considera darle una estrella al repo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firons163%2Fcodex-pool-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Firons163%2Fcodex-pool-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firons163%2Fcodex-pool-manager/lists"}