Hello HN! Today I am presenting you with Peras, the tool which governs your Claude Code and Codex usage, and enforces limits. I built it because I got tired of constantly having to spam /usage to check my usage, and decide if a task is worth risking the agent running out mid-task.

Peras enforces a limit with 2 main tiers. At 75% weekly usage you will get a notification, and at 90% Peras will automatically pause the agent. These limits are the default and they are customizable to your own liking.

You may ask "how does it know my usage in Claude Code or Codex?" Well, it's pretty simple. Peras gets the Claude Code usage % from the status line, and Codex's one comes from its local app-server. The "pause" Peras executes is a hook that refuses the agent's tool calls and ends its turn.

A new feature I implemented is one that makes agents aware of their own usage. When you send your prompt, Peras attaches the usage %. It sends it at the start of the session, then again at 50, 75, 90 and 100%, or if a reset is coming in 30 minutes, so the agent can hurry up and actually capitalize on the remaining usage, if any. Just to clarify, this feature is informational and the pause is what enforces the limit.

Before I switched to native SwiftUI, I used SwiftBar. The problem was that for the mascots patrolling their usage bars, I had to re-encode every menu image 8 times a second! There was also stuff SwiftBar wasn't capable of, like the menu being able to appear over fullscreen apps, pinning it as a floating panel, etc.

What is the difference between the free and paid version? Well, it is MIT, first of all. The CLI, the hooks, the SwiftBar menu, and the app's source are all on GitHub, but building the app needs macOS 13+, Node 18+, "xcode-select --install" and then finally "npm run build:app". The €4.99 buys you a signed copy which is notarized by Apple, with updates included. The guard works with no menu at all. To install, just run:

  npx peras-cli setup
  npx peras-cli codex setup

And now we get to the limits part. For now it's subscription plans only, and when running "claude -p", the pause uses the last interactive reading, so it can come late. Also I feel I have to mention that the guard rail is not a security boundary. It runs inside the agent. The menu is macOS only. The CLI and hooks pass tests on Linux in CI, but I don't use them there day-to-day.

Last thing before I end this post, I would really appreciate feedback from you, whether install worked for Codex users, whether you have encountered any bugs, or whatever you feel like sharing.