What is Peras?
Peras is a local usage monitor and stopping guard for people running Claude Code or Codex with Claude Pro/Max or a ChatGPT plan. It tracks observed plan usage, shows how the week is progressing, and can intervene when usage reaches a limit you choose. The CLI, hooks, and SwiftBar menu are free and MIT-licensed; an optional ready-made macOS menu bar app costs €4.99 once.
Peras Features:
Usage Monitoring: Peras reads Claude Code usage and gets Codex usage through Codex’s local app-server, keeping each agent’s status and history separate.
Configurable Guardrails: Set a usage line for an agent and choose whether Peras notifies you, waits for approval, or refuses guarded tool calls and ends the turn.
Weekly Allowances: Set an estimated weekly allowance for a folder or let an agent use a chosen number of percentage points per day, refreshed at local midnight.
Usage History: Weekly charts show observed usage, last-known remaining allowance, recording gaps, and retained interventions for each supported agent.
Menu Bar Companion: The optional macOS app displays both agents’ five-hour usage, weekly bars, reset times, pause controls, and configurable notifications.
Local Event Log: Peras keeps state on your machine, requires no Peras account, and records neither prompts nor tool commands in its event log.
Peras Benefits:
Fewer Surprise Stops: Seeing usage trends and setting a stopping point can help you reserve plan capacity for work you still intend to do later in the week.
More Deliberate Runs: A daily or folder allowance helps you decide how much agent activity to devote to a task before starting a longer session.
Control Over Intervention: Choosing between a notification, an approval hold, and a hard stop lets you match the guard to how much oversight a session needs.
Less Account Switching: A shared menu bar view makes it easier to check both agents’ usage and pause status without treating their limits as one combined pool.
Private Local Tracking: Keeping usage state on your machine means you can use the guard without creating a Peras account or sending prompts to Peras.
Use Cases:
Long Coding Sessions: Set a usage threshold before a Claude Code or Codex session so guarded tool calls can pause work when the chosen line is reached.
Weekly Budgeting: Check observed usage and remaining allowance when deciding whether a project can use more of your plan before its weekly reset.
Folder-Based Projects: Assign an estimated weekly allowance to a project folder when you want to keep its agent activity within a planned share of usage.
Daily Work Limits: Give an agent a percentage-point allowance for the day when you want a fresh usage budget at local midnight.
Two-Agent Workflows: Monitor Claude Code and Codex together from the menu bar while keeping their individual limits, pauses, and histories distinct.

