TokenMaxxing

An iPhone app and WidgetKit extension for checking Codex and Claude allowance without opening each provider.

TokenMaxxing shows rolling and weekly usage windows, reset times, freshness, and model-specific limits such as Claude Fable. Provider credentials stay in the device Keychain; widgets receive only cached percentages and reset dates.

Features

• Independent Codex and Claude connections.
• Codex device-code authentication on OpenAI’s website.
• Experimental Claude browser OAuth flow.
• Five-hour, daily, weekly, and model-scoped allowance windows.
• Dynamic duration labels such as 5-hour, 2-day, and 1-week.
• Claude Fable scoped-limit support.
• Home Screen widgets in small and medium sizes.
• Codex-only and Claude-only widgets.
• Lock Screen inline, circular, and rectangular widgets.
• Cached offline state with refresh timestamps.
• Shared Keychain credentials and App Group snapshots.
• Native SwiftUI accessibility and system appearance support.

Requirements

• macOS with Xcode 26 or newer.
• iOS 18 or newer.
• An Apple Account configured in Xcode.
• A development team that supports App Groups and Keychain Sharing.
• A physical iPhone with Developer Mode enabled, or an iOS Simulator.

The checked-in Xcode project is ready to open directly. XcodeGen is optional and is only needed when regenerating the project from project.yml.

Local setup

git clone git@github.com:anuragts/tokenmaxxing.git
cd tokenmaxxing
open TokenMaxxing.xcodeproj

In Xcode:

1. Select the TokenMaxxing project.
2. For both TokenMaxxing and TokenMaxxingWidgets, open Signing & Capabilities.
3. Select the same development team and keep Automatically manage signing enabled.
4. Replace the bundle identifiers with values unique to your Apple team.
5. Create one App Group and select it for both targets.
6. Keep the same Keychain Sharing group on both targets.
7. Select an iPhone or simulator and press Run.

The repository currently uses the com.anurag.tokenmaxxing identifier family. Forks should replace it consistently:

rg -n "com\\.anurag" project.yml Config Shared TokenMaxxing TokenMaxxingWidgets TokenMaxxing.xcodeproj

Update the App Group in Shared/AppConstants.swift to match the capability selected in Xcode. If a free Personal Team cannot provision the App Group, use an Apple Developer Program team that supports the capability.

Optional project regeneration

brew install xcodegen
xcodegen generate

Testing

Run the unit suite without code signing:

xcodebuild test \
  -project TokenMaxxing.xcodeproj \
  -scheme TokenMaxxing \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.1' \
  -derivedDataPath .derivedData \
  CODE_SIGNING_ALLOWED=NO

Change the simulator name or OS version to one installed on your Mac. The tests cover provider decoding, transient authentication failures, percentage normalization, dynamic duration labels, Fable scoped limits, cache persistence, and stale-state behavior.

Installing on an iPhone

1. Connect and unlock the iPhone.
2. Trust the Mac if prompted.
3. Enable Developer Mode under Settings → Privacy & Security.
4. Select the iPhone as Xcode’s run destination.
5. Build and run the TokenMaxxing scheme.

After installation, open TokenMaxxing and connect either provider. The connections are independent, so one provider can continue working if the other needs authentication.

Adding widgets

• Home Screen: long-press the Home Screen → Edit → Add Widget → TokenMaxxing.
• Lock Screen: long-press the Lock Screen → Customize → select the widget area → TokenMaxxing.
• Add provider-only widgets to a Smart Stack to swipe between Codex and Claude.

Widget refresh timing is controlled by iOS and is not an exact background timer. Every surface includes freshness or stale-state information.

Architecture

TokenMaxxing/          SwiftUI app, provider cards, and login flows
TokenMaxxingWidgets/   Home Screen and Lock Screen widgets
Shared/                Provider APIs, models, storage, and formatting
TokenMaxxingTests/     Decoder, model, and persistence tests
Config/                App Group and Keychain entitlements
Design/                Editable icon source and provider-mark notes

The app normalizes provider-specific responses into UsageWindow snapshots. OAuth credentials are stored in the shared Keychain access group. Only non-secret normalized snapshots are written to the App Group for WidgetKit.

Privacy and provider compatibility

• TokenMaxxing never asks for or stores provider passwords.
• Access and refresh tokens are stored in Keychain, not UserDefaults.
• Tokens are not copied into widget snapshots or logs.
• Codex authentication is completed on OpenAI’s website.
• Claude support is marked experimental in the app.

The usage endpoints consumed by TokenMaxxing are product-client contracts, not stable public third-party APIs. OpenAI or Anthropic may change them without notice. This project is not affiliated with, endorsed by, or sponsored by OpenAI or Anthropic. Product names and marks belong to their respective owners.

Development notes

• Deployment target: iOS 18.
• UI: SwiftUI.
• Widgets: WidgetKit.
• Credential storage: Security framework / Keychain.
• Shared cache: versioned JSON in an App Group.
• Network layer: URLSession with provider-specific adapters.

See PLAN.md for the original architecture decisions and implementation record.

Contributing

Issues and pull requests are welcome. Please avoid attaching OAuth tokens, raw authorization responses, Keychain exports, or screenshots containing information you do not want published.

License

Source code is available under the MIT License. Provider names, logos, and trademarks are excluded from that license and remain the property of their respective owners.