<PhatLam/>/docsVI

Install and sign in to the sources

Requirements, building from source, installing the background jobs, signing in to Claude, Console, Codex, Antigravity and Gemini, and troubleshooting.

AIUsageUpdated 23 Oct 2026
cài đặtđăng nhập

AIUsage runs entirely on your Mac. This page explains how to build the app from source, install the background jobs and sign in to the data sources.

Requirements

  • macOS 26 or later and Xcode 27 or later to build.
  • The tools and accounts you want to track, already signed in: claude.ai and the Anthropic Console (inside the app's embedded browser), codex, agy, and a Google Cloud service account for the Gemini API (optional).

Build and install the app

xcodebuild -project AIUsage.xcodeproj -scheme AIUsage -configuration Release \
  -derivedDataPath /tmp/AIUsage_build CODE_SIGN_IDENTITY="-" CODE_SIGNING_ALLOWED=YES build
cp -R /tmp/AIUsage_build/Build/Products/Release/AIUsage.app /Applications/
open /Applications/AIUsage.app

After installing, delete the temporary build and re-register the app with Launch Services so WidgetKit does not run the widget from a temporary folder. Always confirm BUILD SUCCEEDED before copying: if a broken build is copied into /Applications, the app will not launch.

Install the background jobs

There are three LaunchAgents: refresh runs every 5 minutes, trigger runs when the refresh button in the app or widget is pressed, and login opens the sign-in window from the widget. Sample files live in the repository's launchd/ directory and use __HOME__ in place of a user path.

Sign in to the sources

  1. Claude: open the helper's sign-in window and choose Continue with email. Google sign-in is blocked inside a WebView. Type the confirmation code sent by email, or paste it with the Edit menu.
  2. Anthropic Console: run the helper with the login-console argument and sign in once. The API credit balance then appears as the "API" row in the Claude card.
  3. Codex: run codex login. The app uses the token in Codex's own sign-in file.
  4. Antigravity: sign in to agy once.
  5. Gemini API (optional): store the base64-encoded service-account JSON in the Keychain under the name aiusage.gcp.sa, then edit the project, BigQuery table and billing-account constants at the top of the gemini branch in fetch_one.sh. The credit balance is read from the AI Studio page; sign in to Google once with the login-aistudio argument.
  6. Remote host (optional): list the host in REMOTE_HOSTS in fetch_one.sh and copy remote_insights.py to that machine. Key-based SSH without a password prompt is required.

The app never types a password or a confirmation code for you: you sign in yourself in the helper's window.

Troubleshooting

  • The Claude card says "sign-in required". The session has expired. Press the sign-in button on the card or run login again.
  • The API row is missing. The Console has not been signed in yet. Run login-console, then refresh.
  • A password saved in macOS Passwords does not autofill. The sign-in window is WebKit embedded in the app and cannot use system autofill; use the emailed-code sign-in instead.
  • The build fails with "detritus not allowed" while signing. The source folder is in a synced location (Documents or Desktop) and picks up extended attributes. Sign a copy in a temporary directory.
  • The widget refresh button does not update. An old widget process survives a deploy. Run pkill -f AIUsageWidgetExtension and try again.