Peras

Peras is a lightweight local tool that watches your Claude Code or Codex usage and stops the agent before you hit your weekly plan limit. It runs entirely on your machine, the CLI needs Node 18+ and no external dependencies, and comes with a macOS menu bar app that sits beside your clock. The site says the tool is free with an MIT licence, and the macOS app is a one‑time €4.99 purchase.

The core workflow starts with `npx peras-cli setup`, which installs hooks that intercept the agent's tool calls. `peras status` shows a real‑time bar; for Claude Code you see a 5‑hour segment filled to the point of usage, the percentage used, and the reset time (e.g., “75 % resets Sat 12:00”). You can specify a line value (default 75 %) with commands like `peras set --line 75`. When the bar reaches that line, Peras can warn, ask, or pause the agent. A warning triggers a desktop notification but lets the agent continue. An ask halts the next tool call until you press a key or run `peras resume`. A pause stops all tool calls until you run `peras resume` or the week resets. The macOS app lets you click the pear icon to open a full‑screen view of the bars and a pause button next to each agent.

Peras supports project‑level allowances. With `peras budget daily 10` you give all projects 10 % of the weekly allowance for the day. `peras budget --here weekly 5` gives the current folder five % of the week. You can create and switch between allowance profiles with `peras profile use "Normal day"`. Daily usage starts with the first reading of the day; the tool records gaps and shows them on the weekly charts.

The tool tracks two separate histories for Claude and Codex, and you can view past weeks with `peras review` or `peras compare`. Notifications come from the menu bar and can be limited to warnings, pauses, or resets. The CLI includes diagnostics (`peras doctor`) and a test mode (`peras test`) that runs on a copy of the hooks. All data stays on your machine; the tool reads usage from the local agent server and never touches any login files or tokens.