Token Ghost 👻

A small macOS menu bar plugin that shows your Claude Code and Codex usage limits at a glance.

Token Ghost runs inside SwiftBar. SwiftBar is the menu bar app; Token Ghost is the plugin that reads your Claude/Codex usage and renders it.

🇰🇷 한국어 안내는 README.ko.md를 참고하세요.

---

What it looks like

The menu bar title shows only your Claude Code current-session usage, e.g. 👻22%.

Click it for the full breakdown:

🧡 Claude
Current: 🟨🟨🟨⬜️⬜️⬜️⬜️⬜️  36% (~9:10pm)
Weekly:  🟩🟩⬜️⬜️⬜️⬜️⬜️⬜️  25% (~Jul 15 6pm)
Checked 3m ago

💙 Codex
5 Hour:  🟩⬜️⬜️⬜️⬜️⬜️⬜️⬜️  12% (~8:28pm)
Weekly:  🟩🟩🟩⬜️⬜️⬜️⬜️⬜️  35% (~Jul 17 6am)
From session log, 40m ago

The bar fills green → yellow → orange → red as usage climbs. Every bucket shows its reset time as (~time), and each tool shows how fresh its numbers are.

---

How it works

Token Ghost is not a standalone app. It is a plugin for SwiftBar:

SwiftBar      = the macOS menu bar app that displays text
Token Ghost   = the plugin that reads Claude/Codex usage and prints the menu
Claude / Codex CLI = the tools that actually know your usage limits

So it only works once Claude Code and Codex already work in your terminal.

Where the numbers come from

Claude — captured from a short interactive /usage session. Claude Code keeps no structured usage data on disk, so a brief TUI session is the only local source. To stay light, the capture runs at most once every 15 minutes and is cached in between; the menu shows how old the value is. Change the interval with TOKEN_GHOST_CLAUDE_TTL_MIN, or force a fresh capture from the Refresh menu action.

Codex — read from the structured rate_limits events Codex writes into its local session logs (~/.codex/sessions/**/*.jsonl). No terminal automation is involved. Because those logs only update when Codex actually runs:

• the menu shows the data age (From session log, 40m ago), and
• once a window's reset time has passed, the bucket shows 0% with the projected next reset (the reported reset rolled forward by the window length), e.g. 5 Hour: 0% (~3:18am), until the next Codex run writes fresh numbers.

---

Requirements

• macOS
• Python 3 (already present on most developer Macs)
• SwiftBar
• Claude Code CLI, logged in — required for Claude usage
• Codex CLI, logged in — required for Codex usage

Token Ghost never logs in for you. Check that each CLI already works:

codex login status   # Codex
claude               # Claude Code: opens the TUI; log in with /login if asked

---

Install

Paste this into Terminal (no angle brackets):

curl -fsSL https://raw.githubusercontent.com/zoeymakes/token-ghost/v1.0.0/install.sh | bash

What the installer does:

SwiftBar already installed        → installs the Token Ghost plugin
SwiftBar missing + Homebrew       → installs SwiftBar via brew, then the plugin
SwiftBar missing + no Homebrew    → installs the plugin only; install SwiftBar yourself

If SwiftBar has to be installed manually, get it from https://swiftbar.app, then run the install command again.

From a downloaded copy

cd token-ghost && ./install.sh

After installing

SwiftBar opens automatically. If it asks for a Plugin Folder, the installer already targets the one SwiftBar is configured to watch (falling back to ~/SwiftBarPlugins). If 👻 doesn't appear right away, click SwiftBar → Refresh All. On first launch macOS may ask permission for SwiftBar to run and show menu bar items — allow it.

---

Menu actions

• Refresh — force a fresh capture now (bypasses the Claude cache TTL).
• Setup guide — open this README.
• Open Claude / Open Codex — launch the respective app or website.

---

Configuration

Environment variables (set them where SwiftBar can see them, or edit the plugin):

Variable	Default	Effect
TOKEN_GHOST_CLAUDE_TTL_MIN	15	Minutes between Claude /usage captures
TOKEN_GHOST_PLUGIN_DIR	SwiftBar's configured folder	Where the plugin is installed

---

Commands

~/.token-ghost/token_ghost.py --render-cache      # print the last cached menu
~/.token-ghost/token_ghost.py --collect           # collect + print JSON (Claude honors the TTL)
~/.token-ghost/token_ghost.py --collect --force    # force a fresh Claude capture

---

Privacy

Token Ghost does not store passwords, API keys, access tokens, or account credentials. It reads usage from the already-installed claude and codex tools and caches only usage percentages and reset times at:

~/.cache/token-ghost/cache.json

---

Uninstall

curl -fsSL https://raw.githubusercontent.com/zoeymakes/token-ghost/main/uninstall.sh | bash

To remove the local cache too, from a downloaded copy:

./uninstall.sh --with-cache

---

Installed files

<SwiftBar plugin folder>/token-ghost-menu.5m.py
~/.token-ghost/token_ghost.py
~/.token-ghost/README.md
~/.cache/token-ghost/cache.json

---

Limitations

• Token Ghost is a SwiftBar plugin, not a standalone .app.
• Codex numbers move only when Codex actually runs; the menu shows the data age and marks passed reset windows as projected estimates.
• Claude usage comes from a short interactive capture; between captures (15 min TTL) the menu shows the cached value with its age.
• SwiftBar menus are text, so progress bars are drawn with colored squares.

---

License

MIT — see LICENSE.