explaingit

aqua5230/usage

Analysis updated 2026-06-24

★ 82PythonAudience · developerComplexity · 2/5LicenseSetup · easy

TLDR

Mac menu-bar app that shows Claude Code and Codex CLI quota usage by reading local log files, with session, weekly, project, and token cost views.

Mindmap

mindmap
  root((usage))
    Inputs
      Claude Code statusLine hook
      Codex session logs
      LiteLLM pricing cache
    Outputs
      Menu-bar percentage
      Session and weekly stats
      Token and cost estimate
    Use Cases
      Track Claude Code quota
      Estimate Codex API spend
      Spot which projects burn tokens
    Tech Stack
      Python
      macOS
      Tkinter
      LaunchAgent
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

See Claude Code session and weekly usage as a percentage in the macOS menu bar.

USE CASE 2

Estimate Codex CLI token costs from local conversation logs without using an API key.

USE CASE 3

Install the statusLine hook automatically with the popover button to start tracking Claude Code usage.

USE CASE 4

Run usage as a LaunchAgent so it starts when you log in to your Mac.

What is it built with?

PythonmacOSTkinterLaunchAgent

How does it compare?

aqua5230/usagehi-fullhouse/cybersecurity-skillsclawdbrunner/captcha-solver
Stars828281
LanguagePythonPythonPython
Setup difficultyeasyeasymoderate
Complexity2/52/53/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · easy Time to first run · 5min

Unsigned .app needs Ctrl-click and Open through Finder for first Gatekeeper bypass, for source install needs Python 3.13.

AGPL-3.0, copyleft license that requires network-served derivatives to share their source code.

In plain English

usage is a small Mac menu-bar application that shows how much of your Claude Code and OpenAI Codex CLI quota you have used. It pins a tiny percentage in the top-right of the screen, and clicking it opens a popover with session usage, weekly usage, the projects that used the most recently, and today's token count and a cost estimate. The README, written in Traditional Chinese with an English version available, is aimed at giving non-technical Mac users a clear walkthrough. The key design choice is that the numbers do not come from calling the Anthropic or OpenAI API. They come from log files the two CLIs leave on your own machine. For Claude Code, usage installs a small script called a statusLine hook, which Claude Code runs every time it refreshes its status bar. The hook receives the same JSON that Claude Code itself uses, writes it to ~/.claude/usage-status.json, and the menu-bar app reads from that file. For Codex, which has no equivalent hook, usage scans the conversation log files under ~/.codex/sessions/ and reads the rate_limits and token totals each conversation records. The only time usage talks to the network is when it needs to estimate a Codex cost and the local pricing cache at ~/.claude/pricing_cache.json is missing. In that case it downloads a public price table from the LiteLLM project, stores it, and refreshes it once a week. If that download fails it falls back to a built-in price table. Anthropic and OpenAI API keys are never read, and the macOS Keychain is never touched. There is a packaged .app on the Releases page that you drag to /Applications. Because it is not signed, the first launch needs a Ctrl-click and Open through Finder to get past Gatekeeper. The popover then offers an install hook button that wires up the Claude Code side for you. Developers running from source create a Python 3.13 virtual environment, run pip install -e ., and then python3 main.py --setup to install the hook. There is also a terminal-only TUI mode with a pixel-art Claude logo and a spinner, a --mock flag for previewing the UI with fake data, and a LaunchAgent script that starts usage automatically when you log in. The project is released under AGPL-3.0.

Copy-paste prompts

Prompt 1
Install aqua5230/usage from the Releases .app, walk through the Gatekeeper Ctrl-click trick, and click the install hook button.
Prompt 2
Run usage from source with a Python 3.13 venv, pip install -e ., and python3 main.py --setup to wire up the Claude Code hook.
Prompt 3
Add a new CLI to the usage repo that reads ~/.claude/usage-status.json and prints today's session percentage to stdout.
Prompt 4
Extend usage to support a third CLI by adding a log-file parser alongside the existing Claude Code and Codex readers.
Prompt 5
Modify usage to refresh the LiteLLM pricing cache daily instead of weekly and add a manual refresh button to the popover.

Frequently asked questions

What is usage?

Mac menu-bar app that shows Claude Code and Codex CLI quota usage by reading local log files, with session, weekly, project, and token cost views.

What language is usage written in?

Mainly Python. The stack also includes Python, macOS, Tkinter.

What license does usage use?

AGPL-3.0, copyleft license that requires network-served derivatives to share their source code.

How hard is usage to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is usage for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.

Alternatives & similar repos