the practical guide

Make your agent quota-aware.

limitcheck gives coding agents a small, stable answer before they start a large task: which windows exist, how much runway is left, and when each one resets.

install once Bootstrap the CLI and agent instructions.

npx --yes limitcheck

Quick start

Run the bootstrap from any directory. It installs the package globally, detects the agent surfaces on the machine, and adds the same runway-aware instructions everywhere it can.

Install

One command is enough. No account, API key, daemon, or hosted dashboard.

Expose usage

Your harness passes the provider’s usage snapshot to the CLI as JSON.

Plan the task

The agent reads the lowest remaining window and adjusts its scope before it spends.

Agent setup

The package carries the instruction layer with it. On install, limitcheck writes compatible guidance for the agent surfaces it finds and leaves existing files alone.

surfacefile

Codex / generic agents~/.codex/skills/limitcheck/SKILL.md

Claude Code~/.claude/skills/limitcheck/SKILL.md

Cursor~/.cursor/rules/limitcheck.mdc

OpenCode~/.config/opencode/skills/limitcheck/SKILL.md

Workspace fallbackAGENTS.md · CLAUDE.md

If a surface is not installed yet, its global file is simply skipped. The CLI and workspace instructions still work.

Usage

Agents should check before high-context work, long builds, multi-file changes, or anything that is expensive to resume. The status command is intentionally easy to pipe.

# the agent’s first move on a large task
limitcheck status --json

# pipe a snapshot from an adapter
cat usage.json | limitcheck status --json
limitcheck status --file usage.json --provider codex

The human-readable form is useful while wiring an adapter. Agents should prefer --json because it is stable and unambiguous.

Payload format

limitcheck does not own provider authentication. The harness that already has access to usage passes a compact snapshot at the adapter boundary.

codex-style

{
  "provider": "codex",
  "rateLimits": {
    "fiveHour": { "usedPercent": 38 },
    "weekly": { "usedPercent": 19 }
  }
}

cursor-style

{
  "provider": "cursor",
  "usage": {
    "monthly": { "used": 560, "limit": 1000 }
  }
}

normalized output

{
  "version": 1,
  "provider": "codex",
  "windows": [{
    "name": "weekly",
    "remainingPercent": 81,
    "resetAt": "2026-09-28T17:00:00.000Z"
  }]
}

Accepted window signals are usedPercent, remainingPercent, or used + limit. Unknown reset times stay unknown; they are never guessed.

The planning rule

The installed skill tells agents how to turn status into behavior. It is deliberately conservative: the lowest remaining window is the available runway.

remainingagent behavior

> 25%Proceed, but check again before another large phase.

10–25%Split the work, checkpoint frequently, and avoid unnecessary exploration.

≤ 10%Do not start a large task. Ask for a smaller slice or wait for reset.

Weekly and monthly windows matter most for planning. A five-hour window can look healthy while the weekly window is nearly exhausted.

CLI reference

commandpurpose

limitcheckBootstrap the CLI and detected agent instructions.

limitcheck installRun the bootstrap explicitly.

limitcheck install --workspace-onlyWrite only to the current workspace.

limitcheck status --jsonNormalize JSON from stdin or LIMITCHECK_SNAPSHOT.

limitcheck status --file usage.json --provider codexRead a named snapshot file.

limitcheck sample cursorPrint a safe local example.

Troubleshooting

“no usage input”

Pass JSON through stdin, use --file, or set LIMITCHECK_SNAPSHOT. limitcheck cannot infer private provider usage that the harness has not exposed.

The agent only sees the short window

Update the adapter to include every available window. Weekly and monthly limits are the planning signals that prevent a good-looking short window from hiding a bad runway.

The agent did not load the instructions

Run npx --yes limitcheck again. It is safe to rerun and does not overwrite existing guidance. You can always use limitcheck status --json explicitly.