# Stay Within Limits

Use when long-running or parallel agent work must respect 5-hour and weekly usage...

- Repository: https://github.com/BuilderIO/skills (4626 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add BuilderIO/skills --skill stay-within-limits -g -a claude-code -y`
Codex: `npx skills add BuilderIO/skills --skill stay-within-limits -g -a codex -y`
Cursor: `npx skills add BuilderIO/skills --skill stay-within-limits -g -a cursor -y`
Gemini CLI: `npx skills add BuilderIO/skills --skill stay-within-limits -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add BuilderIO/skills`

## Description

Use when long-running or parallel agent work must respect 5-hour and weekly usage limits by checking usage between waves, pausing near the cap, and resuming only when the window is clear.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Stay Within Limits

Keep long-running agent work inside the current 5-hour and weekly usage windows.
Check usage before launching substantial work and between waves of parallel
subagents. If an active 5-hour or weekly limit is at or above 95%, pause new
work until the window is clear enough to continue safely.

## Core Loop

1. Run a bounded wave of work. Default to at most 3 parallel subagents unless
   the user or host gives a different throttle.
2. Wait for the wave to finish. Do not interrupt in-flight subagents just to
   save budget; that usually loses work.
3. Check current 5-hour and weekly usage with the host's usage/budget tool.
4. If either window is at or above 95%, stop launching work and schedule a
   self-contained resume when the relevant window should clear.
5. On resume, re-check the real window or block before continuing. Do not trust
   elapsed wall-clock time alone.

## Usage Signals

Prefer a first-party host usage tool when available. In Claude Code, use:

```sh
npx -y ccusage@latest blocks --active --json
```

Use the JSON to identify the active block start, current cost or percentage, and
time remaining. On wake, compare the active block start timestamp with the
previous one; a new timestamp is stronger evidence than "enough time passed."

If the tool reports cost instead of a direct percentage, convert through the
current account limit when known. For Claude Max-style 5-hour blocks, some users
prefer an earlier caution threshold around $500-550; treat that as a
user-configured guardrail, not a universal rule. The default stop rule is still
95% of the active 5-hour or weekly limit.

## Pausing And Resuming

When a wake/resume tool is available, schedule a wakeup for:

```txt
min(3600, secondsUntilWindowClears)
```

If the runtime clamps wake delays to 60-3600 seconds, chain wakeups for longer
waits. Each wakeup should re-check usage, reschedule if still over budget, and
continue only when the window is safely below the threshold.

The rest: https://github.com/BuilderIO/skills/blob/HEAD/skills/stay-within-limits/SKILL.md