---
title: "Install and sign in to the sources"
url: https://phatdev.net/en/docs/aiusage/cai-dat
lang: en
updated: 2026-10-23
alternate:
  vi: https://phatdev.net/docs/aiusage/cai-dat
markdown: https://phatdev.net/en/docs/aiusage/cai-dat.md
---

# Install and sign in to the sources

Part of the doc set: [AIUsage](https://phatdev.net/en/docs/aiusage.md)

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

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

```sh
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.