Settings.json

Module: Configuration | Lesson: 3 of 5 | Time: ~10 minutes

What You Will Learn

Where settings.json files are located on Windows
The difference between global and project settings
Key options you can configure
How to create and edit your settings file

Prerequisites

Completed Writing Effective CLAUDE.md Files

Main Content

What Is settings.json?

While CLAUDE.md tells Claude about your project, settings.json tells Claude Code about your preferences. It controls the application itself -- things like visual theme, permission defaults, allowed tools, and connected services.

Think of it this way:

CLAUDE.md = instructions for Claude (the AI)
settings.json = configuration for Claude Code (the application)

Where settings.json Lives

There are two levels of settings on Windows:

Level	Location	Applies To
Global	`C:\Users\YourName\.claude\settings.json`	All projects
Project	`.claude/settings.json` (inside your project folder)	This project only

Finding Your Home Folder

On Windows, your home folder is usually C:\Users\YourName. You can find it quickly by opening PowerShell and typing echo $env:USERPROFILE. The .claude folder may be hidden -- in File Explorer, click View and check Hidden items to see it.

Global vs Project Settings

When both files exist, Claude Code merges them together. Project settings override global settings for that specific project.

This is useful because you might want:

Global settings: your preferred theme, your default permission level
Project settings: specific tool permissions for this particular project, project-specific MCP servers

For example, you might globally deny file deletion but allow it for a specific cleanup-focused project.

Key Settings You Can Configure

Here are the most commonly used settings:

Theme

{
  "preferences": {
    "theme": "dark"
  }
}

Options are "dark", "light", or "light-daltonized".

Allowed and Denied Tools

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(del *)"
    ]
  }
}

This controls which tools Claude can use without asking you for permission. We will cover permissions in depth in the next two lessons.

Verbose Mode

{
  "preferences": {
    "verbose": true
  }
}

When verbose is on, Claude Code shows more detail about what it is doing, which can help you learn and debug.

A Basic settings.json Example

Here is a complete starter settings.json for a Windows user:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": []
  },
  "preferences": {
    "theme": "dark",
    "verbose": false
  }
}

This configuration:

Lets Claude read files, search for files, and search within files without asking
Does not deny any tools outright (Claude will ask before doing anything else)
Uses the dark theme
Keeps output concise (verbose off)

Valid JSON Required

settings.json must be valid JSON. That means:

Use double quotes around all keys and string values (not single quotes)
No trailing commas after the last item in a list or object
No comments (JSON does not support // or /* */ comments)

If Claude Code is not picking up your settings, the most common cause is a JSON syntax error. You can validate your JSON at jsonlint.com.

How to Edit settings.json

You have several options:

Option 1: Use any text editor Open the file directly in Notepad, VS Code, or any editor you prefer:

notepad $env:USERPROFILE\.claude\settings.json

Option 2: Ask Claude to help Inside a Claude Code session, you can say:

Show me my current settings.json

Add Read and Grep to my allowed tools in settings.json

Claude can read and modify the settings file for you.

Option 3: Use the /config command Inside Claude Code, type /config to interactively view and change settings. This is the safest approach because Claude Code validates the changes for you.

Start Simple

You do not need to configure everything up front. The defaults work well for most people. Add settings as you discover specific preferences. Over-configuring early can actually create problems.

Creating the .claude Folder

If you do not have a .claude folder in your project yet, you can create one:

# In your project folder:
mkdir .claude

# Then create the settings file:
notepad .claude\settings.json

For the global settings folder:

# Create the global .claude folder if it does not exist:
mkdir $env:USERPROFILE\.claude

# Then create or edit the global settings:
notepad $env:USERPROFILE\.claude\settings.json

Try It Yourself

Create a basic settings.json file for your practice project.

Navigate to your practice folder:
```
cd C:\Users\YourName\claude-practice
```
Create the .claude directory:
```
mkdir .claude
```
Open a new settings.json file:
```
notepad .claude\settings.json
```

Paste in this starter configuration:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": []
  },
  "preferences": {
    "theme": "dark"
  }
}

Save the file and close Notepad.
Start Claude Code and verify it picks up the settings:
```
claude
```
Then ask: "What are your current settings?" Claude should be able to tell you about the configuration.

No Visible Change?

Some settings (like theme) take effect immediately. Others (like permissions) affect behavior only when Claude tries to use a specific tool. Do not worry if nothing looks different right away -- you will see the permissions in action in the next lessons.

What You Learned

settings.json configures Claude Code's behavior (separate from CLAUDE.md which instructs Claude)
Global settings live at C:\Users\YourName\.claude\settings.json and apply everywhere
Project settings live at .claude/settings.json in your project and override global settings
Key options include theme, permissions (allowed/denied tools), and verbose mode
You can edit settings with a text editor, by asking Claude, or with the /config command
The file must be valid JSON -- double quotes, no trailing commas, no comments

Help Us Improve

How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.

Give Feedback →

Next Up

Next: The Permissions Model

What You Will Learn​

Prerequisites​

Main Content​

What Is settings.json?​

Where settings.json Lives​

Global vs Project Settings​

Key Settings You Can Configure​

Theme​

Allowed and Denied Tools​

Verbose Mode​

A Basic settings.json Example​

How to Edit settings.json​

Creating the .claude Folder​

Try It Yourself​

What You Learned​

Next Up​