convez.ai
AgenteDevOps & InfraestruturaIntermediário
paulrobello

Codex Monitor

paulrobello/codex-monitor

Monitore quotas de IA coding-agents em uma única interface Apple

Ver no GitHub
InicialPluginScore · de 0 a 100

App nativo Apple para monitorar uso de agentes IA em OpenAI Codex, OpenRouter e Claude Code. Exibe janelas de uso, percentuais de cota restante, barras de progresso e contadores de reset, com widgets nativos para macOS e iOS.

Instalação

$npx convez-ai paulrobello/codex-monitor

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Acompanhar consumo de quota de múltiplos provedores IA
  • Visualizar reset countdowns e períodos de uso (5h e semanal)
  • Integrar monitoramento no menu bar do macOS ou homescreen iOS
  • Scripting via CLI para automação de checagens de uso

Veredito

Ferramenta specializada de alta qualidade para devs que usam múltiplos serviços de IA coding. Implementação robusta em Swift 6, autenticação segura (Keychain), widgets nativos e CLI — bem executada, mas nicho.

README

A tradução para o português deste README ainda está na fila.

Codex Monitor

License: MIT Runs on MacOS | iOS Swift 6.0

A native Apple app for monitoring AI coding-agent usage across OpenAI Codex, OpenRouter, and Claude Code. Shows usage windows with remaining quota percentages, progress bars, and reset countdown timers. Built with SwiftUI for macOS and iOS, with WidgetKit home-screen widgets.

Codex Monitor macOS app

Quick Start

Prerequisites

RequirementNotes
macOS 15+Required for the macOS app
iOS/iPadOS 17+Required for the iOS app
XcodeWith iOS/macOS SDKs
XcodeGenbrew install xcodegen
Apple dev teamQMLVG482FY configured for signing

Build and Run

git clone https://github.com/paulrobello/codex-monitor.git
cd codex-monitor
make run

make run generates the Xcode project, builds the macOS app, installs it to ~/Applications/CodexMonitor.app, and launches it.

Install on iPhone

make launch-phone                  # Build, install, and launch on "Pauls iPhone 17"
make launch-phone PHONE_DEVICE="Your Device Name"  # Target a different device

Features

  • Multi-Provider Monitoring — Track OpenAI Codex, OpenRouter, and Claude Code usage from a single app
  • Usage Windows — Shows 5-hour and weekly Codex usage windows with remaining quota percentages
  • Reset Countdowns — Displays reset date/time plus time remaining until quota resets
  • Progress Bars — Visual indicators for usage consumption across all providers
  • WidgetKit Widgets — Home-screen widgets (macOS and iOS) with cached usage and timeline refresh
  • Auto-Refresh — Configurable intervals: 5, 15, 30, or 60 minutes
  • Secure Auth — OAuth credentials stored in Keychain, not in plain-text files
  • macOS Menu Bar — Lives in the menu bar with a dynamic gauge icon showing usage at a glance
  • iOS Device-Code Login — Authenticate via OpenAI device-code flow; clipboard support for easy code entry
  • macOS CLI — codex-usage helper CLI for scripting and terminal-based usage checks

Providers

ProviderAuth MechanismData SourceSnapshot ID
OpenAI CodexOAuth (PKCE on macOS, device-code on iOS) → KeychainAPI: /wham/usage or /api/codex/usageopenai-codex
OpenRouterAPI key in Keychain (or OPENROUTER_API_KEY env)API: openrouter.ai/api/v1/key + /creditsopenrouter
Claude CodeNone (reads local files)Local JSONL tails from ~/.claude/projects/claude-code

UsageProviderClient orchestrates fetching from all enabled providers. CodexMonitorSettings.enabledProviders controls which are active.

Gallery

macOS App

Codex Monitor macOS app

Widget

Codex Monitor widget

Authentication

Codex OAuth

Credentials are stored in the shared Keychain access group QMLVG482FY.net.pardev.CodexMonitor:

service:  net.pardev.CodexMonitor.codex-auth
account:  codex-oauth

Credential lookup order:

  1. CODEX_MONITOR_ACCESS_TOKEN or CODEX_ACCESS_TOKEN environment variables
  2. Codex Monitor Keychain item
  3. Legacy auth.json files (auto-migrated to Keychain and removed)

macOS uses browser-based OAuth with a local callback server (port 1455). iOS uses device-code flow — Safari opens the OpenAI device page, user enters the code, and the app polls for authorization.

OpenRouter

API key lookup order:

  1. OPENROUTER_API_KEY environment variable
  2. Keychain (OpenRouterAPIKeyStore)

Claude Code

No authentication required. Reads the last 2MB of up to 12 most-recent .jsonl session files under ~/.claude/projects/, extracting token counts from type: "assistant" records.

CLI

Build and use the codex-usage CLI:

make refresh                           # Build + fetch current usage

# After building, the CLI is at:
build/DerivedData/Build/Products/Debug/codex-usage login         # Start OAuth login
build/DerivedData/Build/Products/Debug/codex-usage refresh       # Fetch usage + update cache
build/DerivedData/Build/Products/Debug/codex-usage print         # Print cached snapshot
build/DerivedData/Build/Products/Debug/codex-usage cache-path    # Show cache file path
build/DerivedData/Build/Products/Debug/codex-usage clear-auth    # Remove stored credentials
build/DerivedData/Build/Products/Debug/codex-usage interval      # Show refresh interval
build/DerivedData/Build/Products/Debug/codex-usage interval 30   # Set interval to 30 min

Architecture

Codex Monitor uses a shared-core architecture — CodexUsageCore contains all business logic and is linked by every target (macOS app, iOS app, widgets, CLI).

Sources/
├── CodexUsageCore/       Shared auth, usage fetch, cache, settings, formatting
│   ├── CodexUsageCore.swift   Models, clients, auth stores, cache, settings
│   └── CodexOAuth.swift       OAuth PKCE + device-code flows, token refresh, JWT parsing
├── CodexMonitorApp/      macOS SwiftUI app (MenuBarExtra + WindowGroup + Settings)
├── CodexMonitoriOS/      iOS/iPadOS SwiftUI app (NavigationStack + List)
├── CodexMonitorWidget/   WidgetKit extension shared by macOS and iOS
└── CodexUsageCLI/        macOS helper CLI (main.swift)

Tests/
└── CodexUsageCoreTests/  17 unit tests — parsing, JWT, auth, settings, cache

project.yml               XcodeGen project definition (9 targets)
Makefile                  Build, test, install, and launch targets

Data Flow

graph LR
    UI[macOS / iOS UI] --> Store[UsageStore]
    Store --> Provider[UsageProviderClient]
    Provider --> Codex[CodexUsageClient]
    Provider --> OR[OpenRouterUsageClient]
    Provider --> CC[ClaudeCodeUsageClient]
    Codex --> API[OpenAI API]
    OR --> ORAPI[OpenRouter API]
    CC --> Files[Local JSONL Files]
    Codex --> Cache[Usage Cache]
    OR --> Cache
    CC --> Cache
    Cache --> Widget[WidgetKit Timeline]

    style UI fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
    style Provider fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
    style Cache fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
    style Widget fill:#e65100,stroke:#ff9800,stroke-width:2px,color:#ffffff

Build Targets

The XcodeGen project.yml generates 9 targets across macOS and iOS:

TargetTypePlatformDescription
CodexUsageCoreFrameworkmacOSShared business logic
CodexUsageCoreiOSFrameworkiOSShared business logic (iOS build)
CodexMonitorAppmacOSMenu bar app with usage views
CodexMonitoriOSAppiOSNavigationStack + List app
CodexMonitorWidgetExtensionWidget ExtensionmacOSWidgetKit widget
CodexMonitorWidgetiOSExtensionWidget ExtensioniOSWidgetKit widget
codex-usageCLImacOSHelper command-line tool

Development

Build Commands

make generate      # Regenerate Xcode project from project.yml
make build         # Generate + build (CodexMonitor scheme)
make test          # Generate + run tests (CodexUsageCoreTests)
make checkall      # Build + test + lint + fmt + typecheck
make install       # Build + copy .app to ~/Applications/
make run           # Install + launch
make clean         # Remove build/ and .xcodeproj/

No linter or formatter is configured — make lint and make fmt are no-ops.

Shared Data

Usage cache (no credentials):

~/Library/Group Containers/group.net.pardev.CodexMonitor/CodexMonitor/usage.json

Refresh settings:

~/Library/Group Containers/group.net.pardev.CodexMonitor/CodexMonitor/settings.json

Environment overrides:

CODEX_MONITOR_CACHE_PATH       # Override cache file location
CODEX_MONITOR_SETTINGS_PATH    # Override settings file location

Sign In

macOS — Browser OAuth flow with local callback server on port 1455.

iOS/iPadOS — Device-code flow:

  1. Tap Sign In
  2. Safari opens the OpenAI Codex device page
  3. Enter the code shown in the app
  4. Return to Codex Monitor
  5. App polls and stores credentials after authorization

Tap the device code to copy it to the clipboard.

Contributing

  1. Fork the repository and create a feature branch
  2. Run make checkall (build, test, lint, fmt, typecheck) before every commit
  3. Keep commits atomic — one logical change per commit
  4. Submit a pull request with a clear description

Resources

License

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

Author

Paul Robello - probello@gmail.com


Monitor your AI coding-agent usage across Codex, OpenRouter, and Claude Code — from your menu bar, home screen, or terminal.

Ver o original no GitHub

Bom para

Relacionados