Try free

Last updated 13 October 2026

Reset the Claude Code config file

Identifying a broken Claude Code configuration

Your terminal might show a JSON parse error or simply stop responding when you try to launch Claude Code. This usually happens when the configuration file contains a syntax error or a setting that the tool no longer recognizes. You might have tried to edit the file to change your default model or adjust permissions and accidentally left out a comma or a quote. When the CLI cannot read the configuration file, it often fails to start entirely or reverts to a state where it asks for your login credentials repeatedly even though you have already authenticated.

You might also notice that the agent ignores your project instructions or behaves as if it has no memory of previous sessions. If the tool starts but acts unpredictably, the first step is to look at the hidden settings files on your machine. These files control everything from the permissions you grant the agent to the way the terminal interface appears. A manual reset is often the fastest way to get back to a working state without having to guess which specific line in a large JSON file is causing the conflict.

Locating the global configuration file

The primary configuration for Claude Code lives in your home directory. On macOS and Linux, the tool stores its global data in a hidden folder named .claude inside your user profile. The specific file is at ~/.claude/settings.json. If you are using Windows, this folder is located in your user profile directory, which you can usually find at C:\Users\YourName\.claude\settings.json. This global file is the master record for your user preferences and applies to every session you run regardless of which folder you are working in.

This file contains your authentication status and your preferred global permission modes. It also keeps track of which model the agent should use by default. Because this file sits outside your project repositories, it does not get cleared when you delete a folder or clone a new project. If you are experiencing issues across multiple different coding projects, the problem is almost certainly located in this global settings.json file. You will need to use a text editor or the command line to find and manage this file directly.

Checking for project level overrides

Claude Code allows you to set rules that apply only to a specific repository. These settings are stored in a .claude directory at the root of your project. Within this directory, you might find a file named settings.json or settings.local.json. The tool reads the local file first and uses those values to override the global preferences you set in your home directory. This allows you to have different permission levels or model choices for a high security project compared to a personal experiment.

If the CLI works fine in most folders but fails in one specific repo, the local configuration is the likely culprit. The settings.local.json file is particularly important because it is designed to hold your personal overrides that are not tracked by version control. If a colleague updated the main project settings and those changes conflict with your local environment, the agent might throw errors. You should check both the global and the project specific directories when you are trying to restore the tool to its factory state.

Executing a clean reset of the settings

The safest way to reset your configuration is to rename the existing files rather than deleting them. Start by closing all active terminal windows where the agent is running. You can use Ctrl+C to quit a session safely. Once the sessions are closed, navigate to the .claude directory in your home folder. Use a command to rename settings.json to settings.json.bak. This moves the potentially corrupted file out of the way while keeping a copy of your old preferences in case you need to reference them later.

After you have moved the global file, repeat the process for any settings.json or settings.local.json files inside your project directory. By removing these files, you force the tool to act as if it is being run for the first time. The next time you type the claude command, the CLI will look for these files and, finding none, it will generate a fresh set of default configurations. This process ensures that no legacy settings or syntax errors can interfere with the operation of the tool.

Verifying the new configuration is working

Once you have cleared the old files, start a new session by running the claude command in your terminal. The tool should prompt you to log in if you deleted the global settings file, as your authentication token is stored there. After logging in, you can check the state of your new configuration by using the /config slash command inside the interactive interface. This command displays all the current settings the agent is using, including the active model and the current permission levels.

You should also run the claude doctor command from your shell. This built-in diagnostic tool checks your installation and your environment to ensure everything is configured correctly. It will report if the new configuration files were created successfully and if the tool has the necessary permissions to access your files and the network. If the doctor command returns a clean report and the /config command shows the default values, your reset is complete and you can begin customizing your setup again.

Managing visibility with adhdTerminal

When you work on multiple projects simultaneously, it is easy to lose track of which settings are active in which terminal window. This is where adhdTerminal provides a significant advantage for developers. It organizes your various Claude Code sessions into a wall of tiles, where each tile clearly shows the project name and its current status. Because each tile represents a distinct session, you can quickly see if one project is using a different configuration than another without having to manually run the /config command in every window.

The adhdTerminal app also ensures that your tiles persist after a restart. If you have spent time configuring a specific project with custom instructions in CLAUDE.md or specific settings in the local directory, those sessions will reappear in the same place on your wall. This visual organization makes it much harder to accidentally delete the wrong configuration file. You can see the health of each session at a glance, allowing you to identify a configuration issue in one tile before it affects your entire workflow.

Restoring your preferred permission levels

A fresh configuration defaults to a mode where the agent must ask for permission before performing most actions. This is the default permission mode. While this is safe, you may want to restore your previous workflow by changing the mode. You can do this inside a session by using Shift+Tab to cycle through the available modes. These include plan mode for thinking without acting, and acceptEdits mode for a more automated experience. The tool saves these choices back to your settings.json file automatically.

If you want to set specific permissions for individual tools like Bash or Write, you must edit the settings.json file manually. Look for the permissions section in the JSON structure. You can define which tools are allowed to run without a prompt and which ones should always ask for your confirmation. After a reset, taking a few minutes to reconfigure these permissions ensures that the agent can work efficiently while still respecting the security boundaries you require for your specific environment.

Troubleshooting issues that persist after a reset

If you have deleted your configuration files and the tool still shows errors, the problem might be with the installation itself. Run the claude update command to ensure you are using the most recent version of the CLI. Sometimes a bug in an older version of the tool can cause it to misinterpret even a perfectly valid configuration file. Updating the tool often resolves these underlying logic issues that a simple settings reset cannot fix.

You should also check for a CLAUDE.md file in your home directory or project root. While this is not a JSON configuration file, it contains instructions that guide the behavior of the agent. If this file contains conflicting or confusing instructions, the agent might appear to be broken even if the CLI itself is functioning perfectly. Review your ~/.claude/CLAUDE.md file to ensure no global instructions are interfering with the new settings you have just established.

Syncing settings across different workstations

Keeping your Claude Code environment consistent across different machines requires manual effort. Since the configuration lives in hidden local files, you can copy your ~/.claude/settings.json file from one computer to another to bring over your preferences and permission levels. However, be careful not to overwrite the unique identifiers that the tool might use for specific hardware or local paths. It is usually better to copy the specific sections of the JSON that you have customized rather than the entire file.

For developers who need to keep an eye on their sessions while away from their main computer, adhdTerminal offers a free iPhone app. This app mirrors your wall of tiles over an end to end encrypted link, allowing you to see the progress of your tasks and even send new prompts. This does not replace the need for local configuration files, but it provides a way to maintain continuity in your work across different devices. By combining a clean local configuration with remote monitoring, you can maintain a stable and productive coding environment.

Questions people ask

Will resetting my config log me out of the tool?

Yes, deleting the global settings.json file in your home directory will remove your authentication token. You will need to run the claude login command or simply start a new session with the claude command to re-authenticate with your browser.

What happens to my shell history after a reset?

Your shell history remains intact because it is managed by your terminal, not by the Claude Code configuration files. You can still use Ctrl+R to search through your previous commands even after you have cleared your settings.json files.

Do I need to delete the .mcp.json file to reset the tool?

Only if you are having issues with MCP servers. The .mcp.json file handles the configuration for Model Context Protocol servers, which is separate from your main user preferences. If your issue is related to the CLI interface or basic agent behavior, you should focus on the settings.json files first.

Read next

More on when it goes wrong·All posts