Last updated 13 October 2026
Increase the timeout for Claude subagents
Identifying subagent cutoff in complex workflows
When you use subagents to handle deep research or massive refactoring tasks, you might find that the process stops before completion. This often happens because the subagent reaches an internal limit on how long a single tool can run. You might see a subagent begin a task and then simply go quiet or return a brief message saying it cannot continue. This is common when the Bash tool is running a long test suite or when the WebSearch tool is navigating several layers of documentation to find an answer. The default behavior of Claude Code is to protect you from runaway processes, but this sometimes interferes with genuine work that just takes a long time.
The cutoff is not a failure of the model logic but a constraint of the environment configuration. If you are asking a subagent to analyze a large repository using the Read and Glob tools, the cumulative time spent on these operations can exceed what the agent expects for a single turn. You will notice this most often during the planning phase or when the subagent is performing a sequence of edits across dozens of files. Understanding how to extend these limits allows you to delegate much larger chunks of work without having to micro-manage the subagent every few minutes. You want the subagent to work until the job is done, not until a timer expires.
Locating the configuration files for session limits
To fix these timeout issues, you must modify the settings files that Claude Code reads when it starts a session. You have three main locations for these settings. The most broad is the user settings file located at ~/.claude/settings.json. This file controls the behavior of the agent across every project on your machine. If you find that your subagents are always timing out regardless of the repo, this is the place to make your changes. It ensures that every new terminal session you open starts with the increased limits you require for your specific hardware and network conditions.
For project specific adjustments, you should look at the .claude/settings.json file in the root of your repository. This is useful when one particular project has a much larger build process or a more complex directory structure than your other work. If you are working in a team environment and do not want to commit your personal timing preferences to the repository, you can use .claude/settings.local.json instead. This file is ignored by most version control systems but allows you to override the global and project settings for your local environment. This is the safest place to experiment with very long timeout values.
Adjusting tool execution duration in settings
Inside your settings JSON file, you can find a section dedicated to permissions. This block defines how the agent interacts with tools like Bash, Edit, and WebSearch. While the configuration does not use a single global timeout key, it allows you to set limits on how individual tools operate. You should look for values that define the maximum duration for tool execution or the number of permitted steps in a single subagent call. By increasing these numbers, you give the subagent more room to finish heavy compilation tasks or long running scripts without being interrupted by the system safety checks.
When you modify these values, you should do so in small increments to find the balance between efficiency and safety. If you set the limits too high, a subagent that gets stuck in a loop might consume more resources than intended. Start by doubling the current duration values and then test the subagent with a task that previously failed. You can use the /config command inside a session to verify that the agent has loaded your new settings correctly. This command displays the active configuration so you can be sure your local overrides are taking effect before you start a long task.
Refining subagent behavior with agent files
Subagents follow specific instructions stored in the .claude/agents directory. Each subagent is defined by a markdown file that tells it how to behave and what tools to prioritize. If a subagent is timing out, it might be because the instructions are too broad, causing the agent to try to solve the entire problem in one go. You can edit these markdown files to include instructions about breaking down tasks. Tell the subagent to report progress frequently or to pause and ask for permission after completing specific milestones. This does not change the technical timeout but changes the behavior so the subagent finishes smaller tasks within the existing time limits.
You can also create specialized subagents for long running tasks. For example, you might create an agent specifically for running migrations or large scale data processing. By defining a custom subagent in .claude/agents, you can give it a specific scope that avoids the common pitfalls of a general purpose agent. This focused approach reduces the amount of context the subagent has to carry, which in turn reduces the processing time for each turn. A leaner subagent is much less likely to hit the wall during a complex operation because it is not wasting time on irrelevant files or broad searches.
Optimizing context to prevent processing delays
What looks like a timeout is often the subagent struggling with a context window that has become too full. As a session continues, the history of every file read and every command run is stored in the context. This makes every subsequent turn take longer to process. If the processing time exceeds the network timeout of the agent, the subagent will stop. You can fix this by using the /compact command. This command summarizes the conversation so far and removes the full text of previous exchanges while keeping the important facts. This drastically reduces the load on the subagent and often resolves timeout issues in long sessions.
Another way to manage this is through the CLAUDE.md file in your project root. This file holds project instructions and is read by every subagent. If you put too much information in CLAUDE.md, every subagent starts with a heavy context load. Keep your CLAUDE.md focused on essential build commands and code style. If a subdirectory needs specific instructions, place a separate CLAUDE.md file in that subdirectory. Claude Code will read the local file for that part of the tree, allowing subagents working in that folder to have the specific context they need without being slowed down by the entire project history.
Monitoring subagent status with adhdTerminal
Managing multiple subagents is difficult when you are limited to a single terminal window. If a subagent hits a timeout, you might not notice for several minutes while you are focused on another task. This is where adhdTerminal becomes a useful tool for your workflow. It is a native app for macOS and Windows made by MINDBALANCER OU in Estonia. It allows you to run many Claude Code sessions side by side, with each session appearing as a tile on a wall. Each tile has a color, a number, and a name, making it easy to distinguish between different subagents working on different parts of your project.
The wall shows whether a tile is working, waiting for you, or done. If a subagent times out or finishes its task, the tile status changes immediately. You can see the last exchanges of the conversation directly on the tile, which helps you understand exactly where the subagent stopped without having to click into the session. This visual overview is particularly helpful when you have increased your timeouts and are running long processes. You can monitor the progress of a dozen subagents at once, ensuring that none of them are sitting idle because they hit a limit you did not see.
Troubleshooting environment errors with the doctor command
If your subagents are timing out even on simple tasks, there might be an underlying issue with your environment. You should run the 'claude doctor' command to check your installation. This tool verifies that your API keys are valid, your network connection is stable, and that the agent has the necessary permissions to execute tools on your system. Sometimes a timeout is just a symptom of the agent being unable to access a specific directory or a tool like Bash being blocked by your operating system security settings. The doctor command will highlight these issues clearly.
You can also use the /status command during an active session to see the health of the current subagent. It provides information about the current tool being used and how long the session has been active. If you notice that the agent is consistently hanging on a specific tool, you can investigate that tool specifically. For example, if the WebFetch tool is causing the timeouts, you might have a proxy or firewall issue that is delaying the response. Addressing these environment specific problems is often more effective than simply increasing the timeout values in your settings files.
Using hooks to track subagent progress
Claude Code supports hook events that trigger at different points in a session. You can use these to gain visibility into what a subagent is doing right before it times out. Hook events like PreToolUse and PostToolUse are particularly helpful. You can configure these in your settings.json to log the start and end times of every tool execution. By looking at these logs, you can identify if a specific subagent is getting stuck on a particular command or if the delay is happening during the thought process of the model.
If you want to automate your response to timeouts, you can use the SessionEnd or Stop hooks to trigger notifications. This ensures you are alerted the moment a subagent stops working. By integrating these hooks into your development environment, you create a more resilient workflow. You can even set up a hook to run a script that checks the status of your build if a subagent stops unexpectedly. This data is invaluable for fine tuning your timeout settings because it tells you exactly how much more time your subagents need to complete their tasks successfully.
Recovering and resuming after a timeout
When a subagent does time out, you do not have to start the work over from the beginning. You can use the 'claude --resume' command to see a list of earlier sessions and pick the one that was interrupted. This command allows you to step back into the conversation right where the subagent left off. Once inside the session, you can use the /resume command to specifically target the last successful state. This is a powerful way to recover from a timeout without losing the work the subagent has already done on your files.
If the subagent stopped because it was confused or stuck in a loop, you can press Escape twice to see a history of earlier messages. This allows you to select a point in the conversation before the subagent went off track. You can then provide a new prompt with more specific instructions or a higher timeout limit. If you are away from your desk, the free adhdTerminal iPhone app mirrors your wall over an end to end encrypted link. You can see the status of your subagents on your phone and even send a prompt to resume a session that has timed out, allowing you to keep your project moving from anywhere.
Questions people ask
Can I set a different timeout for the Bash tool specifically?
Yes, you can configure tool specific permissions in your .claude/settings.json file. Within the permissions block, you can define the behavior for the Bash tool independently of other tools like WebSearch or Read. This allows you to give long running build scripts more time while keeping a shorter limit on other operations.
Why does my subagent stop even after I increased the limits?
The subagent might be hitting a context window limit rather than a time limit. When the conversation history becomes too large, the model takes longer to process each turn and eventually fails to generate a response. Use the /compact command to summarize the session and clear out unnecessary history to resolve this.
How can I see exactly which setting is causing the subagent to pause?
Use the /config command inside your Claude Code session to view all active settings and their values. This command will show you the effective configuration, including any overrides from your local or project files. If a subagent pauses, you can compare the task duration against the limits shown in the config output.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.