Filbert

Filbert is a native macOS AI usage tracker. It monitors token budgets, quotas, and spending across AI providers from a simple menu-bar app. The name stands for Friendly Icon Letting Budgets Explain Remaining Tokens.

Add the AI providers you use, and Filbert tracks their usage, quotas, and spend in one place.

Most developers use more than one AI platform: a coding plan here, an API key there, and a subscription somewhere else. Filbert brings them into one view, so you do not need to open several browser tabs to see what remains.

What you get

• Menu bar — glance at your most-used provider's remaining quota.
• Popover — click the icon for a full breakdown across every provider.
• Widgets — pin a provider's stats to Notification Center or your desktop (WIP).

Filbert is a native macOS app built to stay out of your way:

• No Dock icon. No app-switcher entry. Just a menu-bar item.
• No proxy. No Electron. It calls each provider's API directly with native URLSession.
• Your API keys stay on your machine, in the macOS Keychain.
• No telemetry. No analytics. No remote logging.

Supported providers

Provider	Status	What it tracks
z.ai	✅ Done	GLM Coding Plan quota, token window, peak hours
Claude	✅ Done¹	Claude Code plan usage via the claude CLI
DeepSeek	✅ Done	Prepaid balance — total, granted, topped-up
OpenAI Codex	✅ Done²	Subscription usage via the local codex CLI
Cursor	✅ Done³	Subscription + on-demand spend via local token
Moonshot	Planned	API usage, token consumption

¹ Claude reads usage from the Claude Code CLI. See Claude Code setup below.

² OpenAI Codex reads usage from the local Codex CLI. See OpenAI Codex setup below.

³ Cursor reads usage from your local Cursor session token. See Cursor setup below.

Add only the providers you use. The menu bar, popover, and widgets adapt to your setup.

Requirements

• Apple Silicon (M1 or newer). The released DMG is arm64-only.
• macOS 26 (Tahoe) or newer. The app is built against the macOS 26 SDK. Older systems render an outdated popover and are no longer supported.
• API keys for the providers you want to track.

Install

Prebuilt releases are available on the GitHub Releases page. Download the Filbert-<version>-arm64.dmg, then:

1. Mount the DMG by double-clicking it.
2. Drag Filbert to /Applications — use the /Applications shortcut inside the DMG window.
3. Launch it. The app lives in the menu bar. There is no Dock icon.

First launch on an unsigned build

Current releases are unsigned (ad-hoc signed), so macOS Gatekeeper blocks them on first launch. Once an Apple Developer Program membership is in place, releases will be signed and notarized. You will not need to take these steps.

To open an unsigned build, do one of these:

• Right-click Filbert in /Applications → Open → confirm the prompt. You only do this once. Later launches work with a double-click.

• Or clear the quarantine flag from the terminal:

  xattr -cr '/Applications/Filbert.app'

Signed and notarized builds, when available, launch with no warning and need none of this.

Use it

Click the Filbert menu-bar icon and open Settings to add a provider. Enter its API key. The key goes straight into the Keychain. Filbert then refreshes usage every five minutes by default.

Three providers read from a local session instead of an API key. Set those up below.

Security

• API keys live as Keychain generic-password items. They are never written to disk in plaintext and never logged.
• Keys go only to their respective provider APIs, over HTTPS.
• No telemetry, no analytics, no remote logging. The only outbound requests are the provider API calls that fetch your usage.

Why macOS asks for your password

macOS may show a system dialog asking for your login password or Touch ID when Filbert saves or reads credentials. This is the Keychain doing its job — not the app.

Filbert stores every API key and token in the macOS Keychain, the encrypted store Safari and other Apple apps use for passwords. When an app first reads or writes a Keychain item in a session, macOS asks you to unlock it. Think of it as a safe's lock:

• Your credentials stay encrypted on disk — only the Keychain can decrypt them, and only after you approve it.
• No other app can read them — the Keychain ties each item to the app that created it. A random process on your machine cannot ask for Filbert's secrets.
• Filbert never sees the process — the app asks the Keychain to store or retrieve a value, and the Keychain handles encryption and access control itself. Filbert never touches your password or Touch ID.

You may see this prompt once per session after the app launches, when it loads saved keys. You may see it again when you save a new key in Settings. Cursor users see another prompt on first import because Filbert reads tokens that Cursor's own apps stored in the Keychain. macOS is granting permission, not asking for another set of credentials.

In short: macOS shows this prompt to protect your credentials. Filbert does not receive your password or Touch ID.

OpenAI Codex setup

Only if you track Codex usage.

The OpenAI Codex provider reads subscription usage from the local codex CLI. Install it, then check the version:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

Run codex from a project directory. On first launch, choose Sign in with ChatGPT. Filbert does not read, store, or manage your Codex credentials. For other install methods and troubleshooting, see the official Codex CLI docs.

Cursor setup

Only if you track Cursor usage.

The Cursor provider reads subscription and on-demand spend from your local Cursor session token. It does not read from the Cursor website. You never enter a key — Filbert finds the token that Cursor's own apps already stored on your machine.

Make sure you are signed in to Cursor. The provider reads tokens from two locations, in this order:

1. Keychain — service cursor-agent, accounts cursor-access-token and cursor-refresh-token. Populated by agent login (the Cursor CLI).
2. SQLite — Cursor Desktop's state.vscdb. Populated when you sign into the Cursor desktop app.

No manual setup is needed. If you're signed into the Cursor desktop app or have run agent login, Filbert picks up the token on the next refresh.

This provider uses undocumented Cursor endpoints. It may stop working if Cursor changes their API.

Claude Code setup

Only if you track Claude Code usage.

The Claude provider reads usage from the Claude Code CLI (claude). It does not read from the Claude desktop app or from editor plugins like Zed's Claude agent. Those are separate products. They share the Claude brand, but they do not feed Filbert.

Install the CLI. Run this in your terminal:

curl -fsSL https://claude.ai/install.sh | bash

Check it. Open a new terminal so PATH reloads:

which claude
# expected: /Users/<you>/.local/bin/claude

Log in. Make sure claude is logged in. Filbert reads the usage Claude Code already fetched for your account. It never handles your credentials.

Then open Filbert → Settings → Claude Code and click Install Helper. The helper hooks into Claude Code's statusLine command. It writes a small cache file that Filbert reads during refresh.

You never run anything by hand. When you click Refresh, Filbert runs claude -p "/usage" in the background. It reads the figures and updates the cache. This works even when you use Claude Code from an editor and never open its status line. During interactive sessions, the status-line helper keeps the cache fresh.

The Claude desktop app (/Applications/Claude.app) is not a substitute. Its bundled claude binary sits under a versioned ~/Library/Application Support/Claude/... path that changes on every update, and it is not meant to run on its own.

How it works

Filbert uses an orthogonal provider architecture. Each provider is its own module behind a shared protocol. You can add or remove any provider without touching the others or the core app.

┌────────────────────────────────────────────┐
│                  App Layer                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ Menu Bar │  │ Popover  │  │ Widgets  │  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  │
│       └──────────────┼──────────────┘       │
│                      │                      │
│  ┌───────────────────▼───────────────────┐  │
│  │            Provider Hub               │  │
│  │   (registry, refresh, aggregation)    │  │
│  └───────────────────┬───────────────────┘  │
│                      │                      │
│     ┌────────────────┼────────────────┐     │
│     ▼                ▼                ▼     │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────────┐│
│  │ z.ai │  │DeepSk│  │Claude│  │ OpenAI … ││
│  └──────┘  └──────┘  └──────┘  └──────────┘│
│           Provider implementations          │
└────────────────────────────────────────────┘

• Provider protocol — one Swift protocol (AIProvider) that every provider implements. It defines quota fetching, authentication, and display metadata.
• Provider hub — owns the registry of active providers, runs the refresh cadence, and hands aggregated data to the UI.
• UI layer — the menu bar, popover, and widgets read the hub's published state. They know nothing about a provider's API.

To add a provider, implement the protocol and register it. Nothing else changes.

Build from source

If you have an Intel Mac, want the latest main, or prefer to build it yourself:

git clone https://github.com/victorhqc/filbert.git
cd filbert
swift run

You'll need Swift 5.9+. Install the Xcode Command Line Tools with xcode-select --install.

To create a DMG locally, first install create-dmg:

brew install create-dmg
scripts/build-dmg.sh --version 0.1.0 --no-sign
# → dist/Filbert-0.1.0-arm64.dmg

Status

Early development. The Core protocol, the Keychain wrapper, and the z.ai, Claude, DeepSeek, OpenAI Codex, and Cursor providers are in place. The app builds and runs as a menu-bar item. More providers and widgets come next.

See specs/ for the spec files that drive the work.

Contributing

We follow a spec-first workflow: write the spec, implement one item, run the validation gate, then review. Read CONTRIBUTING.md for the full workflow, coding standards, commit rules, and the validation gate. The deeper agent guide lives in AGENTS.md.

License

MIT © 2026 Victor Quiroz Castro.