usAIge

usAIge has native clients for macOS, iPhone, iPad, and Apple Watch. The Mac is the trusted limit collector: it reads the local Codex app-server, Claude desktop usage data, Cursor and Grok Build sign-ins already on the Mac, and paired remote tools, then relays only normalized percentages and reset times to paired iPhones.

Roadmap

Product development follows three stages: establish the macOS MVP, extend the experience to iPhone and Apple Watch, and then expand support for additional AI tools. See docs/roadmap.md for the scope and boundaries of each stage.

Built with Codex and GPT-5.6

Codex powered by GPT-5.6 was the primary engineering collaborator used to turn usAIge from a product idea into a working multi-platform system. The human owner set the product direction, privacy boundaries, and final UX decisions; Codex and GPT-5.6 helped execute and verify the implementation across the Swift, SwiftUI, AppKit, WidgetKit, WatchConnectivity, and relay-server codebases.

In practice, Codex and GPT-5.6 were used to:

• Explore the repository, translate product requirements into implementation plans, and make coordinated changes across macOS, iOS, iPadOS, watchOS, widgets, and the web relay.
• Build the local Codex app-server JSON-RPC integration, including account and rate-limit reads, live account/rateLimits/updated events, multi-window quota normalization, reconnect behavior, and privacy-safe error handling.
• Design and implement the account-free Mac-to-iPhone pairing flow, revocable device credentials, normalized snapshot relay, session-status notifications, widgets, WatchConnectivity sync, and Apple Watch complications.
• Iterate on native Apple UX from feedback: the floating macOS usage rail, Settings flows, quota severity states, connection guidance, iPhone activity views, widgets, and Watch layouts.
• Generate and expand automated tests, diagnose build and concurrency failures, review diffs for regressions, package releases, and verify behavior with command-line builds and simulator/device-oriented checks.

This was not a one-shot code generation exercise. Development used an iterative agentic loop: inspect the existing architecture, implement a focused change, run the relevant tests and builds, review the result, fix failures, and repeat. The commit and pull-request history preserves that progression.

iOS app and widget

Open usAIge-iOS.xcodeproj in Xcode 26. The project contains:

• A native tab-based iPhone and iPad app with Usage, Activities, Connection, and Settings sections.
• Account-free pairing with an 8-digit, one-use code shown by the Mac.
• A device-scoped relay token stored in the iOS Keychain.
• An App Group JSON cache containing quota values only, never tokens.
• Small, medium, and large widgets backed by the shared cache.
• Immediate foreground and pull-to-refresh updates plus APNs-assisted, best-effort background refresh scheduling.
• Finished-session, error, and permission-request alerts are enabled by default and controlled through iPhone notification permissions. A locally cached Activities inbox remains available, and selecting an alert focuses the matching event.
• Credential-free WatchConnectivity sync to the Watch app and watch-face complications.

Open Settings → iPhone & Apple Watch Sync on the Mac, create a code, and enter it in the iPhone Connection tab. One Mac can issue separate revocable codes for multiple iPhones. iOS controls the exact time granted to background tasks and widget timelines, so the app shows saved data and its update age instead of promising minute-exact background delivery.

Build the iOS app for Simulator with:

xcodebuild \
  -project usAIge-iOS.xcodeproj \
  -scheme usAIge-iOS \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=latest' \
  build

For device builds, select the same Apple development team for the app and widget targets, register group.com.richardq.usaige as an App Group, and enable Push Notifications plus the Remote notifications background mode.

iOS privacy

• The channel and device identifiers are stored in the app sandbox. The device-scoped read token is stored separately in the iOS Keychain.
• The App Group cache shared with the widget contains normalized quota values, reset times, and refresh metadata, but never bearer tokens.
• The relay retains only the latest normalized snapshot until the Mac owner disconnects the channel. It receives no provider credentials, browser cookies, prompts, or account content.
• For session notification delivery, the relay retains at most the latest 100 status events per Mac, and none older than seven days: event type, session title, workspace name, and timestamp. Disconnecting the Mac deletes that history with the channel.

Apple Watch app and complications

The Apple Watch version shows every synced remote AI limit and provides circular, rectangular, inline, and native quarter-curve corner complications. Users configure sources on the Mac; only normalized quota snapshots are relayed to iPhone and transferred to the Watch.

Open the combined project at Apple/usAIgeApple.xcodeproj to build the iOS app, iOS widget, Watch app, and Watch widget together. Setup, supported watch-face families, sync behavior, and device signing are documented in Apple/README.md.

macOS app

usAIge is a native macOS floating AI usage rail. It shows real usage limits from the local Codex app-server, from local Claude desktop usage data and the Cursor and Grok Build sign-ins already on this Mac, and from remote AI tools you explicitly configure. When a limit has two windows, the inner ring shows its primary window and the outer ring shows its secondary window.

macOS can notify you whenever a primary or secondary usage window crosses a new 5% used boundary. Selecting the notification brings the live limits rail forward.

This is the beginning of the README. Read the rest at the original. Read the full README ↗