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.

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.

Today Tokenomics reads your auth token from Claude Code's credential file — so the install path below routes through the CLI. We're working on detecting the Claude desktop app's credentials directly so you'll be able to skip the Terminal step entirely.

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. To read its usage, Tokenomics talks to GitHub through GitHub's official command-line tool, called gh. You sign in once, and Tokenomics piggybacks on that sign-in.

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. You'll never need to touch Terminal for this one. 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. Install Cursor

    Two options — pick whichever you prefer:

    Option 1 (recommended for non-technical users): download Cursor directly from cursor.com/downloads. Open the .dmg, drag Cursor to Applications. Done.

    Option 2 (if you already use Homebrew): open Terminal and run brew install --cask cursor.

  2. Sign in to Cursor

    Open the Cursor app. The first time you launch it, Cursor walks you through signing in with your Cursor account (or with GitHub / Google). Complete the sign-in. You don't need to write any code yet — just signing in is enough for Tokenomics.

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

  3. Open Tokenomics

    The Cursor tab populates within ~30 seconds. There's no additional CLI step — Tokenomics reads Cursor's local config the moment you've signed in to the app.

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.

Today Tokenomics reads your auth token from the Codex CLI's credential file. We're working on detecting the ChatGPT desktop app's credentials directly so non-coders can skip Terminal entirely.

Before you start

  • A ChatGPT Plus, Pro, Business, or Enterprise account — covers all four products in the pool.
  • About 5 minutes.
  • If you don't have Node.js yet, the install will guide you to nodejs.org first.

  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.

Today Tokenomics reads your auth token from the Gemini CLI's credential file. Direct desktop-app auth is on the roadmap.

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.

  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.

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