Last updated 13 October 2026
How subagents work in Claude Code
The bottleneck of linear development in the terminal
You are deep in a complex feature and suddenly notice three separate modules that need unit tests. You also realize a legacy utility class requires a complete refactor to support the new data types you just introduced. If you handle these tasks yourself using Claude Code in a single session, you quickly encounter a linear bottleneck. You find yourself waiting for the agent to finish reading long directory trees or writing large blocks of code before you can give it the next instruction. This idle time interrupts your flow and forces you to stay focused on one small task when your mind is already three steps ahead.
This waiting period is a common frustration for developers who move faster than their tools. You want to keep working on the core logic or the user interface while the repetitive work happens in the background. Traditional terminal setups often force you to open new tabs and manually re-contextualize the agent every time you want to delegate a task. This manual setup takes time and increases the mental load of managing multiple streams of work. You need a way to offload specific parts of your project to secondary workers that understand their specific roles without constant oversight.
Defining specialized roles in the agent folder
Claude Code addresses this delegation problem through the use of subagents. These are secondary agents that you can define to handle specific types of work within your project. You manage these definitions by creating markdown files inside a directory named .claude/agents at the root of your repository. Each markdown file represents a different subagent role. By giving a subagent a dedicated file, you are providing it with a persistent set of instructions that it will follow every time it is invoked.
The purpose of these files is to describe the personality, goals, and constraints of the subagent. For example, you might create a file called refactor.md that contains instructions on how to handle code cleanup. You would specify that this agent should prioritize readability and follow the specific style guides of your project. Because these instructions live in your repo, they are version-controlled and shared with your team. This allows everyone on the project to use the same specialized agents for common tasks like documentation, testing, or performance optimization.
Authoring subagent instructions with markdown
When you write a subagent file in .claude/agents, you are essentially creating a template for a new session. The content of the markdown file should be clear and direct. You do not need to use complex formatting. Instead, focus on defining the scope of the agent. You can tell a subagent to focus on the Read and Edit tools while avoiding the Bash tool if you want to limit its ability to run arbitrary commands. This provides a layer of safety and focus that a general session might lack.
It is helpful to think of these markdown files as an extension of your CLAUDE.md file. While CLAUDE.md provides general project instructions that every agent follows, the files in .claude/agents provide specific overrides or additional context for a particular job. You might create a subagent named tester.md that has specific knowledge of your CI pipeline and testing framework. This agent will still respect the root CLAUDE.md, but it will prioritize the testing instructions you provided in its own file. This hierarchy ensures that all agents stay aligned with the project goals while specializing in their assigned tasks.
Activating subagents within an active session
You interact with your defined helpers using the /agents command inside a running Claude Code session. When you type this command, the system looks into your .claude/agents directory and lists all the available subagents you have created. This allows you to quickly see which specialized tools are at your disposal. You can then tell the main agent to delegate a specific task to one of these subagents. For instance, you could instruct the main agent to use the tester subagent to generate coverage reports while you continue to modify the source code.
The main agent manages the lifecycle of the subagent. It passes the necessary context and instructions to the secondary process and waits for a signal that the work is complete. This delegation happens within the terminal interface, but it effectively splits the workload. The subagent operates in its own space, using tools like Glob and Grep to find relevant files and Edit to make changes. This allows for a modular approach where the main agent acts as a coordinator, ensuring that the work produced by the subagents integrates correctly with the rest of the project.
Monitoring subagent lifecycle and performance
Tracking the progress of a background task is handled through hook events. Claude Code includes several hooks that you can configure to trigger at specific moments. The SubagentStop hook is particularly important for delegation. You can set up your environment to trigger a system notification or run a custom script whenever a subagent finishes its assigned task. This means you do not have to keep checking the terminal to see if the work is done. You can stay focused on your primary task until you receive a signal that the subagent is ready for your review.
Other hooks like Notification and UserPromptSubmit also play a role in how you manage background work. If a subagent needs your input or hits a permission block, the system can alert you through these events. This automated monitoring system is essential when you have multiple agents running at the same time. It prevents a situation where a subagent is stuck waiting for hours because you did not realize it had stopped or encountered an error. By using these hooks, you create a responsive system that keeps you informed of the background state without requiring your constant attention.
Managing permissions for autonomous background work
Permissions are a major factor when running subagents in the background. By default, Claude Code operates in a mode where it asks for your approval before performing certain actions, especially those involving the Write or Bash tools. This can be a hurdle for subagents because they might pause and wait for your confirmation while you are working elsewhere. You can manage this by adjusting the permission settings in your .claude/settings.json file. Under the permissions key, you can specify which tools are allowed to run without a prompt for specific subagents or directories.
Inside a session, you can also use the Shift+Tab shortcut to cycle through different permission modes. If you trust the subagent to perform a routine task, you can switch it to bypassPermissions or acceptEdits mode. This allows the subagent to work autonomously until the task is complete. However, you should use this power carefully. It is often better to limit the subagent to a specific directory using a CLAUDE.md file in a subdirectory. This restricts the agent's scope and provides a safety net, ensuring that an autonomous subagent cannot accidentally modify critical files outside of its assigned area.
Visualizing multiple subagent workflows
Managing multiple subagents in a single terminal window can quickly become confusing. As you spin up more workers, keeping track of which agent is doing what becomes a challenge. This is where adhdTerminal provides a significant advantage for your workflow. It allows you to run multiple Claude Code sessions side by side as tiles on a visual wall. You can assign a specific color, number, and name to each tile, making it easy to distinguish between your main session and your various subagents. This visual organization replaces the clutter of many terminal tabs with a clear overview of your entire project status.
The adhdTerminal interface shows you at a glance whether a tile is working, waiting for your input, or finished. It displays the last few lines of each conversation, so you can see the progress of a subagent without having to switch focus. If a subagent running in one tile encounters an error, you will see it immediately on your wall. This allows you to manage a high volume of parallel tasks without losing the thread of any single conversation. It transforms the command line experience into a dashboard that matches the way your brain handles multiple streams of information.
Context sharing and resource management
Each subagent operates within its own context window. As the subagent uses the Read and WebSearch tools, its context fills up with information. If a task is very large, the subagent might reach its context limit, which can lead to degraded performance or confusion. You can manage this using the /compact command. This command summarizes the conversation so far and clears out unnecessary data, freeing up space for the agent to continue its work. It is a good practice to use /compact periodically during long subagent sessions to keep the logic sharp and focused.
Subagents also respect your project configuration, including the .gitignore file and any custom slash commands you have defined in .claude/commands. This ensures that the subagent does not waste resources reading files that are not relevant to the project. If you need to give a subagent access to a directory outside of its current scope, you can use the /add-dir command. This expands the subagent's view of the file system for that specific session. Proper resource management ensures that your subagents stay fast and do not incur unnecessary costs by processing data they do not need.
Handling errors and subagent termination
Sometimes a subagent may go off in the wrong direction or get stuck in a loop while trying to solve a difficult problem. When this happens, you need to intervene quickly. You can use the Escape key to interrupt the current tool execution of any active agent. If the subagent has made a series of mistakes, pressing Escape twice will offer you a list of earlier messages. You can select a previous state and jump back to it, effectively undoing the subagent's recent errors. This rollback capability is vital for maintaining the integrity of your code during autonomous sessions.
For even greater control, you can use the free adhdTerminal iPhone app to monitor your subagents while you are away from your desk. The app mirrors your wall of tiles over an end to end encrypted link, allowing you to see the status of every subagent from your phone. If a subagent finishes a long task or hits a block while you are grabbing coffee, you can answer a prompt or send the next task directly from the app. This level of connectivity ensures that your background tasks keep moving forward, even when you are not actively sitting at your computer. If a session becomes completely unsalvageable, you can always use the /clear command to start over with a fresh context in the same folder.
Questions people ask
Can subagents communicate directly with each other without my involvement?
Currently, subagents do not have a built-in mechanism to talk to one another directly. They operate as independent processes coordinated by the main Claude Code session or by your manual instructions. If you need them to share information, the main agent must act as the intermediary, or they must both read and write to shared files in the repository.
Do subagents increase the cost of using Claude Code?
Yes, every subagent session consumes tokens just like a primary session does. Each subagent has its own context window and makes its own API calls to process instructions and use tools. You can monitor the spend for any session by using the /cost or /usage commands to see exactly how many tokens the subagent has consumed during its run.
What happens to a subagent if I close the main terminal window?
If you close the terminal window or terminate the main process with Ctrl+C, the subagent sessions will also stop. However, you can resume your work later by using the claude --resume command. This allows you to pick up from the last state of a specific session, ensuring that you do not lose the progress made by your subagents even after a restart.
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.