Peras watches your plan's usage, tells you where the week is headed, and pauses the agent (or asks first) at the line you set.
$ npx peras-cli setup
v0.4 · free, MIT, local · Node 18+, no dependencies · peras remove takes the hooks out
Want both agents in your menu bar? The Peras app, €4.99 once.
$ peras status
Peras 🍐 watching ~/.claude
5h ▰▰▱▱▱▱▱▱▱▱ 24% resets 18:24 on pace for 75% at reset
7d ▰▰▰▰▰▰▰▰▱▱ 78% resets Sat 12:00 full by Thu 14:59
⚠️ weekly 78% (line 75%), weekly runs out Thu 14:59 at this pace (resets Sat 12:00).
This week by chat (≈: shared out by what each spent; claude.ai use counts too):
≈ +41% ~/code/app 7f3a9c21
≈ +12% ~/code/blog b81e04d7
Peras 🍐 watching ~/.codex
5h ▰▱▱▱▱▱▱▱▱▱ 12% resets 17:12 on pace for 21% at reset
7d ▰▰▰▰▱▱▱▱▱▱ 41% resets Sun 20:00 full by Sun 15:25
$
The Peras app for macOS
The pear sits next to your clock with each agent's 5-hour usage. Click it for the weekly bars, when each window resets, and a pause button for Claude Code and Codex separately.
- Clawd and the Codex companion walk along their 5-hour bars, and stand still while their agent is paused.
- Press ⌃⌥P to open it from anywhere, full-screen apps included.
- Prefer it quiet? Show the pear only, and pick which notifications you get.
$ peras menubar install --native --app ~/Downloads/Peras.app
The CLI and its guard stay free. Build the app yourself from the source, or use the free SwiftBar menu: peras menubar install
Thu 15:00
At your line, one of three things happens.
warn
A desktop notification. The agent keeps going.
ask
The next tool call waits for your OK, once per session. Even from your phone.
pause
Tool calls are refused and the turn ends, until it lifts or you run peras resume.
On pace to run out earlyperas set weekly pace pause
One prompt eats 3% of the weekperas set prompt 3 pause
Overnight runs, at 50%peras set 01:00-08:00 weekly 50 pause
Just this folder, at 60%peras set --here weekly 60 pause
Plan the week, not just the stop.
A daily allowance
Let an agent use ten percentage points today, with a fresh allowance at local midnight.
Room for each project
Set an estimated weekly allowance for a folder. Parallel account activity can count too; tracking gaps can miss usage.
See what happened
Weekly charts show observed usage, last-known remaining allowance, recording gaps and retained interventions.
Set today's allowanceperas budget daily 10 pause
Give this project five pointsperas budget --here weekly 5 pause
Edit rules and allowances visuallyperas settings
Keep a reserve across working daysperas pace 20
Switch saved allowance profilesperas profile use "Normal day"
Give today three more points for an hourperas extra daily 3 1h
See recently observed sessionsperas sessions
Review the week in Terminalperas review
Compare completed tracked weeksperas compare
“Use it or lose it” · 20%+ left within 48h of resetperas notify unused on
Allowances count observed increases in your weekly percentage. Daily tracking begins with the first reading each day. Reminders require the menu bar and a fresh reading. When one agent pauses, the menu can point out fresh allowance on the other.
Codex gets the same guard.
One command adds the same hooks to Codex desktop and the Codex CLI. Its own status, lines, pauses, allowances and history work there too: peras codex status, peras codex pause, and the rest.
$ peras codex setup
Its own lines
Codex's lines, history and pauses are kept apart from Claude Code's.
No tokens touched
Usage comes from your ChatGPT plan, read through Codex's own local app-server. Peras reads no login files.
Ask means wait
Codex has no approval prompt, so an ask line holds its tools until you run peras codex resume.
Ask it what's going on.
peras whyWhich line is acting, and when it lifts.
peras historyPast weeks: the peak, the lines crossed, and when it hit the wall.
peras pause 1h · peras pause 18:00Pause by hand, for a while or until a time.
peras resume 1hLift a stop for an hour instead of until the reset.
peras eventsRecent warnings, pauses, resumes and resets.
peras testTries a pause and resume on a throwaway copy of the hooks, for both agents.
peras doctorChecks that each agent's hooks actually ran lately.
peras notify resets onChoose your desktop notifications: warnings, pauses, resets.
peras updateThe newest Peras, with your hooks and menu bar refreshed. Your lines and history stay.
peras removeTakes out Claude's hooks and restores its status line; peras codex remove does Codex. Your rules and history stay.
Everything stays on your machine. The event log holds no prompts and no tool commands.
See the number. Choose the pause.
Monitoring
A usage display helps you decide when to stop. An alert asks you to notice it and act.
Peras's hook guard
At your configured line, supported hooks refuse guarded tool calls and end the turn. The CLI and hooks are free; the app is optional.
The boundary
Stale readings can make a pause late. Requests already in flight and tools outside hook coverage aren't stopped. This guards your own sessions.
Before you give the pear a job.
Is it safe to rely on a pause?
Use it as a guard for your own sessions. Usage is account-wide, folder and prompt numbers are estimates, and stale readings can make a pause late. Hooks do not cancel requests already in flight or stop a client that skips them. Default check failures may let work proceed; supported Claude Code versions offer opt-in strict checking.
Why pay if the source is MIT?
The CLI, hooks, SwiftBar menu and app source are free and MIT-licensed. €4.99 once gets the signed, notarized, ready-made macOS app and supports the work. Updates included. Get the app, open your purchase downloads, or build it yourself.
Does Peras track me or need an account?
No Peras account is required for the guard, and there is no product telemetry. State stays local. Codex reads usage through its own local app-server; update checks contact npm. Polar handles the separate app purchase and customer downloads.
Which Mac can run the app?
macOS 13 or later, with Node 18+. Builds include Apple silicon and Intel. Execution testing so far is Apple silicon with current macOS; macOS 13 and Intel execution are untested.
How do I install after using npx?
Keep using npx peras-cli for each command, or install globally with npm install --global peras-cli to get peras. Set up only your providers. Review and trust Codex hooks in /hooks, then restart sessions. After buying and unzipping the optional app into Downloads, run npx peras-cli menubar install --native --app ~/Downloads/Peras.app.
Do Claude and Codex share one limit?
No. Their provider usage windows, rules and pauses stay separate. Peras shows both together and can optionally tell each agent their saved usage context.
Claude Code weekly limitCodex usage limitSet a stopping point