Last updated 13 October 2026
Limit the number of Claude subagents
Preventing runaway recursion in complex tasks
When you give Claude Code a complex project, it often uses the Task tool or spawns subagents to break down the work. This recursive behavior can solve hard problems, but it also creates a risk of runaway processes. You might return to your terminal after five minutes to find that several agents have spent significant credits on a loop. This usually happens when the agent tries to fix a bug by introducing a new one, triggering a cycle of failed tests and attempted fixes.
Controlling this behavior starts with understanding how these sub-tasks are triggered. The agent decides to spawn a subagent or start a new task based on the complexity of your prompt and the instructions in your CLAUDE.md file. If you do not set hard boundaries, the agent will continue until it thinks the job is done or it hits a safety limit. You need to intervene before the recursion gets out of hand and consumes your entire budget.
Defining tool permissions in settings files
Limit subagent activity through the settings.json file. Find this file in the .claude directory of your project or in your home directory at ~/.claude/settings.json. This file allows you to define exactly which tools the agent can use and whether it needs your permission every time. By restricting the permissions for tools like Bash or Edit, you force the agent to stop and wait for your input before proceeding with deep changes.
Inside your settings.json, use the permissions key to manage tool access. While I do not know of a specific setting that sets a maximum integer for subagent counts, you can control the flow by setting specific tools to require manual approval. If you set the agent to always ask before running a Bash command, any subagent it spawns will also be forced to wait for your confirmation. This prevents a chain of automated actions from running without your oversight.
Using permission modes for manual oversight
Claude Code offers different permission modes that you can cycle through using Shift+Tab during an active session. These modes are default, acceptEdits, plan, and bypassPermissions. If you are worried about the agent spawning too many sub-tasks, start your session in plan mode. In this mode, the agent will describe what it intends to do without actually executing the tools. This allows you to review its strategy before any subagents are even created.
Once you are happy with the plan, switch to acceptEdits or default mode. If you notice the agent starting to loop or spinning up too many sub-tasks, hit Escape to interrupt the current process. Pressing Escape twice will even let you go back to an earlier message in the conversation to redirect the agent. This manual oversight is the best defense against a subagent that has lost its way in your codebase.
Monitoring session costs and usage
Keep an eye on your spend to detect runaway subagents early. Use the /cost slash command frequently during a session to see how much the current conversation has cost. If the cost is rising faster than expected, it is a sign that the agent is either reading too many files or spawning expensive sub-processes. The /usage command provides a broader view of your activity and helps you understand the impact of complex tasks on your account.
If you find that a session has become too bloated with sub-task history, use the /compact command. This summarizes the session and frees up context space, which can sometimes stop an agent from getting confused by its own previous failed attempts. If the session is beyond saving, /clear will let you start over in the same folder with a fresh slate. This prevents the agent from carrying over the overhead of a failed recursive loop into your next prompt.
Managing agent definitions and project instructions
Exert more control over subagents by creating specific markdown files in the .claude/agents directory. These files act as templates for how subagents should behave when they are invoked. If you find that the agent is creating too many generic sub-processes, define a specific agent that has a more limited scope. By documenting exactly what a subagent should and should not do, you reduce the chance of it wandering into unrelated parts of your codebase.
The agent also respects the instructions in your CLAUDE.md file. Add a section to this file that explicitly forbids the creation of subagents for certain types of tasks. For example, state that the agent should never attempt to refactor more than one file at a time without asking first. Because Claude Code reads CLAUDE.md at the start of every session, these rules provide a persistent set of guardrails for every sub-task it generates.
Running side by side sessions with adhdTerminal
When you run multiple complex tasks, the standard terminal can become a bottleneck. It is hard to keep track of which subagent is doing what when everything is buried in one scrolling window. This is where adhdTerminal becomes useful. It allows you to run many Claude Code sessions side by side as tiles on a wall. You can see the status of each session at a glance, whether it is working, waiting, or idle.
By naming each tile and giving it a color, you can separate your main development task from experimental sub-tasks. If one tile starts a heavy recursive process, monitor its progress visually while working on something else in another tile. If you see a tile stay in the working state for too long without producing a headline or a number you expect, jump in and check the last exchanges. This visual overview makes it much harder for a runaway subagent to go unnoticed.
Restricting context with directory commands and ignore files
Subagents often spiral out of control because they have access to too much context. If an agent starts searching your entire repository for a small bug, it might spawn sub-tasks to analyze every folder it finds. Prevent this by being specific about the context. Use the /add-dir command to point the agent toward specific subdirectories relevant to the task. This keeps the agent focused and reduces the likelihood that it will spawn broad search agents.
Claude Code also respects your .gitignore file. Use this to exclude large directories that the agent does not need to see, such as build artifacts or dependency folders. If you have specific files that are only relevant to your local setup, use .claude/settings.local.json to manage overrides that do not get tracked in your repository. By narrowing the field of vision, you naturally limit the number of sub-tasks the agent needs to create to understand the project.
Observing lifecycle events through hooks
The hook events provide a way to see exactly when subagents are starting and stopping. Events like SubagentStop and Notification give you clues about the internal lifecycle of the agent's work. While you cannot currently write a script to automatically kill a subagent based on a hook, you can use the output of these events to understand the patterns that lead to runaway processes.
If you notice that a specific type of prompt always leads to a Notification or a Stop event that signals a failure, adjust your CLAUDE.md instructions. The goal is to create a feedback loop where you refine your project instructions based on how the agent actually behaves. Over time, this reduces the number of unnecessary subagents and makes the ones that do run more efficient and targeted.
Questions people ask
How do I stop a subagent immediately?
Press the Escape key once to interrupt whatever the agent is doing. If you need to go back and undo the prompt that caused the subagent to spawn, press Escape twice to see a list of earlier messages. You can also use Ctrl+C to quit the entire session if the agent becomes unresponsive.
Can I set a hard limit on the number of subagents in settings.json?
There is no single setting to set a numeric cap on subagents. Instead, use the permissions section in your settings.json to require manual approval for tools like Bash or Task. This forces every new sub-process to wait for your permission before it can execute any meaningful work.
Will /clear stop all running subagents?
The /clear command resets the current session and removes the conversation history from the context. This effectively stops any active sub-tasks associated with that session. It is a good way to recover if the agent has gotten stuck in a loop or has created too much confusing 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.