Try free

Last updated 13 October 2026

Find logs for Claude Code subagents

Locating subagent definitions in the project structure

You launched a subagent to refactor a complex module and it started strong but now it is stuck. You expected a series of file changes but the agent finished its task without modifying the code. You need to see exactly what happened inside that sub-task. Claude Code does not have a separate log file specifically named for subagent internal thoughts. To troubleshoot effectively, you must first look at the source of the subagent instructions. These instructions define how the agent approaches a problem and what tools it prioritizes during its execution.

Subagents are not hidden deep within the binary of the tool. They exist as markdown files inside your repository within the .claude/agents directory. If a subagent is failing to follow your logic, the first place to investigate is the text of its definition file. You can use the /agents command inside an active session to see which agents are currently available to the system. By reading these markdown files, you can see if the subagent has the correct context or if it lacks the specific Bash or Edit permissions required to complete the task you assigned to it.

Reviewing the conversation history with keyboard shortcuts

When a subagent runs, it behaves like a nested session within your main terminal window. The detail of its work can quickly scroll past your view as the agent executes multiple steps. You do not have to rely on what is currently visible on the screen to understand what went wrong. The tool provides a built-in way to navigate the history of the conversation without leaving the interactive interface. This is the most direct way to see the log of thoughts and actions the agent performed while the subagent was active.

Pressing the Escape key twice in rapid succession opens a mode that allows you to move back through the history of the current session. You can use your arrow keys to scroll up and see the specific tool calls like Bash or Read that the subagent performed. This history includes the full output of every command. If a subagent silently failed because a shell script returned a non-zero exit code, you will find that error message here. This review mode is essential for catching the small mistakes that subagents often ignore when they report their final status to the main agent.

Tracking tool execution through hook events

Hooks provide a powerful way to monitor what is happening under the hood during complex tasks. Claude Code supports several hook events that trigger at specific points in the execution cycle. For subagent troubleshooting, the SubagentStop event is particularly useful. It allows you to see exactly when a subagent handed control back to the main agent. You can also look for Notification events that the system sends during execution. These events provide a timeline of the subagent behavior and help you identify if it is looping or getting stuck on a particular tool call.

To manage these hooks, you can use the /hooks command inside your session. While you cannot create custom binary hooks for every minor action, you can observe how the system handles the transition between the main agent and its subordinates. If a subagent is failing to start or ending prematurely, the hook sequence will show you the exact moment the failure occurred. This is as close to a real-time execution log as you can get without using external monitoring tools. It helps you distinguish between a logic error in the agent instructions and a system error in the tool execution.

Examining tool outputs for specific error messages

Subagents rely on a set of core tools to interact with your filesystem and environment. These tools include Bash, Read, Edit, Write, and Grep. When a subagent fails to complete a task, the error is almost always contained in the output of one of these tools. For example, if a subagent tries to use the Edit tool on a file it has not read yet, the tool will return an error. This error is logged in the session history even if the subagent tries to hide it or move on to a different approach.

You should use the /status command to see what the agent is currently tracking in its internal state. If a Bash command failed inside a subagent, the error message from the shell is the most accurate piece of data you have. Subagents often attempt to fix their own errors by trying a different command, which can clutter your terminal. By scrolling back to the first failed tool call, you can identify the root cause of the issue. This might be a missing environment variable, a permission problem, or a simple typo in a file path that the agent generated during its planning phase.

Using project instructions to increase verbosity

The CLAUDE.md file at the root of your project acts as the primary instruction set for all agent activities. You can use this file to force subagents to be more descriptive about their actions. Since there is no global setting to toggle a debug log, you must instruct the agent to create its own trail. You can add a section to your project instructions that requires subagents to use the TodoWrite tool to document their progress as they move through a complex refactor or a large scale search.

If you are working on a specific part of the tree, you can place a CLAUDE.md file in a subdirectory to apply more granular rules. Instruct the subagent to echo important state information to the terminal using the Bash tool. This creates a manual log that persists in your session history. By requiring the subagent to state its intent before every major file change, you make it much easier to audit its logs later. This approach turns the conversation history into a structured log that follows your specific debugging needs.

Managing parallel subagent tasks with adhdTerminal

When you run several complex subagent tasks across different parts of a large project, your terminal window becomes crowded and hard to manage. It is easy to lose track of which subagent is doing what when everything is compressed into a single scrollback buffer. This is where adhdTerminal provides a clear advantage for developers. It is a native app for macOS and Windows that runs many Claude Code sessions side by side on a single screen. Each session appears as a tile on a wall, which helps you visualize multiple streams of work simultaneously.

Each tile in adhdTerminal has a color, a number, and a name to help you keep your subagents organized. The tile shows the last exchanges of the conversation and indicates whether the session is working, waiting for you, or idle. This allows you to monitor the progress of a subagent in one part of your project while you actively code in another. If a subagent in one tile hits an error, you will see it immediately without having to switch contexts or scroll through thousands of lines of terminal history. It makes the execution of parallel agents much more transparent.

Verifying the environment with the doctor command

Sometimes subagents fail not because of poor instructions, but because the environment is not set up correctly. If you notice that subagents are consistently failing to use tools or are crashing unexpectedly, you should check the health of your installation. The claude doctor command is designed for this specific purpose. It checks your current configuration and ensures that the tool has the necessary permissions to function on your operating system. It also verifies your login status and connection to the necessary backend services.

Run this command from your shell outside of an active session to get a report on any potential issues. It might reveal that your permissions in settings.json are too restrictive for the subagent to perform its work. For example, if you have set your permissions to plan mode, a subagent might be unable to commit the changes it has spent time preparing. Use the /permissions command inside a session to verify that you have allowed the subagent to use the tools it needs. Correcting these environmental issues is often faster than rewriting the subagent logic.

Monitoring session costs and context limits

Subagents can be expensive in terms of both money and context space. If a subagent gets into a loop where it keeps reading the same files or trying the same failing Bash commands, it will quickly fill the context window. When the context window is full, the agent might start losing older information that was critical to the task. You can use the /cost and /usage commands to see exactly how many tokens the current session has consumed. This is a vital metric for troubleshooting because a sudden spike in usage often indicates a subagent that has gone off the rails.

To fix a bloated context, use the /compact command. This summarizes the session so far and frees up space for new instructions and tool outputs. This is particularly helpful when a subagent has generated a lot of logs that you have already reviewed and no longer need. If the session is beyond saving, you can use /clear to start over in the same folder. This wipes the slate clean while keeping your current project instructions and settings intact. Regularly managing your context ensures that your subagents always have the space they need to think clearly and log their actions accurately.

Accessing historical data from previous sessions

If you accidentally quit a session or your terminal crashes, the logs for your subagent tasks are not lost. You can carry on the most recent session in a folder by using the claude --continue command. If you need to go back further to find a specific subagent execution from earlier in the day, use the claude --resume command. This command provides a list of your previous sessions so you can pick the exact one you need to investigate. This persistent history is one of the most useful features for long term troubleshooting.

Once you have resumed a session, you can use the terminal history search tool by pressing Ctrl+R. This allows you to search for specific strings or commands that the subagent used. This is useful for finding where a specific file was edited or which grep command was used to locate a bug. In adhdTerminal, your tiles reopen in the same place after a restart and resume the same session automatically. This means you do not have to manually track which session ID belongs to which subagent task. The visual layout persists, allowing you to pick up exactly where your troubleshooting session left off.

Questions people ask

How can I see the exact Bash commands a subagent ran?

You should press the Escape key twice inside your session. This enters a history mode where you can scroll back through every turn of the conversation, including the full command and output of every Bash tool call. This is the most reliable way to find errors that the subagent might have bypassed.

Can I save the subagent logs to a file for later review?

You can use the /export command to save the entire session history to a markdown file. This file will include all tool calls, subagent responses, and user prompts in a readable format. It is a great way to document a complex debugging session or share the agent behavior with a teammate.

What should I do if a subagent is taking too long to finish?

Press the Escape key once to interrupt the agent and stop its current tool execution. After interrupting, you can use the /status command to see what it was trying to do. If it was stuck in a loop, you might need to use /compact to clear out old context or modify your CLAUDE.md to give it better directions.

Read next

More on claude code basics·All posts