How it works Providers Install GitHub
Free & open source · macOS, Linux, Windows + KDE Plasma

Know how much AI you have left.

Needle puts your Claude Pro or Max, ChatGPT/Codex and z.ai Coding Plan limits in your menu bar, panel or taskbar, with OpenRouter and a local-model token tally right alongside. One glance tells you whether to start that big refactor now — or route it somewhere with room.

Get it on GitHub Install in one line
Keys stay on your machine No telemetry Lightweight Python
C 46%  Z 100% 43% Thu 5:48
The readout

One line. Every limit.

The menu bar shows a single number per service: the tighter of its 5-hour and weekly windows. That's the honest answer to "how much can I use right now?"

C 58%G 71%Z 82%$14
plenty under 30% under 10%
C · G · Z · $
Claude, ChatGPT/Codex, z.ai, and your OpenRouter balance. Turn off what you don't use and it disappears.
Amber, then red
The text changes color as you run low — and a desktop notification fires the moment a gauge first goes red, plus one more when it recovers.
Click for detail
Each window, its reset time, and whether you're burning through it faster than it refills.
Reading the gauge

The fill is what's left.
The tick is the clock.

Every bar carries two facts. If the fill sits left of the tick, you're spending faster than the window resets. Drag the sliders and watch the verdict change.

Fill is the share of the limit you still have.

Tick is the share of time left before the window resets.

Claude · 5-hour resets in 2h 12m46% left
● on paceRight on pace.
Providers

Four services. Two need nothing.

Claude and ChatGPT/Codex reuse sign-ins you already have. z.ai and OpenRouter take a key, pasted once into a dialog. Local AI just shows up.

Claude

Nothing to add

Uses your Claude Code sign-in. Log in to claude with Pro or Max and you're done. Shows 5-hour and weekly windows — and if the sign-in expires, Needle nudges Claude Code to refresh it in the background.

ChatGPT / Codex

Nothing to add

Uses your ChatGPT sign-in from OpenCode or ~/.codex/auth.json. Same 5-hour and weekly limits you see in /status.

z.ai

Coding Plan key

Paste your Coding Plan API key. Shows the 5-hour window and your tool-call allowance.

OpenRouter

Any key

A management key shows your whole account balance. A regular key shows that key's own spending limit.

Local AI

No setup at all

Counts tokens you run on local models — Ollama and local providers in OpenCode — into a running total: today, this week, all time, top models, and what it would have cost on a hosted API. It isn't a limit, so it stays out of the compact readout.

Claude is never asked more than once every 5 minutes, even if you mash Refresh. Anthropic backs off hard on frequent polling, and that backoff can slow Claude Code itself.

Platforms

At home on every desktop.

The same fetcher and the same keys file power every frontend, so you can copy your config from one machine to the next.

macOS · SwiftBar

A menu-bar item with bars, reset times and a pace word for each window: ▲ fast, ● on pace or ▼ plenty. Refreshes every 5 minutes and can open at login.

Linux Mint · Cinnamon applet

A panel applet that opens a popup on click — plus the PineNeedle desklet, a gauge card that lives on your desktop in ten themes, from a green-screen Retro CRT to an alien computer. Light, System, Dark, Night or a fully custom palette.

Windows · Tray icon

The tightest percentage on a green, amber or red tile. Hover for the compact summary, click for bars, reset times and pace words. Light, System, Dark, Night or a fully custom palette. Refreshes every 5 minutes and starts when you sign in.

KDE Plasma 6 · Panel widget

A native Plasma 6 widget: compact panel text, a click popup with the same gauges, notifications, the Local AI tally and update checks. Themes follow Plasma's own colors in System mode, with Light, Dark and Night presets.

Install

Two commands. No account.

Clone the repo and run the installer. It sets up the keys file at ~/.config/needle/config.json and you're live.

On the Mac, macOS asks to let security read your Claude Code sign-in from the Keychain. Click Always Allow so the menu bar can refresh quietly, or Allow to approve it each time.

SwiftBar included. The Mac installer grabs it with Homebrew if it's missing and offers to start it at login.

On Windows, you need Python 3. The installer offers to get it with winget if it's missing, and starts Needle when you sign in by default. No Git? Download the ZIP from GitHub and run the second line from that folder.

Stays current. Needle checks GitHub once a day; when a new release is out, an Update to 1.x.x… item appears right in the menu — or run needle --update. Your keys and settings carry over.

Something off? Run needle --text --debug to see the raw responses. The usage endpoints aren't officially documented and can change.

zsh
# clone, then run the installer
git clone https://github.com/KGthePM/Needle.git && cd Needle/mac
./install-mac.sh

Then click Add z.ai key… or Add OpenRouter key… in the menu and paste. Claude and ChatGPT/Codex just work.

Privacy-first, like everything we build

Your keys never leave your machine.

Needle talks to each provider directly and nowhere else. There's no Needle server to sign up for.

Runs locally

A small Python fetcher on your computer. Nothing in the cloud.

Keys stay put

Stored in one file in your home folder, sent only to the provider they belong to.

No telemetry

No analytics, no tracking, no phoning home.

Open source

Read every line on GitHub before you run it.

Stop guessing. Start glancing.

Free and open source. Takes about a minute to set up.

Get Needle on GitHub More from PineCompute