The frustration of watching an autonomous agent hit a usage wall mid-execution is a shared pain point for power users of Anthropic’s Claude Code and OpenAI’s Codex. Peras, a newly released open-source utility, addresses this by enforcing strict usage limits and offering granular control over when these agents can proceed. Developed by Vertias, the tool monitors plan usage in real-time, predicting weekly consumption and allowing users to set specific thresholds that trigger warnings, prompts, or hard pauses.

Granular Control and Local Privacy

Peras operates entirely locally, requiring no API tokens and ensuring that no prompts or tool commands are stored in its event log. The tool integrates with both agents via CLI hooks, allowing users to set limits based on percentage usage, specific times, or even individual project folders. For instance, a user can configure the tool to pause Claude Code if a single prompt consumes more than 3% of the weekly allowance, or to restrict overnight runs to 50% of the weekly budget. This level of specificity helps prevent unexpected overages that could leave a critical task unfinished.

macOS Integration and Visual Feedback

Beyond the command line, Peras offers a native macOS application that sits in the menu bar. This companion app provides visual feedback through animated characters—Clawd for Claude Code and a Codex companion—that move along progress bars representing the 5-hour usage window. When an agent is paused, these characters stand still, offering an immediate visual cue. The app also allows users to trigger pauses or resume agents directly from the interface, supporting keyboard shortcuts like ⌃⌥P for quick access even in full-screen applications.

Proactive Planning and Historical Analysis

The tool goes beyond simple enforcement by offering planning features. Users can set daily allowances, reserve usage across working days, and view weekly charts that track observed usage and recording gaps. Commands like peras review and peras compare allow for historical analysis of past weeks, helping users adjust their workflows to better fit their subscription limits. For Codex specifically, the tool reads usage data through the local app-server without accessing login files, maintaining a clear separation between Claude and Codex usage histories.

Key Takeaways

  • Peras is a free, MIT-licensed tool that enforces usage limits for Claude Code and Codex to prevent mid-task interruptions.
  • It offers three intervention modes: warn (notification), ask (manual approval), and pause (hard stop).
  • The tool is fully local, respecting privacy by not storing prompts or tool commands in its event log.
  • macOS users can utilize a native menu bar app for visual monitoring and quick control.
  • Peras supports granular limits based on time, project folder, and percentage usage.

The Bottom Line

As agentic workflows become more complex, tools like Peras that offer guardrails against usage caps are becoming essential infrastructure for developers who rely on subscription-based AI agents. The ability to pause an agent before it hits a wall transforms a potential productivity killer into a manageable constraint.