Peras

Product Introduction

1. Definition: Peras is a local, open-source (MIT-licensed) CLI tool and optional native macOS menu bar application designed as a usage guard and budget manager for AI coding agents, specifically Anthropic's Claude Code and OpenAI's Codex (via the ChatGPT plan). It functions as a real-time monitoring and intervention layer that operates via system hooks.
2. Core Value Proposition: It exists to prevent unexpected overage and budget depletion within the fixed weekly usage limits of Claude Pro/Max and ChatGPT plans. Its core value is providing predictable AI agent cost control, automated usage pausing, and granular budget allocation for developers and teams, ensuring one long-running task cannot consume an entire week's allowance.

Main Features

1. Dual-Agent Real-Time Monitoring: Peras independently monitors both Claude Code and Codex usage by reading local application state files (~/.claude, ~/.codex). It provides a unified terminal (peras status) or menu bar view showing 5-hour and 7-day usage percentages, reset times, and pace projections. For Codex, it reads usage data through the local Codex app-server API without touching login tokens.
2. Configurable Automated Intervention Hooks: The core guard functionality uses installable hooks that intercept tool calls. Users can set "lines" (thresholds) that trigger one of three actions: warn (desktop notification), ask (requires manual approval for the next tool call), or pause (automatically refuses tool calls and ends the turn). Lines can be based on weekly percentage, prompt cost, pace, or a specific time window.
3. Granular Budget & Allowance System: Beyond simple hard stops, Peras introduces a proactive budgeting system. Users can allocate daily allowances (resets at local midnight) or project-specific weekly allowances (peras budget --here). Features like peras pace reserve a percentage for future days, and peras extra grants temporary additional allowance. This allows for weekly AI usage planning rather than just reactionary stopping.
4. Historical Analytics & Review: The tool provides a data layer for understanding usage patterns. Commands like peras review, peras history, peras compare, and peras sessions offer insights into past weeks' peak usage, effectiveness of set lines, per-chat/folder cost estimates, and tracking gaps, enabling data-driven budget refinement.

Problems Solved

1. Pain Point: The "runaway agent" problem where a single complex coding task or overnight script consumes a disproportionate or entire week's fixed AI usage limit, leading to blocked access and disrupted workflows.
2. Target Audience: Freelance developers and small engineering teams on Claude Pro/Max or ChatGPT Plus/Team plans who rely on AI coding assistants for daily work and need to manage fixed, prepaid quotas. Tech leads who need to allocate shared team AI resources across projects.
3. Use Cases: A developer starts a large refactoring task with Claude Code and sets a prompt 3 pause rule to prevent any single prompt from using more than 3% of the weekly limit. A team uses peras budget --here weekly 5 to allocate 5% of the weekly limit to a specific project repository. A user sets a 01:00-08:00 weekly 50 pause rule to prevent unsupervised overnight runs from using more than half the remaining weekly allowance.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros: Operates fully locally with no telemetry or required account (privacy-focused). Offers fine-grained, proactive budget management, not just hard stops. Provides unified monitoring for two major AI coding agents. The CLI/core guard is free and open-source (MIT). Native macOS app offers convenient at-a-glance monitoring.
   • Cons: Relies on reading local state files, so stale readings can cause delayed pauses. Cannot cancel requests already in flight. Hooks may be bypassed by clients that do not support or skip them. Folder-based tracking is an estimate and may not account for parallel account activity outside the monitored directory. The native app is macOS-only.

2. Key Alternatives & Differentiation:

   • Manual Tracking: Users manually check the Claude or ChatGPT usage web pages.
     • Differentiation: Peras automates monitoring, provides real-time projections, and enables automated action, eliminating the need for constant manual vigilance.
   • Provider Native Alerts: Claude and OpenAI may offer basic usage alerts via email or UI.
     • Differentiation: Native alerts are informational only and lack automated intervention. Peras provides actionable guards (pause/ask) and sophisticated per-project/daily budgeting not offered by the providers.
   • Generic Time Trackers: Tools like Toggl or RescueTime.
     • Differentiation: These track time, not token/usage percentage against a specific AI plan's limit. Peras is purpose-built for the specific cost structure and hook integration points of AI coding agents.

Frequently Asked Questions (FAQ)

1. Is Peras safe and private? Yes, Peras is designed with privacy as a core principle. It requires no account, sends no product telemetry, and all your usage data, rules, and history remain locally on your machine. For Codex, it reads usage through the official local app-server API.
2. How reliable is the automatic pause feature? The pause is a guard for your own sessions, not an absolute guarantee. Its effectiveness depends on up-to-date local usage readings; stale data can cause a delayed pause. It cannot cancel requests already sent to the API. Users should treat it as a robust safety net, not an infallible hard limit.
3. What's the difference between the free CLI and the paid app? The core CLI tool, monitoring hooks, guard logic, and SwiftBar menu script are completely free and MIT-licensed. The €4.99 one-time purchase is for the pre-built, signed, and notarized native macOS menu bar application, which offers a more integrated and convenient user experience. The functionality is identical.
4. Can I use Peras to manage a shared team limit? Peras is primarily designed for individual machine/user monitoring. While its budgeting features can help an individual allocate shares of their personal limit, it does not currently offer multi-user coordination or centralized management for a single shared account used across multiple machines.
5. Does Peras work with Claude.ai web usage or only Claude Code? Peras directly monitors Claude Code via local files. However, usage from claude.ai (the web interface) contributes to the same weekly account limit and is reflected in the total usage percentage that Peras reads, so it is accounted for in the overall monitoring and guard triggers.