Peras

Peras is a usage guard for people who run Claude Code and Codex against a Claude Pro/Max or ChatGPT plan. It watches both agents, tells you where the current week is heading, and then warns, asks, or pauses the agent at the line you set, so that one long task cannot burn the rest of your week. Running `peras status` prints a compact readout for each agent: the 5-hour and 7-day windows, how much of each is used, when each window resets, and an on-pace projection such as 'on pace for 75% at reset' or 'full by Thu 14:59'. The product is a free, MIT-licensed CLI plus hook guard, with an optional native macOS menu bar app that keeps the same numbers one glance away. A percentage in a usage bar tells you what you have spent, not what you are about to spend. A single long agent run can cross a weekly limit hours before you would have noticed, and by the time the number looks alarming the work is already gone. Peras draws an explicit distinction between monitoring and guarding: a usage display helps you decide when to stop, and an alert asks you to notice it and act, whereas Peras's hook guard actually refuses guarded tool calls and ends the turn once your configured line is crossed. The point is to make the stopping point a rule you set in advance rather than a decision you have to make mid-run. At your line, one of three things happens, and you choose which. `warn` sends a desktop notification while the agent keeps going. `ask` makes the next tool call wait for your OK, once per session, which Peras notes can be answered even from your phone. `pause` refuses tool calls and ends the turn until the pause lifts on its own or you run `peras resume`. Lines can be set per window and per trigger, for example `peras set weekly 85 pause` for a flat weekly line, `peras set weekly pace pause` to stop when you are on pace to run out early, `peras set prompt 3 pause` when one prompt eats 3% of the week, `peras set 01:00-08:00 weekly 50 pause` for overnight runs at 50%, or `peras set --here weekly 60 pause` for just the current folder at 60%. Beyond a single stop line, Peras lets you plan the week. A daily allowance lets an agent use a fixed number of percentage points today, with a fresh allowance at local midnight (`peras budget daily 10 pause`). A folder can be given an estimated weekly allowance (`peras budget --here weekly 5 pause`), though Peras is explicit that parallel account activity can count too and that tracking gaps can miss usage. `peras pace 20` keeps a reserve across working days, and saved allowance profiles can be switched with `peras profile use 'Normal day'`, so a normal day and a heavy day do not need the same rules. Extra room can be granted temporarily with `peras extra daily 3 1h`, and rules and allowances can be edited visually with `peras settings`. Allowances count observed increases in your weekly percentage, and daily tracking begins with the first reading each day. Peras also records what happened. `peras status` breaks the week down by chat, shared out by what each spent, and claude.ai use counts too; the demo output shows entries such as '≈ +41% ~/code/app' and '≈ +12% ~/code/blog'. Weekly charts show observed usage, the last-known remaining allowance, recording gaps, and retained interventions. `peras sessions` lists recently observed sessions, `peras review` reviews the week in Terminal, and `peras compare` compares completed tracked weeks. `peras history` reports past weeks with the peak, the lines crossed and when it hit the wall, while `peras why` says which line is acting and when it lifts, and `peras events` lists recent warnings, pauses, resumes and resets. A 'use it or lose it' notification can be turned on with `peras notify unused on` to flag 20% or more left within 48 hours of a reset. Peras works through agent hooks rather than by intercepting your account. `peras codex setup` adds the same hooks to Codex desktop and the Codex CLI in one command, and Codex's lines, history and pauses are kept apart from Claude Code's. Codex usage comes from your ChatGPT plan, read through Codex's own local app-server, and Peras states plainly that it reads no login files and touches no tokens. Because Codex has no approval prompt, an ask line there holds its tools until you run `peras codex resume`. Everything stays on your machine: no Peras account is required for the guard, there is no product telemetry, state stays local, and the event log holds no prompts and no tool commands. The payoff is that the weekly limit stops being something you discover and becomes something you control. Instead of watching a bar climb and guessing whether a long run will finish in time, you set the number in advance and let the guard end the turn at it, then resume when you actually want to continue, from the terminal or the menu bar. Pauses are reversible: `peras pause 1h` or `peras pause 18:00` stops by hand for a while or until a time, and `peras resume 1h` lifts a stop for an hour instead of until the reset, so the guard does not lock you out of your own work. Peras is candid about the boundary too. Stale readings can make a pause late, requests already in flight and tools outside hook coverage are not stopped, usage is account-wide, folder and prompt numbers are estimates, and default check failures may let work proceed, with opt-in strict checking on supported Claude Code versions, so it is best treated as a guard for your own sessions. The command list maps closely onto real workflows. An overnight or unattended run is the clearest case: `peras set 01:00-08:00 weekly 50 pause` holds the agent to 50% of the weekly window during those hours, so a scheduled job cannot consume the week while you sleep. A long single prompt is another: `peras set prompt 3 pause` catches the case where one prompt eats 3% of the week. Project-level work fits `peras set --here weekly 60 pause` or `peras budget --here weekly 5 pause`, limiting just the folder you are in. Day-to-day pacing fits `peras budget daily 10 pause` with a fresh allowance at local midnight, plus `peras extra daily 3 1h` when a day needs three more points for an hour. Anyone comparing tracked weeks uses `peras review` and `peras compare`, and anyone who wants to use up leftover allowance before a reset can enable `peras notify unused on`. Peras is aimed at developers who run Claude Code and Codex on a Claude Pro/Max or ChatGPT plan and want the weekly limit handled as a rule rather than a surprise. The CLI and hooks work through npm: `npx peras-cli` for each command, or `npm install --global peras-cli` to get `peras`, setting up only your providers and reviewing and trusting Codex hooks in `/hooks` before restarting sessions. The native app requires macOS 13 or later with Node 18+, and builds include Apple silicon and Intel, though execution testing so far is Apple silicon with current macOS and macOS 13 and Intel execution are untested. The CLI, hooks, SwiftBar menu and app source are free and MIT-licensed; €4.99 once buys the signed, notarized, ready-made macOS app with updates included, and Polar handles the separate app purchase and customer downloads. Diagnostics include `peras test`, which tries a pause and resume on a throwaway copy of the hooks for both agents, `peras doctor`, which checks that each agent's hooks actually ran lately, and `peras update`, which refreshes hooks and the menu bar while keeping your lines and history. Peras turns a usage bar into a stopping point you chose. Set the line once, let the hooks warn, ask or pause at it, and spend the rest of the week knowing the guard is holding the number for you.