Software

AI

Alpymist does two things for people who work with AI models: it puts the vendors' command-line tools in the menu, and it shows in the bar how much of your limits you have used. Nothing is installed and nothing is asked of any vendor until you turn it on.

The tools

The AI menu starts each vendor's own command-line tool in a terminal:

Entry	Tool	From
Claude Code	`claude`	Anthropic
Codex	`codex`	OpenAI
Gemini CLI	`gemini`	Google

Starting one that is not installed offers to install it first. Each is installed its vendor's own way, with the command shown and asked about before it runs, in a terminal where you can watch it. Alpymist ships none of them.

alpymist-ai-usage tool run claude
alpymist-ai-usage tool install codex      # installing again updates it
alpymist-ai-usage tool remove gemini      # its login and settings stay

Install and Remove in the menu have the same entries.

Usage in the bar

The AI icon on the bar is dim until a provider is turned on. Click it for the popup: every provider has a row and a switch, and turning one on is where it is set up.

Provider	Shows	Needs
Claude	A Pro or Max subscription's 5-hour and weekly limits	Claude Code
OpenRouter	The month's spend, the key's limit, and credits left	An API key
Anthropic API	What the organisation's API use has cost this month	An admin key
OpenAI API	What the organisation's API use has cost this month	An admin key
GitHub Copilot	The month's premium requests, what is left, and when they reset	`gh`, logged in
ChatGPT (Codex)	A ChatGPT plan's 5-hour and weekly Codex limits	Codex, logged in
Gemini CLI	How much of each model's allowance is used	Gemini CLI, logged in

The last three read their figures in a way the vendor does not document. They are marked so where you turn them on, and may stop working.

Once a provider is on, the icon shows whichever is closest to a limit, and changes colour past the warning level. The popup shows each provider's meters and how old the answer is; a button asks them all again, and so does a right click on the icon.

Keys

A provider that needs a key has a field for it under its row in the popup. The key goes from there into your keyring and nowhere else: not into a file, and not onto a command line. While the keyring is locked, nothing is asked, and the bar says so.

alpymist-ai-usage list             # the providers, and which are on
alpymist-ai-usage status           # what each last reported
alpymist-ai-usage enable openrouter
alpymist-ai-usage key openrouter   # give a key again, typed unseen
alpymist-ai-usage disable openrouter   # off; its key stays in the keyring
alpymist-ai-usage forget openrouter    # forget its keys and its last answer
alpymist-ai-usage refresh

Settings

Settings › AI usage has a switch for each provider and these:

Setting	Default	Meaning
Warn from	80 %	How much of a limit is used before the bar changes colour
Notify when a limit is near	On	A notification when a provider passes that, and one more when it is nearly used up
Ask every	10 minutes	How often providers are asked. One that only reads this machine, as Claude's does, is asked more often.
Stop asking on battery below	20 %	Below this, on battery, nothing is asked and the last answers stay

Nothing is asked while the screen is locked.

Things to know

Claude's figures are as fresh as your last use of Claude Code on this account. Turning the provider on adds a status line command to Claude Code's own settings, keeps the one you had, and puts it back when turned off.
Claude Code has a status line in the prompt's colours unless you have one of your own: the directory, git, the model, how full the context is, your limits and the time. A new account starts with it, and turning the Claude provider on gives it to an account that had none. It is /usr/share/alpymist/claude-statusline.sh; to change it, copy it, and name your copy as statusLine in ~/.claude/settings.json.
A provider that reports only a spend has no limit to be near, so it is shown in the popup and never drives the icon's colour.
To take the icon off the bar, remove custom/ai from the bar's modules; see The top bar.

Adding a provider

A provider is a program that prints a report and a small file naming it, in /usr/share/alpymist/ai-usage/. Anyone can package one. What each provider can and cannot say has the research behind the shipped ones.

Edit this chapter on GitHub