Back to home

Setup guide

Connect your platforms.

Most AI providers run on a shared usage pool — sign in once and Tokenomics tracks everything that account covers, across chat, agents, and creative tools. Pick the platform you use below for plain-English setup steps. No assumptions about what you've installed before.

Quick & Guided shows the no-Terminal flow Tokenomics handles for you inside the app. Terminal is for users who want to install command-line tools manually.

Anthropic

Anthropic runs three products on a single shared usage pool — Claude Chat (claude.ai and the Claude desktop app), Claude Cowork (the collaborative agent surface), and Claude Code (the developer CLI). Whichever you use, it's the same 5-hour and 7-day windows. Connecting once gets you all three.

Heads-up: as of February 2026, Anthropic's Authentication and credential use policy doesn't permit third-party apps to sign in to Pro / Max accounts directly. Tokenomics has two supported paths instead.

Path A — Already have Claude Code installed?

Tokenomics auto-detects it. Open Tokenomics → click the gear → Providers → Anthropic → Connect. Done. Your rings populate within ~30 seconds and reflect the whole Anthropic pool: Chat, Cowork, and Code.

Path B — Don't have Claude Code? Paste an API key.

  • Works for users who have a developer key from console.anthropic.com.
  • Important caveat: an API key tracks your developer API spend, not your Pro / Max plan's 5-hour and 7-day rate limits. Different metric, different audience. Most consumer Pro users won't have one.
  • If you don't have a key and don't want to install Claude Code, the third option is the Terminal tab above — it walks through installing Claude Code yourself.

  1. Get your Anthropic API key

    Sign in to console.anthropic.com → API Keys. Click Create Key. Name it "Tokenomics". Copy the long string that starts with sk-ant-. Treat it like a password.

  2. Paste it into Tokenomics

    Open Tokenomics → gear icon → Providers → Anthropic → Connect with API key. Paste, click Save.

    Where the key is stored: macOS Keychain on your computer. Tokenomics never sends it anywhere except to Anthropic's API.

  3. Open Tokenomics

    The Anthropic tab populates within ~30 seconds. The numbers reflect your developer API usage — see the caveat above.

Manual install of Claude Code, the developer CLI. Once it's signed in, Tokenomics piggybacks on its credential file to read your Pro / Max plan rate limits. This is the path most accurate for non-API users who want to track their actual subscription.

Before you start

  • An Anthropic account on the Claude Pro plan or higher — covers Chat, Cowork, and Code (free accounts don't expose usage data).
  • About 5 minutes.
  • Don't worry if you've never opened Terminal — every step explains what to expect.

  1. Open Terminal

    Press ⌘ Space, type Terminal, and press Return. A black or white window opens with a blinking cursor — that's where you'll paste the next command. Don't worry, you can't break anything by typing here.

  2. Install Claude Code

    Copy the line below, paste it into Terminal, and press Return. (Cmd-V to paste — just like anywhere else on your Mac.)

    $ npm install -g @anthropic-ai/claude-code
    What you'll see: a short download, then added 1 package. Takes about 30 seconds.
    If you see "command not found: npm" — that means Node.js isn't installed yet. Tokenomics handles this for you: when you click Install in the app, it'll open nodejs.org automatically. Run the .pkg installer, then come back here and try again.

  3. Sign in

    Type claude and press Return. Your default browser will open and ask you to sign in to your Anthropic account. Sign in. The browser will say "You can close this tab" when it's done.

    $ claude
    What you'll see: Terminal will print "Welcome to Claude Code" and a project picker. You can press Ctrl-C to exit — your sign-in is saved.

  4. Open Tokenomics

    If Tokenomics is already running, click its menu bar icon — within ~30 seconds the Claude tab shows two rings: 5-hour usage on the outside, 7-day usage on the inside. If it's not running, launch it from Applications.

How you'll know it worked

Two rings appear on the Anthropic tab — even at 0% usage, the rings render at 0% rather than spinning forever. The menu bar shows the same rings, miniaturized.

The rings reflect your whole Anthropic account: anything you do in Claude Chat, Claude Cowork, and Claude Code all counts against the same 5-hour and 7-day pool.

Common issues

I only use Claude Chat — do I really have to install Claude Code?

Today, yes — but not for long. Anthropic's three products share one usage pool, so the data Tokenomics needs is the same regardless of which app you use. The current path uses Claude Code's auth token because that's what Tokenomics knows how to read. We're adding direct support for the Claude desktop app's credentials so chat-only users can skip Terminal entirely. Watch the changelog.

The popover still shows "Anthropic isn't set up yet."

That means Tokenomics can't find the Claude Code credentials file at ~/.claude/. Either step 3 didn't complete (the browser closed before it could write the token), or the CLI was installed under a different user. Open Terminal, type claude, finish the browser sign-in all the way through, then click "Refresh" in Tokenomics.

I'm on the free Claude plan — will Tokenomics work?

The CLI installs and signs in fine on free, but Anthropic doesn't expose a usage endpoint for free accounts — so Tokenomics has nothing to read. The Anthropic tab will say "Pro plan required" instead of showing rings. Pro is $20/month; that's the lowest tier with usage data, and it covers all three products in the pool.

Terminal said "permission denied" on the npm install.

Some Node installs put the global folder in a place that requires admin rights. Try the same command with sudo at the start — Terminal will ask for your Mac password (you won't see it as you type, that's normal). If that still fails, the cleanest fix is to install Node via the official .pkg from nodejs.org instead of Homebrew.

GitHub

GitHub has one AI product Tokenomics tracks: GitHub Copilot.

Tokenomics handles GitHub sign-in for you

One click in the app, one approval in your browser, you're done. No CLI, no Terminal, no Personal Access Token. Tokenomics only sees your Copilot quota — never your code.

Before you start

  • A GitHub Copilot subscription (Individual, Business, or Enterprise).
  • About 1 minute.

  1. Click Sign in with GitHub in Tokenomics

    Open Tokenomics → click the gear icon → Providers → GitHub Copilot → Sign in with GitHub. Your default browser will open to GitHub's approval page.

  2. Approve in your browser

    GitHub will ask you to authorize Tokenomics — Read Copilot usage. Review the scopes (read-only — Tokenomics asks only for what it needs to show your quota) and click Authorize.

    What you'll see: the browser redirects back to a "Tokenomics" confirmation page, then closes the tab. Tokenomics' Copilot panel switches to "Connected".

  3. Done

    Within ~30 seconds the Copilot tab shows two bars — Premium-request usage and total monthly requests.

Manual install of GitHub's official command-line tool, gh. You sign in once, and Tokenomics piggybacks on that sign-in. This path is also the fallback if the Quick OAuth flow fails for any reason.

Before you start

  • A GitHub Copilot subscription (Individual, Business, or Enterprise — any tier with premium-request quotas).
  • About 3 minutes.

  1. Install the GitHub CLI

    Open Terminal (⌘ Space → Terminal) and paste:

    $ brew install gh
    Don't have Homebrew? Either install it (one line — brew.sh) or skip Homebrew entirely and download the official GitHub CLI installer from the GitHub CLI releases page — look for the .pkg file. Tokenomics will offer both options when you click Install in the app.

  2. Sign in to GitHub

    Run the login command. gh will ask a few short questions in Terminal — pick the defaults (GitHub.com, HTTPS, log in with a web browser).

    $ gh auth login
    What you'll see: a one-time code in Terminal. Copy it, your browser opens to github.com/login/device, paste the code, click Authorize. Done.

  3. Open Tokenomics

    The Copilot tab shows your premium-request usage and your monthly request quota within ~30 seconds. No additional setup needed inside the app.

How you'll know it worked

The Copilot tab shows two bars: "Premium" (your premium-model request usage) and "Requests" (total monthly requests). If you don't have a paid Copilot plan, the tab says so explicitly instead of spinning.

Cursor

Cursor is an AI-powered code editor — a single Mac app, not a multi-product platform. Tokenomics reads its usage directly from Cursor's local config file.

Before you start

  • A Cursor Pro or Business plan (free plans don't expose usage data).
  • About 2 minutes.

  1. Download Cursor

    Go to cursor.com/downloads. Click Download for Mac. Open the .dmg and drag Cursor to your Applications folder.

  2. Sign in to Cursor

    Open the Cursor app from Applications. The first time you launch it, Cursor walks you through signing in with your Cursor account (or with GitHub / Google). Complete the sign-in.

    What you'll see: Cursor's main editor window with your account name in the bottom-left corner.

  3. Tokenomics auto-detects

    The Cursor tab populates within ~30 seconds. No CLI, no Connect button to click — Tokenomics reads Cursor's local config the moment you've signed in.

If you already use Homebrew, you can install Cursor via brew instead of the .dmg. The auth and Tokenomics-detection steps are identical.

Before you start

  • Homebrew installed.
  • A Cursor Pro or Business plan.

  1. Install Cursor via Homebrew

    Open Terminal (⌘ Space → Terminal) and run:

    $ brew install --cask cursor

  2. Sign in to Cursor

    Open Cursor from Applications, sign in with your Cursor / GitHub / Google account.

  3. Tokenomics auto-detects

    Same as the Quick path — Tokenomics reads Cursor's local config within ~30 seconds.

How you'll know it worked

The Cursor tab shows two bars — "Premium" (your premium-model usage) and "Requests" (total monthly requests). If you signed in with the wrong account, sign out and back in inside Cursor; Tokenomics picks up the change automatically.

OpenAI

OpenAI runs four products on a single shared usage pool — ChatGPT (web and desktop app), Codex (the CLI coding agent), DALL-E (image generation), and Sora (video). Whatever you use, it's the same 5-hour window and context-token budget. Connecting once gets you all four.

Tokenomics handles the install for you

OpenAI's auth runs through the Codex CLI today — but you don't have to install or even see it. Tokenomics ships its own copy of Node.js and pulls Codex into a private folder on first connect. The whole step is a progress bar inside Tokenomics; no Terminal opens.

Before you start

  • A ChatGPT Plus, Pro, Business, or Enterprise account — covers all four products in the pool.
  • About 1 minute.

  1. Click Connect OpenAI in Tokenomics

    Open Tokenomics → gear icon → Providers → OpenAI → Connect. A progress bar appears: "Setting up OpenAI on this Mac… ~30 seconds left."

  2. Sign in to OpenAI

    When setup finishes, Tokenomics opens your browser to OpenAI's sign-in page. Use your ChatGPT account credentials. Browser closes itself when done.

  3. Done

    The OpenAI tab shows your 5-hour usage and remaining context-token budget within ~30 seconds.

Manual install of the Codex CLI via npm. Use this path if you already have Node.js installed, prefer the official OpenAI-distributed package, or want the CLI itself for other purposes.

Before you start

  • A ChatGPT Plus, Pro, Business, or Enterprise account — covers all four products in the pool.
  • About 5 minutes.
  • Node.js installed on your Mac — install from nodejs.org if needed.

  1. Install the Codex CLI

    Codex is OpenAI's command-line coding agent — and it's the auth path Tokenomics currently uses for all four products in the pool. Open Terminal and paste:

    $ npm install -g @openai/codex
    What you'll see: a short download log, ending in added 1 package.

  2. Sign in

    Run the login command. Your browser opens, signs you into your ChatGPT account, then redirects back. Terminal will say you're signed in.

    $ codex login

  3. Open Tokenomics

    The OpenAI tab shows two bars — "5-hour" usage and "Context" (your remaining session-token budget) within ~30 seconds.

How you'll know it worked

The OpenAI tab shows your 5-hour usage and remaining context-token budget. The numbers reflect your whole OpenAI account — anything you do in ChatGPT, Codex, DALL-E, and Sora all counts against the same pool.

Common issues

I only use ChatGPT — do I really have to install Codex?

Today, yes — but only because Tokenomics currently reads your auth token from the Codex CLI's credential file. Once that auth is in place, the data covers your entire OpenAI account: chat, image, and video usage all included. We're working on detecting the ChatGPT desktop app's credentials directly so the CLI step won't be required for chat-only users.

Google

Google AI runs three products on a shared usage pool — Gemini (chat and the Gemini CLI), Nano Banana (image generation), and Veo (video). Sign in once and Tokenomics tracks your usage across all three.

Tokenomics handles the install for you

Google's auth runs through the Gemini CLI today — but you don't have to install or even see it. Tokenomics ships its own copy of Node.js and pulls Gemini CLI into a private folder on first connect. The whole step is a progress bar inside Tokenomics; no Terminal opens.

Before you start

  • A Google account on Gemini Code Assist (free works, but limits vary by plan).
  • About 1 minute.

  1. Click Connect Google AI in Tokenomics

    Open Tokenomics → gear icon → Providers → Google AI → Connect. A progress bar appears: "Setting up Google AI on this Mac… ~30 seconds left."

  2. Sign in with Google

    When setup finishes, Tokenomics opens your browser to Google's sign-in. Pick the right Google account, grant access, browser closes itself.

  3. Pick your plan tier

    Inside Tokenomics → gear → Providers → Google → set your plan (Free, Standard, or Enterprise). This tells Tokenomics which limits to compare your usage against. Right plan = accurate rings.

Manual install of the Gemini CLI via npm. Use this if you already have Node.js, prefer the official Google-distributed package, or want the CLI itself for other purposes.

Before you start

  • A Google account on Gemini Code Assist (free works, but limits vary by plan — pick your tier in Tokenomics → Settings → Google).
  • About 5 minutes.
  • Node.js installed on your Mac.

  1. Install Gemini CLI

    Open Terminal and paste:

    $ npm install -g @google/gemini-cli

  2. Sign in

    Run the login command — your browser opens, you pick your Google account, grant access, and the browser closes itself.

    $ gemini login

  3. Pick your plan in Tokenomics

    Open Tokenomics → click the gear icon → Providers → Google → set your plan (Free, Standard, or Enterprise). This tells Tokenomics which limits to compare your usage against. The right plan = accurate rings.

How you'll know it worked

The Google tab shows your token usage and request count. The numbers reflect your whole Google AI account — anything you do in Gemini, Nano Banana, and Veo all counts against the same pool.

API-key providers

Stability AI, Runway, and ElevenLabs don't have CLIs — you connect them by pasting an API key into Tokenomics. The pattern is the same for all three. No Terminal version exists or is needed for these.

Before you start

  • A paid account with the provider (free tiers usually don't expose a usage endpoint).
  • About 2 minutes per provider.

  1. Get an API key

    Sign in to the provider's website and look for "API keys" in account settings. Direct links:

    Click "Create new key" (or similar). Give it a name like "Tokenomics". Copy the key — it's a long string of letters and numbers. Keep it private; treat it like a password.

  2. Paste it into Tokenomics

    In Tokenomics, click the gear icon → Providers → pick the provider → "Paste API key". Paste, click Save.

    Where the key is stored: macOS Keychain on your computer. Tokenomics never sends it anywhere except to the provider you chose. You can revoke or rotate the key any time on the provider's website — Tokenomics will surface an error and prompt you to re-enter.

How you'll know it worked

The provider's tab shows credits remaining, monthly usage, or character count (depending on the provider). If the key is wrong, you'll see "Invalid API key" rather than a spinner.

Still stuck?

Open an issue on GitHub.

If something didn't work or a step needs better wording, the fastest fix is to tell us. Most setup bugs get patched in the next release.

Report a setup issue Back to install