Last updated 13 October 2026
View and edit the Claude Code config file
Locate the global configuration file
The main global configuration file for your environment is located at ~/.claude/settings.json. This file is the central hub for all your user-level preferences and persists across every project you work on. When you first install the agent, this directory might not exist until you run the claude command for the first time. It is a standard JSON file that you can modify to change how the agent interacts with your terminal and your code.
Finding this file is the first step when you want to change the default behavior of your sessions. On macOS and Linux, the tilde represents your home directory. On Windows, you will find this folder in your user profile path. Because it is a hidden directory, you might need to enable the option to see hidden files in your file explorer or use the command line to navigate there. Keeping your global settings in this one place ensures that your favorite themes and model choices follow you from project to project.
Edit the global settings file directly
You can edit the ~/.claude/settings.json file with any text editor you prefer. If you are already in a terminal, using a tool like vim or nano is often the fastest way to make a quick change. Inside the file, you will see various keys that correspond to different aspects of the agent. You can set the default model or adjust the visual theme to better suit your eyes. This direct editing method is powerful because it allows you to see every available option at once.
Always check your syntax when editing the JSON file directly. A missing comma or a misplaced quote can cause the agent to fail when it tries to load your preferences. If you make a mistake, you can use the claude doctor command to diagnose if the configuration file is causing issues. It is a good practice to make a backup of your settings before making major changes. This way, you can quickly revert to a known working state if the agent stops behaving the way you expect.
Use the configuration command inside a session
You do not always need to leave the agent to change your settings. While you are in an active session, you can use the /config slash command. This command provides an interactive way to view and change your current environment. It is often faster than hunting for a file when you are in the middle of a coding task. The changes you make through this interface are typically saved to your global or project settings automatically.
The interactive menu is designed to be fast and intuitive. You use your keyboard to navigate through the different categories and toggle options. This is often safer than editing the JSON file manually because the interface prevents you from entering invalid values or breaking the file structure. Once you finish making your changes, the agent applies them immediately to the current session. This allows you to test new settings without having to restart the command.
Handle project specific overrides
Sometimes a specific repo requires different rules than your global defaults. You can create a .claude folder in your project root and add a settings.json file there. These project-level settings take priority over the global ones in your home folder. This allows you to enforce certain tools or styles for a specific team or language. This is useful for teams that want to enforce a specific coding style or restrict the agent to certain tools while disabling others.
For personal preferences that you do not want to commit to a shared repository, use .claude/settings.local.json. This file is ignored by most version control systems if you add it to your gitignore. It allows you to have your own custom theme or specific model choice that does not interfere with the settings used by the rest of your team. By using a combination of global, project, and local settings, you can create a highly tailored environment that works perfectly for your specific needs.
Manage permission modes and tool approvals
One of the most common reasons to edit your config is to manage how the agent handles permissions. You can set the default permission mode to default, acceptEdits, plan, or bypassPermissions. If you find yourself manually approving too many actions, you might switch to acceptEdits to streamline the process. You can also cycle through these modes using Shift+Tab while a session is active. You can define specific permissions for different tools in the settings.json file.
Tools like Bash, Write, and Edit can have their own approval requirements. If you trust the agent to read files but want to review every write operation, you can configure that specifically. This granular control is essential for maintaining security while benefiting from the speed of an autonomous agent. You can also use the /permissions command to quickly check which tools are currently authorized and make adjustments as your project evolves without breaking your focus.
Configure model preferences and themes
The agent allows you to specify which model you want to use by default. You can change this in your global settings file or by using the /model command. Switching models can be useful if you have different requirements for speed or reasoning depth. Your configuration file stores these choices so you do not have to specify them every time you start the command with claude. This saves time and ensures consistency across your different work environments.
The visual theme is another setting that lives in the config file. If you work in a high-contrast environment or prefer a specific color palette, you can adjust this to match your terminal setup. The agent respects the settings you provide to ensure the text remains readable. You can also use /terminal-setup to help align the agent with your specific shell and terminal emulator, which ensures character encoding and features function correctly.
Organize multiple sessions with adhdTerminal
Managing many different configuration files across several projects can become difficult to track. This is where adhdTerminal becomes a useful addition to your developer toolkit. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. It runs many Claude Code sessions side by side, where each one is a tile on a wall. This visual organization makes it easy to see which settings and project instructions are active in each window.
A tile has a color, a number, and a name to help you separate your work contexts. The app shows whether a session is working, waiting for you, done, or idle. It also displays the last exchanges of its conversation and can show headlines the project publishes. Tiles reopen in the same place after a restart and resume the same session. A free iPhone app mirrors the wall over an end to end encrypted link. It costs 99 dollars once, and one key runs one computer at a time and can be moved, with a 7 day free trial and no account required.
Verify settings and troubleshoot
After editing your configuration files, it is a good idea to verify that the agent is reading them correctly. You can run claude doctor to check the health of your installation and see if there are any issues with your setup. This command helps identify common problems like syntax errors in your JSON files or missing directories. It provides a quick summary of your environment to ensure everything is functioning as expected before you start a long coding session.
If you notice the agent is not behaving according to your new settings, check for conflicting files. Remember that project-level settings override global settings. You can also use the /status command within a session to see the active configuration. If things go wrong, you can always use /clear to reset the session or use the double Escape key combo to go back to an earlier message in your conversation history. These built-in tools give you complete control over your development environment.
Questions people ask
Can I use different settings for different folders?
Yes, you can create a .claude/settings.json file in the root of any project folder. These local settings will take precedence over your global configuration in ~/.claude/settings.json. This is useful for project-specific rules or tool restrictions.
What should I do if my config file causes the agent to crash?
Run the claude doctor command to identify syntax errors or invalid keys in your JSON file. If you cannot fix the error, you can delete the file and the agent will create a new one with default values the next time you start it. Always ensure your JSON uses double quotes and proper commas.
How do I change the default permission mode permanently?
Open your ~/.claude/settings.json file and look for the permissions section. You can set the default mode to bypassPermissions, plan, or acceptEdits to change how the agent asks for approval. You can also use the /config command within a session to update this setting interactively.
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.