English | 한국어

CreditClock

Track AI subscription usage, refill timers, and plan status in one place.
macOS app + desktop widget for Codex, Claude, and Gemini.

Screenshots

What You Get

• Unified usage tracking across providers in one dashboard.
• Refill countdowns for multiple quota windows (for example, 5h, 1w, daily).
• Subscription state indicators (Active, Trial, Paused, Expired).
• WidgetKit support (systemMedium, systemLarge) with shared app data.
• Menu bar quick view with one-click refresh.

Supported Providers

Provider	Data Source	Setup in App
Codex (OpenAI)	Local ~/.codex usage cache/session logs, with JWT fallback	Grant local folder access + click Connect
Claude (Anthropic)	Local ~/.claude/plugins/oh-my-claudecode/.usage-cache.json or Anthropic OAuth usage endpoint	Grant local folder access + click Connect
Gemini	Local ~/.gemini/oauth_creds.json (CLI OAuth quota) or Gemini API key fallback	Grant local folder access for CLI OAuth, or save API key + enable

Installation (macOS)

Prerequisites:

• macOS 14+
• Xcode 15+
• Homebrew + xcodegen

brew install xcodegen
xcodegen generate
open CreditClock.xcodeproj

In Xcode, run the CreditClock scheme.

Background Behavior

• CreditClock runs as a menu bar agent (no Dock icon / no always-open main window).
• After provider setup, it keeps polling in the background and pushes snapshot updates to widgets.
• Closing the settings window does not stop background polling.
• Choosing Quit from the menu bar stops polling until the app is launched again.
• Enable Launch at Login in the menu bar panel if you want automatic startup after sign-in.

Widget Setup (Desktop)

1. On the desktop, right-click an empty space and choose Edit Widgets.
2. Search for CreditClock.
3. Pick a size (Medium or Large) and add it to the desktop.
4. Open the CreditClock menu bar panel and click Refresh Now once after initial setup.
5. If the widget still shows No synced data, remove/re-add the widget after a refresh.

Settings Checklist

• In Settings -> Local Data Access, click Grant Codex + Claude + Gemini Together (Recommended) and select your home folder (~) once.
• For OpenAI and Anthropic, click Connect.
• For Anthropic, use Re-login Claude if Auth Status or Test fails.
• For Gemini, use local CLI OAuth (~/.gemini/oauth_creds.json) or save an API key and enable it.
• Use provider Test buttons to verify each connection.

How To Use

1. Launch CreditClock.
2. Open Settings from the menu bar icon (creditcard.circle).
3. Complete the steps in Settings Checklist.
4. Follow Widget Setup (Desktop) to add the widget.
5. Leave CreditClock running in the menu bar (optional: enable Launch at Login).

Installation note (as of February 17, 2026): CreditClock is not code-signed yet, so install/run it directly from Xcode (CreditClock scheme).

Troubleshooting

• No providers configured: open Settings and connect at least one provider.
• Widget shows No synced data: refresh once in app, then remove/re-add the widget.
• Folder access errors: re-open Settings and re-grant local access.
• Widget stops updating after reboot/login: make sure Launch at Login is enabled.

Privacy

• Local provider data is read from your machine (~/.codex, ~/.claude, ~/.gemini).
• API keys are stored in macOS Keychain.
• Snapshot sync between app and widget uses App Group plus local fallback paths.

Development

Tech Stack

• Swift 5.10
• SwiftUI (macOS app)
• WidgetKit (desktop widget)
• XcodeGen project generation (project.yml)

Project Structure

CreditClock/
├── CreditClockApp/                 # macOS menu bar agent + settings
├── CreditClockWidget/              # WidgetKit extension
├── Shared/
│   ├── Models/                     # Snapshot/state models
│   ├── Persistence/                # App Group, fallback storage, keychain wrappers
│   ├── Providers/                  # OpenAI/Anthropic/Gemini adapters
│   └── Store/                      # Refresh orchestration + polling
├── scripts/                        # Type-check, version bump, release helpers
└── project.yml                     # XcodeGen source of truth

Local Development

# Generate Xcode project
xcodegen generate

# Run Swift type checks used by pre-commit
./scripts/typecheck.sh

Pre-commit Automation

.husky/pre-commit runs:

1. scripts/bump-version.sh (patch bump in VERSION + regenerate Shared/Generated/BuildVersion.generated.swift)
2. scripts/typecheck.sh

Enable hooks in a fresh clone:

git config core.hooksPath .husky

If needed, skip version bump once:

CREDITCLOCK_SKIP_VERSION_BUMP=1 git commit -m "your message"

Build / Release Scripts

# Build unsigned Release app and zip artifact
./scripts/build-release-artifact.sh

# Build and upload/update GitHub release tag main-latest (requires gh auth)
./scripts/upload-main-release.sh

Data Sync Notes

• Primary sync: App Group container (group.com.creditclock.shared).
• Fallback sync: ~/.creditclock/snapshots.json.
• Widget bridge fallback: ~/Library/Containers/com.creditclock.app.widget/Data/Documents/snapshots.json.

License

MIT License. See LICENSE.