Based on repository activity, growth velocity and community engagement.
28
Growth2/30
Activity10/25
Popularity7/25
Trust10/20
46
Stars
High
Sentiment
Votes
46
README.md
AgentLimits
In Development
AgentLimits is a macOS Sonoma+ menu bar app with Notification Center widgets. It shows usage limits for ChatGPT Codex / Claude Code (5-hour + weekly, or monthly when the provider returns a monthly window), GitHub Copilot (monthly premium requests), and ccusage token usage.
Token usage (ccusage): daily/weekly/monthly tokens and cost via CLI.
Codex: npx -y ccusage@latest codex daily
Claude Code: npx -y ccusage@latest claude daily
Premium request usage (Copilot): daily premium request count and cost via WebView.
API: https://github.com/settings/billing/usage_table (fetched automatically with Copilot usage)
Menu Bar Display
Two-line layout per provider in the icon area
Line 1: provider name
Line 2: X% / Y% (5-hour / weekly)
For monthly-only providers such as Copilot or some Codex plans: X% (monthly)
Display mode: Used or Remaining (shared across app and widgets)
Status colors are based on pacemaker comparison when available (colors are configurable in Notification settings)
Status colors in the menu bar are automatically darkened or lightened to match the current menu bar text color.
Pacemaker indicator: optionally shows <used>%↑ when over pace
Toggle icon visibility per provider in Usage settings
Hide menu bar icon: completely hides the menu bar icon. While hidden, double-click the app icon in Finder (or open via Spotlight / open -a AgentLimits) while it is still running to temporarily show the icon and open Settings. Closing the Settings window hides the icon again.
Provider display order (Codex / Claude Code / Copilot) is configurable in Usage settings (Display Order)
Menu Dashboard
When you open the menu bar menu, a dashboard appears at the top showing per-provider usage at a glance:
Header: provider name · remaining time (5h window) · days until weekly reset, or monthly reset for monthly-only providers
Usage bar: linear progress bar color-coded by usage level; when pacemaker is exceeded, the bar is segmented (green → orange → red) matching the widget donut ring behavior
Pacemaker bar: divided into time segments (5h: 5 segments, weekly: 7 segments, monthly: single continuous bar) with gaps, matching the widget inner ring
Clicking a dashboard row opens the provider's usage page in the browser
Dashboard visibility is configurable per provider in Usage settings (Show dashboard in menu)
Menu also includes: Display Mode, Language (System/Japanese/English), Wake Up → Run Now, Start app at login, and Check for Updates...
Pacemaker
Pacemaker shows a time-based usage benchmark to help you stay on track.
Calculation: Elapsed percentage of the usage window (e.g., 50% = halfway through the 5h or weekly window)
Comparison: Green = on track or ahead, Orange = slightly over pace, Red = 10%+ over pace
Menu Bar: Shows <used>% (<pacemaker>)% with toggleable pacemaker value display (Pacemaker settings)
Widget: Outer ring = actual usage, inner ring = pacemaker percentage (shown when pacemaker data is available)
When usage exceeds pacemaker in used mode only, the outer ring is segmented and color-coded (green → orange → red) to show warning/danger zones (toggleable in Pacemaker settings, enabled by default)
Thresholds: Warning/danger delta thresholds are configurable in Pacemaker settings
Colors: Pacemaker ring/text colors are configurable in Pacemaker settings
Widgets
Usage Widgets (Codex / Claude Code)
Dual donut gauge: 5-hour and weekly windows side by side
Some Codex plans may show a single centered monthly donut when the Codex API returns only a monthly window
Color-coded percentage based on usage level and display mode
Update time shown as HH:mm (or --:-- if older than 24h)
Usage Widget (GitHub Copilot)
Single centered donut gauge: monthly premium interaction quota
Pacemaker inner ring divided into weekly segments (4–5 segments based on billing period)
Center label: 1mo
Color-coded percentage based on usage level and display mode
Update time shown as HH:mm (or --:-- if older than 24h)
Token Usage Widgets (Codex / Claude Code)
Small: today / this week / this month summary (cost + tokens)
Medium: summary + GitHub-style heatmap
7 rows (Sun–Sat) × 4–6 columns (weeks)
5 levels by quartile distribution
Weekday labels (Mon, Wed, Fri)
Desktop pinned mode support (accented / grayscale)
Widget tap action is configurable (default opens https://ccusage.com/)
Premium Requests Usage Widget (GitHub Copilot)
Small: today / this week / this month summary (cost + premium requests)
Medium: summary + GitHub-style heatmap
Data is fetched automatically when Copilot usage is refreshed (via WebView, no CLI required)
Widget tap action is configurable (default opens https://ccusage.com/)
Settings Guide
Usage
Open Usage.
Select Codex, Claude Code, or Copilot.
Choose refresh interval (1–10 minutes).
Toggle Show in menu bar to show the usage percentage in the icon area.
Toggle Show dashboard in menu to show/hide the provider's row in the menu dashboard.
Drag rows in Display Order to change the order of providers in the menu bar icon and dashboard.
Click the bottom login bar (▲) to expand the embedded WebView panel.
Sign in via the embedded WebView (chatgpt.com / claude.ai / github.com).
Use Clear Data to remove login data, website storage, and cached usage snapshots if sign-in gets stuck or you want to reset login history.
ccusage
Open ccusage.
Select provider (Codex / Claude Code).
Choose refresh interval (1–10 minutes).
Enable periodic fetch and set additional CLI args if needed.
Use Test Now to verify CLI execution.
For Copilot: billing data is fetched automatically when Copilot usage is refreshed — just enable the toggle.
Wake Up
Open Wake Up.
Select provider (Codex / Claude Code). Note: Copilot is not supported.
Enable schedule.
Choose hours to run (0–23).
Use Test Now to verify CLI execution.
Notification
Open Notification.
Request notification permission (first time only).
Select provider (Codex / Claude Code / Copilot).
Configure thresholds for each window (5-hour/weekly for Codex/Claude Code when available; monthly-only Codex and Copilot use the primary/monthly threshold).
Adjust usage colors (donut + status colors) if needed.
Pacemaker
Open Pacemaker.
Toggle the menu bar pacemaker value display.
Toggle the widget ring warning segments (color-coded segments when exceeding pacemaker).
Adjust pacemaker warning/danger deltas.
Customize pacemaker ring/text colors.
Advanced
Open Advanced.
Set full paths for codex, claude, npx if needed (blank = resolve via PATH).
Review PATH resolution results.
Choose widget tap action (open website / refresh data).
Toggle Hide menu bar icon to completely hide the icon from the menu bar. To access settings while hidden, double-click the app icon while it is still running.
Copy the bundled status line script path if needed.
