Try free

Last updated 13 October 2026

Deal with rate limits in Claude CLI

Identify the causes of rate limits in the terminal

You are in the middle of a complex refactor when the terminal stops and returns a 429 error. This message indicates that you have exceeded the rate limits set by the Anthropic API. These limits exist to ensure fair resource distribution among all users. When the Claude CLI agent works on a project, it frequently sends requests to analyze your code, run shell commands via the Bash tool, or read files with the Read tool. Each of these actions contributes to your quota of requests per minute and tokens per minute.

A rate limit error usually happens when the agent enters a loop or when the context window becomes too large. If the agent repeatedly tries to fix a failing test and fails, it may trigger multiple API calls in rapid succession. Similarly, if the agent reads several large files into the session context, every following prompt will carry those tokens. This increases the load on the API and brings you closer to the throttle threshold. Understanding that the rate limit is a combination of how often you call the API and how much data you send is the first step toward a smoother workflow.

You can check your current standing by using the /status command within a session. This command provides an overview of the current state of your interaction. While it does not give you a countdown to when a 429 error will vanish, it helps you see if the agent is stuck in a repetitive task. If you see that the agent has performed the same Bash command five times without success, it is time to interrupt the process using the Escape key. Interrupting a runaway agent is the most effective way to prevent an immediate rate limit lockout.

Monitor your API consumption and session costs

Keeping track of your resource usage helps you anticipate when you might hit a limit. The Claude CLI provides two specific slash commands for this purpose. Use /usage to see the number of tokens consumed in your current session. This command breaks down the input and output tokens so you can see if a specific file or a long conversation is bloating your requests. Large input token counts are the primary reason for hitting per-minute volume limits.

The /cost command shows the financial impact of your current session. While the rate limit is based on technical throughput rather than dollars, there is a direct correlation between high costs and high token usage. If you notice the cost of a single session rising rapidly, it means the agent is processing a massive amount of information. Monitoring these figures allows you to decide when to reset the conversation or prune the context before the API forces a pause on your work.

If you are managing several different features at once, adhdTerminal can help you keep these costs and limits organized. adhdTerminal is a native app for macOS and Windows that runs many Claude Code sessions side by side as tiles on a wall. It shows whether a session is working, waiting, or idle. This visualization makes it easier to spot an agent that is consuming tokens unnecessarily in the background. By spreading your work across different tiles, you can manage separate contexts and avoid hitting a rate limit on one massive, overstuffed session.

Reduce token overhead with the compact command

As a session progresses, the context window fills up with every file the agent has used the Read tool on and every Bash command output. This history is sent back to the API with every new prompt you submit. When the history becomes too long, the token count per request spikes, which often leads to 429 errors even if you are only sending short messages. To fix this, use the /compact command. This tells the agent to summarize the work done so far and clear the detailed history from the active context.

The /compact command is a vital tool for long term development tasks. It preserves the essential progress and the state of the project while discarding the redundant details of every intermediate step. This significantly reduces the size of the payload sent to the Anthropic API. If you know you are about to start a new phase of a task, running /compact first is a good preventative measure. It resets your token overhead and gives you more breathing room within your per-minute limits.

You can also automate this behavior by configuring hook events. The PreCompact hook event allows you to define what happens right before a session is summarized. If you find yourself hitting rate limits frequently during long sessions, you may need to run /compact more often. This keeps the agent efficient and prevents the cumulative weight of a long conversation from triggering a 429 error. Managing the density of your session is just as important as the logic of your prompts.

Control tool execution using permission modes

The Claude CLI operates in different permission modes that change how the agent interacts with your system. By default, the agent may ask for permission before performing certain actions. If you use the bypassPermissions mode, the agent can run tools like Write, Edit, and Bash without stopping. While this is faster, it can lead to rapid-fire API calls if the agent gets confused. Rapid calls are a common trigger for rate limiting.

To manage this, you can cycle through permission modes using Shift+Tab. Switching to the plan mode allows the agent to outline its intended actions without executing them. This is a highly token-efficient way to work. You can review the plan, refine it, and then switch back to a more active mode to execute the steps. By planning first, you reduce the number of trial-and-error cycles the agent performs, which directly preserves your API quota.

You can also define specific tool permissions in your .claude/settings.json file. For example, you can require manual approval for the WebSearch or WebFetch tools while allowing the Read tool to function automatically. Restricting the most resource-intensive tools ensures that the agent does not go on a data-gathering spree that exhausts your rate limits. Setting these boundaries in your configuration file provides a layer of protection against unexpected API usage spikes.

Optimize project instructions in CLAUDE.md

The agent looks for a file named CLAUDE.md in the root of your repository to understand project-specific rules and instructions. If you find yourself repeating the same context or setup commands in every prompt, you are wasting tokens. Repeated information in prompts increases the size of every request. By moving these instructions into CLAUDE.md, you provide a stable reference point that the agent can access efficiently.

Structure your CLAUDE.md to include build commands, test patterns, and style guides. When the agent knows how to run tests or where to find logs, it spends fewer turns asking you for information or exploring the file system with Glob and Grep tools. Fewer turns mean fewer API requests. This efficiency helps you stay under the rate limit because the agent can reach the solution in a more direct path.

If you work on a monorepo or a project with distinct sub-modules, you can place a CLAUDE.md file in subdirectories as well. The agent will respect the instructions specific to that part of the tree. This localization of context prevents the agent from loading irrelevant information into the session. By keeping the context relevant to the task at hand, you minimize token usage and reduce the risk of triggering a 429 throttle.

Use multiple sessions to distribute the load

Hitting a rate limit in one session does not always mean you are blocked across all activities. If one session has become too large and is hitting 429 errors, you can start a fresh session in the same folder using the /clear command. This wipes the current context and lets you start over with a clean slate and zero token overhead. This is particularly useful if the current session has reached a point of diminishing returns where the agent is confused by its own history.

For developers who need to work on multiple features simultaneously, adhdTerminal offers a way to keep these sessions distinct and visible. Because adhdTerminal runs multiple Claude Code sessions side by side, you can designate one tile for refactoring, another for writing tests, and a third for documentation. This modular approach prevents any single session from becoming a massive token sink. You can monitor the status of each tile to see if any specific task is nearing its limit while continuing to work on others.

When you need to resume work after a break or a crash, use the claude --resume command. This allows you to pick from a list of earlier sessions. Choosing the right session to resume is better than starting a new one and re-explaining the entire project. However, if a resumed session is already near the context limit, remember to use /compact immediately to stay below the rate limits. Managing your sessions as discrete units of work is a professional way to handle API constraints.

Refine file interactions with targeted tools

The way the agent reads and writes files has a huge impact on your rate limits. The Read tool pulls the entire content of a file into the session. If you ask the agent to read a 2000-line source file, your input tokens for every subsequent request will increase by several thousand. Instead of reading everything, encourage the agent to use the Grep tool to find specific strings or the Glob tool to list files in a directory. This targeted search keeps the context small.

When it comes to making changes, the Edit tool is more efficient than the Write tool for large files. The Edit tool allows the agent to propose specific line changes rather than rewriting the entire file. Rewriting a large file via the Write tool consumes more output tokens and can be slower, increasing the chance of a timeout or a rate limit hit. If you see the agent attempting to rewrite large portions of the codebase, use the Escape key to interrupt it and suggest a more surgical approach.

You can also use subagents to handle specific sub-tasks. By creating markdown files in the .claude/agents directory, you can define specialized agents for tasks like code review or documentation. Running a subagent with the /agents command allows you to offload work into a separate context. This keeps the main session focused and prevents the primary context window from growing too large, which is the most common cause of sustained 429 errors.

Handle the aftermath of a 429 error

When you hit a 429 error, the best immediate action is to wait. Rate limits are usually calculated on a rolling window, so pausing for sixty seconds is often enough to clear the throttle. During this pause, avoid sending new prompts or retrying the failed command immediately. Repeatedly hitting the API while you are already throttled can sometimes extend the duration of the limit.

After the pause, use the /doctor command to ensure your installation and connection are still healthy. This command checks your configuration and connection to Anthropic's services. If the doctor command reports everything is fine, but you still hit limits, it is a sign that your current session is too heavy. Use /compact or /clear to reduce the token load before you try the prompt again. This proactive management ensures that your next request stays within the allowed boundaries.

Finally, check for any background processes that might be using your API key. If you have multiple terminal windows or other tools running Claude Code sessions, they all contribute to the same rate limit. Consolidating your work or using a tool like adhdTerminal to keep track of all active sessions can prevent these invisible conflicts. By being mindful of your total throughput across all windows, you can maintain a steady development pace without the frustration of constant 429 interruptions.

Questions people ask

Does the Claude CLI automatically retry after a 429 error?

The CLI has some internal logic to handle transient errors, but a 429 rate limit often requires a manual pause. If the agent stops, you should wait a minute before sending a new prompt. You can use the /status command to see if the agent is still trying to process a task or if it has completely halted.

Can I increase my rate limits through the terminal settings?

No, rate limits are controlled by the Anthropic API and are determined by your account tier and usage history. You cannot change these limits in .claude/settings.json or via any slash command. Your only option in the terminal is to optimize how many tokens you send to stay within your existing limits.

Will using a different model reduce the frequency of 429 errors?

It might help if the other model has different rate limit quotas on your account. You can switch models using the /model command to see if a different one provides more headroom. However, the most effective way to stop 429 errors is to reduce context size using /compact or /clear regardless of the model you use.

Read next

More on when it goes wrong·All posts