Guide · Updated 2026-10-24

Guide Coding agents Rate limits

How to check Codex and Claude Code rate limits from your terminal (and let the agent act on them)

Q: Do I need a SuperCompress account to use Runway?

No. runway_check runs in the local plugin and does not need an account. supercompress limits reads the same local sources.

Q: Does Runway work with Claude Code?

Yes. setup connects Claude Code's statusline as a tee so rate_limits events are recorded. Your own statusline keeps working. If you skipped that step, run supercompress limits connect claude-code once.

Q: How do I turn it off?

Set SUPERCOMPRESS_RUNWAY=0. That stops setup from touching the statusline and turns off proxy header capture. uninstall also reverses the wiring.

Q: What if there is no usage data yet?

The action is unknown. Carry on, and never invent a limit. Codex writes rate-limit events after the first model turn. Claude Code reports them through its statusline after the first reply.

By Arjun Shah

A 5-hour or weekly provider window can close while a coding agent is still mid-task. SuperCompress 0.5.40 ships Runway: supercompress limits (alias runway) and the local MCP tool runway_check. They read provider rate-limit data and return an action the agent can follow: go, pace, land, wait, or unknown.

October 24, 2026 · Guide

Why do rate limits matter in long agent sessions?

Coding agents often spend a whole provider window on one job: a refactor, a failing test, a multi-file edit. Codex and Claude Code both expose 5-hour windows and longer weekly (or monthly) caps. When that window closes mid-task, the model stops. The working tree may have uncommitted edits, a half-written handoff, or a test run that never finished.

Knowing the runway does not add quota. It tells the agent whether to keep going, shrink the next step and write a checkpoint, or stop and wait for the reset. That is the difference between a clean landing and a session that dies on a hard cutoff. Weekly and monthly windows work the same way over a longer stretch: the agent still needs an instruction, not only a remaining-quota number on screen.

What does `supercompress limits` show?

Run it in a terminal. runway is an alias for limits. Human-readable text is the default. --json prints one JSON object on stdout so an agent can parse action, proceed, scope, waitMinutes, and alternatives.

supercompress limits
supercompress limits --json
supercompress runway

Each answer is one of these actions:

Action	What the agent should do
`go`	Keep working. `scope` may be `large` when a short window would otherwise reset with unused quota, so the agent can take on more in this window.
`pace`	Returned under `--policy balanced` when a long window is ahead of pace. Prefer cheaper steps until it catches up. The default policy is `max`, which does not switch to `pace`.
`land`	Keep working, but commit or write a handoff note before each step. A 5-hour window resets on its own. Unused quota in that window is lost, so the agent should not stop early.
`wait`	A window is exhausted. Checkpoint, then wait `waitMinutes` or switch to a provider listed in `alternatives`.
`unknown`	No data source yet. Carry on, and never invent a limit.

The text formatter in the plugin prints a header, one line per window, then guidance. Placeholder values only:

runway · codex · GO
  5h window         … left · resets in <duration> · ok
  weekly            … left · resets in <duration> · ok
  → Plenty of runway. Proceed; checkpoint before long multi-step operations.

The JSON summary field is the same idea in one line, for example codex go · 5h window … left, resets in <duration>. When there is no source, the header is runway · unknown · no usage data for this agent yet plus a hint that names the missing source (Codex after the first turn, Claude Code after the first statusline reply, or an ingest/proxy path).

Where does the data come from?

Runway reads local rate-limit sources. It does not guess a number when none of these have data.

Source	Harnesses
`~/.codex/sessions` rate-limit events (zero config)	Codex
Statusline tee, wired by `setup` or `supercompress limits connect claude-code`. Your own statusline keeps working.	Claude Code
Upstream rate-limit headers seen by the local proxy (Anthropic, OpenAI, xAI, OpenRouter, Codex)	Harnesses routed through `localhost:8080` (Aider, Continue, Cline, OpenCode, Goose)
`supercompress limits ingest --provider <id>`, or `SUPERCOMPRESS_LIMITS_SNAPSHOT`	Cursor, Windsurf, Grok Build, Gemini CLI, custom hooks

Codex needs no extra wiring: after the first model turn in a session, rate-limit events are already in ~/.codex/sessions. Claude Code reports rate_limits on its statusline JSON after the first reply. setup wraps that statusline as (tee || cat) | <your statusline>, so the existing command still runs. If you skipped setup, supercompress limits connect claude-code does the same wrap once.

The optional local proxy records provider rate-limit headers (and retry-after on 429) for traffic sent through localhost:8080. Harnesses that have no local quota telemetry can pipe a usage JSON payload to supercompress limits ingest --provider <id>.

How does the agent use Runway?

The local MCP server registers runway_check. Call it before large or multi-step work. Optional arguments: provider (for example codex or claude-code) and policy (max, balanced, or conservative). The tool returns the same fields as supercompress limits --json. It runs in the local plugin. The hosted MCP URL does not have runway_check.

setup and plugin add the runway rule to agent instructions and skills automatically, register runway_check on the local MCP, copy a standalone runtime to ~/.supercompress/runway/, and connect the Claude Code statusline. uninstall reverses that wiring. Set SUPERCOMPRESS_RUNWAY=0 to opt out: setup will not touch the statusline, and the proxy will not capture rate-limit headers.

The rule the plugin writes is short: on go, proceed (scope: large means take on more); on land, keep working and checkpoint before each step; on wait, checkpoint and wait waitMinutes or use alternatives; on unknown, carry on and never guess a limit.

How is this different from usage-display CLIs?

Tools such as ai-usage-cli, aistat, aiquota and cclimits show remaining quota to a person. Runway turns the same kind of data into an instruction the agent can follow. You can still read the text output yourself. The extra piece is action (and --json / runway_check) so the session can go, land, or wait without you watching the meter.

How do I install Runway?

npm install -g supercompress-proxy && supercompress setup

Setup detects the coding agents on the machine and wires Runway with the rest of the plugin. Restart the agent so it loads the local MCP server. Then:

supercompress doctor
supercompress limits

doctor prints a per-agent health matrix, including a Runway line when the runtime is present. supercompress uninstall removes only SuperCompress entries (MCP registrations, hooks, instructions, the runway statusline wrap) and leaves other MCP servers in your configs.

FAQ

Do I need a SuperCompress account to use Runway?

No. runway_check runs in the local plugin and does not need an account. supercompress limits reads the same local sources.

Does Runway work with Claude Code?

Yes. setup connects Claude Code's statusline as a tee so rate_limits events are recorded. Your own statusline keeps working. If you skipped that step, run supercompress limits connect claude-code once.

How do I turn it off?

Set SUPERCOMPRESS_RUNWAY=0. That stops setup from touching the statusline and turns off proxy header capture. uninstall also reverses the wiring.

Does the hosted MCP include `runway_check`?

No. Runway runs in the local plugin. The hosted MCP URL does not have runway_check. Use the local MCP server or supercompress limits --json.

What if there is no usage data yet?

The action is unknown. Carry on, and never invent a limit. Codex writes rate-limit events after the first model turn. Claude Code reports them through its statusline after the first reply.

Coding agents guide All coding agents