Last updated 13 October 2026
Edit the global config for Claude Code
Locate the global settings file
You are likely tired of re-configuring your environment every time you start a new coding task. When you use Claude Code across multiple repositories, you quickly realize that setting up the same preferences over and over is a waste of time. You want a way to define how the agent behaves, which tools it can use, and how much permission it has without repeating yourself in every project folder. This is where the global configuration file comes into play, allowing you to set a baseline that applies to every session you launch on your machine.
The global configuration for Claude Code lives in your home directory. Specifically, you will find it at ~/.claude/settings.json. This file governs how the CLI behaves regardless of which project folder you are currently working in. If you find yourself changing the same settings every time you start a new repository, this is the file you need to modify. Opening this file in a text editor allows you to see the current state of your preferences. It is a standard JSON file. If the directory or the file does not exist yet, running the CLI for the first time usually creates the necessary structure. You can navigate there using your terminal or open it directly with your favorite editor to begin making permanent adjustments to your workflow.
Use the slash command for quick changes
While you can edit the JSON file manually, the CLI provides a built-in way to view and change configuration. Inside an active session, you can type /config to see your current settings. This command displays what is currently active, including any overrides from local project files. It is an efficient way to verify if your global settings are being applied as expected. The /config command also allows you to change values on the fly. If you want to switch the default behavior of the agent for your current session and future ones, this is often faster than hunting down the file path.
However, remember that the CLI distinguishes between global settings and project-specific settings. Changes made through the interactive interface will be saved to the appropriate JSON file based on the scope you define during the configuration process. This interactive method is less prone to syntax errors than manual editing. It helps you stay within the terminal environment without breaking your flow. Once you have made a change through /config, the agent will immediately respect the new settings for the duration of the session and persist them to the ~/.claude/settings.json file if you chose the global option.
Configure permission levels across all projects
One of the most common reasons to edit the global config is to manage how much autonomy you give the agent. Claude Code operates in different permission modes such as default, acceptEdits, plan, and bypassPermissions. If you prefer to always review every change before it happens, you can set your global default to a more restrictive mode. This prevents the agent from making accidental edits to your filesystem without an explicit confirmation. You can cycle through these modes manually inside a session by using Shift+Tab, but setting a global default ensures you start every project with your preferred safety level.
You can also define permissions per tool within the settings.json file. For instance, you might want the agent to have free rein with the Read and Glob tools but require a prompt for the Write or Edit tools. By setting these in ~/.claude/settings.json, you establish a safety baseline that follows you across every repository. This saves you from having to re-configure security preferences every time you start a new task or switch projects. The agent will check these permissions before executing any tool, ensuring that it never exceeds the boundaries you have defined for your machine.
Set project instructions with global markdown
Beyond simple key-value pairs in JSON, you can influence the behavior of the agent using markdown files. While each project can have its own CLAUDE.md in the root directory, there is a global version located at ~/.claude/CLAUDE.md. This file is the perfect place for instructions that apply to every single line of code you write. If you have a preferred naming convention or a specific way you like your documentation formatted, put it here. This file acts as a permanent set of guidelines that the agent reads every time it starts a session.
The agent reads these global instructions alongside any project-specific ones. This creates a hierarchy of context. The global file acts as your personal coding standard, while the local CLAUDE.md handles project-specific logic like build commands or test runners. This setup ensures that the agent always knows your general preferences without you needing to repeat yourself in every new folder you initialize. It is a powerful way to maintain consistency across a diverse set of projects, from small scripts to large enterprise applications.
Manage MCP servers at the global level
Model Context Protocol or MCP servers extend the capabilities of the agent by connecting it to external data sources or tools. You can manage these servers using the claude mcp command or by editing the .mcp.json configuration file. When you set up an MCP server globally, it becomes available to the agent across all your projects. This is useful for tools that are not tied to a specific codebase, such as a personal knowledge base or a specialized search tool. Keeping these configurations in a central location simplifies your setup and reduces maintenance overhead.
Configuring MCP servers requires providing the necessary connection details in the JSON structure. If you need to troubleshoot a connection, the /mcp slash command inside a session will show you the status of active servers. Keeping these configurations in a central location means you do not have to manage multiple identical server configurations across different folders. This reduces the risk of credentials or connection strings becoming out of sync. It also ensures that the agent always has access to the external tools it needs to complete complex tasks effectively.
Balance local and global settings
It is helpful to understand how Claude Code resolves conflicts between different configuration files. The hierarchy starts with the global ~/.claude/settings.json, followed by the project-level .claude/settings.json, and finally the .claude/settings.local.json file. The local file is designed for overrides that you do not want to track in version control, such as personal API keys or environment-specific paths. When you edit your global config, you are setting the floor for your experience, which can be refined at the project level.
If a project has specific requirements that differ from your global preferences, the project-level file will take precedence. This flexibility allows you to maintain a consistent environment while still being able to adapt to the unique needs of a specific codebase. You can use the /status command to see which files are currently influencing the agent's behavior. This visibility is crucial for debugging why an agent might be behaving differently in one folder compared to another, helping you manage the complexity of multiple configuration layers.
Verify changes with the doctor command
After making manual edits to your JSON files, you should ensure that the configuration remains valid. Use the claude doctor command from your terminal to run a health check on your installation. This command checks for common issues, including malformed configuration files or missing dependencies. It is a reliable way to confirm that your changes to ~/.claude/settings.json have not introduced syntax errors that might crash the CLI. Regular checks can prevent subtle configuration errors from affecting your productivity.
Inside an active session, you can also use the /doctor slash command. This provides a similar diagnostic report but focused on the current environment. If the agent starts behaving unexpectedly after a config change, these tools are your first line of defense. They help you identify whether the problem lies in the global settings, a local override, or a broader issue with the CLI installation itself. Keeping your configuration healthy ensures that the agent can focus on writing code rather than struggling with a broken environment.
View global effects in adhdTerminal
When you manage several projects at once, you might find it hard to keep track of how your global settings are performing across different contexts. This is where adhdTerminal provides a visual advantage. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and is not affiliated with Anthropic. It runs many Claude Code sessions side by side, where each session is a tile on a wall. Each tile has a colour, a number, and a name, showing you exactly whether an agent is working, waiting for your input, done, or idle.
Because adhdTerminal tiles reopen in the same place after a restart and resume the same session, you can see your global configuration in action over long periods. Each tile shows the last exchanges of its conversation and can show numbers and headlines the project publishes. This setup is helpful for developers who need to mirror their wall to a free iPhone app over an end-to-end encrypted link to answer prompts or send the next task. It costs 99 dollars once, and one key runs one computer at a time, providing a 7 day free trial with no account required.
Automate with hooks and custom commands
Advanced users can further customize the global experience by using hooks and custom commands. Hooks allow you to trigger actions at specific points in the agent's lifecycle, such as SessionStart or PreToolUse. These are defined in your configuration and can be used to set up your environment or log activity. By placing these in your global config, you ensure that every session benefits from the same automation, regardless of which project you are currently working on.
You can also create custom slash commands by adding markdown files to the .claude/commands directory. While these can be project-specific, you can also set up global commands that provide shortcuts for repetitive tasks. For example, a custom command could quickly summarize your recent changes or run a specific set of diagnostic tools. This level of customization transforms the CLI from a general-purpose agent into a personalized development assistant tailored to your specific habits and requirements.
Questions people ask
Can I use different models for different projects?
Yes, you can specify a preferred model in the project-level .claude/settings.json file or use the /model slash command within a session. The project-specific setting will always override whatever you have defined in your global ~/.claude/settings.json file.
How do I reset my global configuration to the defaults?
You can either delete the ~/.claude/settings.json file or rename it to something else. The next time you run the claude command, the CLI will automatically recreate the default configuration files with the standard settings.
Will my global settings be shared if I push my project to a repository?
No, global settings stay on your local machine in your home directory. Only files inside the project folder, such as .claude/settings.json or CLAUDE.md, are typically included in a repository if they are not specifically excluded by your .gitignore file.
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.