Last updated 13 October 2026
How to use the bug report command in Claude Code
Identifying when to report a technical issue
You are working on a complex project and the agent suddenly stops responding to your prompts. You might see a strange error message in the terminal that does not relate to your code. Sometimes the agent enters a loop where it tries to use a tool like Bash or Edit repeatedly without making any progress. These moments are frustrating and can stop your workflow. When the tool behaves in a way that seems like a software failure rather than a logic error, you need a direct way to tell the developers.
The built-in bug reporting system is the fastest way to send technical feedback to the team at Anthropic. You do not have to leave your terminal or open a browser to fill out long forms. The /bug command is designed to capture the exact state of your session so the engineers can see what went wrong. It helps them understand if the issue is a problem with the agent logic, the terminal environment, or a specific tool failure.
Running the bug command inside a session
To start a report, you must be inside an active interactive session. If the agent is currently busy running a task or writing code, you should press Escape once to interrupt it. Once you see the input prompt, type /bug and press Enter. The tool will then initiate a process to gather information about your current environment and the recent history of your conversation. This ensures the developers have the context they need to reproduce the failure.
The command will ask you to provide a description of the problem. You should be as specific as possible in this description. Describe what you expected to happen and what actually occurred. If a specific tool like Read or Write failed with a system error, mention that clearly. The tool will package your description along with technical logs. It usually asks for your final confirmation before it sends the data to the Anthropic servers. This gives you a chance to cancel if you change your mind.
Checking your environment with the doctor command
Sometimes what looks like a bug is actually a configuration issue in your local environment. Before you send a formal report, it is helpful to run claude doctor. You can run this command directly from your shell. It performs a series of checks on your installation. It verifies your internet connection and checks if you can reach the necessary API endpoints. It also looks for common permission issues that might prevent the agent from working correctly.
If you are already inside a session, you can use the /doctor slash command to perform similar checks. If the doctor identifies a problem with your setup, it will provide advice on how to fix it. Fixing these environmental issues often resolves the errors you are seeing. If the doctor says everything is healthy but the agent still fails, that is a strong signal that you should proceed with the /bug command to report a genuine software issue.
Managing configuration and permission modes
Bugs can sometimes be tied to how you have configured your project. Claude Code looks for instructions in a CLAUDE.md file at the root of your repository. It also checks for settings in .claude/settings.json or your global ~/.claude/settings.json file. If you have custom rules or tool restrictions, the agent might struggle to complete tasks. Use the /config command to review your current settings. This shows you which tools are allowed and which permission mode you are using.
Your choice of permission mode can affect how the agent behaves. You might be in default, acceptEdits, plan, or bypassPermissions mode. You can cycle through these modes by pressing Shift+Tab inside a session. If a bug only appears when you are in a specific mode, include that information in your report. Understanding the relationship between your local configuration files and the agent behavior helps the engineering team isolate the root cause of the problem.
Ensuring your installation is current
The team at Anthropic frequently releases updates to improve the stability of the tool. Before you report an issue, you should check if a newer version of the software is available. You can do this by running claude update in your terminal. This command will check the current version and install any available patches or new features. Many technical glitches and tool failures are resolved in these updates.
If you run into an error immediately after an update, it might be a regression. In this case, using the /bug command is very helpful for the developers. You can also use /release-notes to see what changed in the latest version. This can help you determine if a change in the software is responsible for the new behavior you are seeing. Keeping your tool updated ensures you are not reporting bugs that have already been fixed.
Monitoring multiple sessions with adhdTerminal
When you are working on several projects at once, it can be hard to tell if a bug is specific to one codebase or is a general issue with the agent. This is where adhdTerminal becomes a useful tool for your workflow. It is a native app for macOS and Windows that runs many Claude Code sessions side by side. Each session appears as a tile on a wall, showing you the status of each task at a glance. You can see if one tile is working, waiting, or idle while you continue working in another.
By observing multiple tiles, you can quickly spot patterns. If every tile is showing the same error, you know the problem is likely with your network or the Anthropic API. If only one tile is stuck, the issue is likely related to that specific project or its CLAUDE.md instructions. This extra visibility makes your bug reports much more accurate. You can provide details about which environments are affected, which helps the engineers find a solution faster.
Handling session context and history
A bug might be caused by a session that has become too large for the context window. As a session fills with conversation and file content, the agent can become confused. You can use the /compact command to summarize the history and free up space. If the agent starts working correctly after you compact the session, the issue was likely context exhaustion rather than a hard bug in the software.
If the session is completely broken, you can use /clear to start over in the same folder. This wipes the current conversation but keeps you in the same project. If you need to go back to a previous session to see when a bug first appeared, use the /resume command. It provides a list of earlier sessions for you to pick from. Tracking when a problem started is valuable information for any bug report you submit.
Privacy and data collection in reports
When you use the /bug command, it is important to understand what data is being sent. The report typically includes your recent terminal logs and snippets of the conversation. It might include parts of the files the agent has read using tools like Read or Glob. This data is necessary for the developers to see the exact state of the failure. However, you should be mindful of any sensitive information that might be present in your terminal output.
Review the information the tool prepares before you confirm the upload. If you are working in a highly secure environment with strict data privacy requirements, you may want to sanitize your terminal history before running the command. The /help command can provide more details on how the tool handles data. Most developers find the automatic logging helpful because it eliminates the need to manually collect evidence of a crash or an error.
Questions people ask
Does the bug command upload my entire project folder to Anthropic?
No, the /bug command does not upload your whole directory. It primarily captures the current session history, recent terminal logs, and specific diagnostic information. It only includes code snippets that were already part of the conversation context or recent tool outputs.
Can I use the bug command if I am not in an interactive session?
The /bug command is a slash command meant for use inside the interactive interface. If you cannot start a session at all, you should run claude doctor or claude update from your shell instead. These commands help diagnose installation and connection problems that prevent the agent from starting.
How do I provide feedback that is not a technical bug?
If you want to suggest a feature or give general feedback that is not a software failure, you can still use the /bug command and specify that it is a feature request in your description. Alternatively, you can use /help to see if there are other community or support channels available for general discussion.
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.