Skip to main content

Settings & Configuration in Claude Code

Claude2 min read
A settings.json file with configuration keys and a gear icon

Almost everything about Claude Code’s behavior — permissions, environment, hooks, which plugins are on, your theme — is controlled by settings.json files. You rarely need to touch most of it, but knowing where settings live and how they layer means you can change what you need with confidence.

Where settings live#

Like memory, settings come in scopes that layer from personal to project. The three you will deal with:

  • User settings — ~/.claude/settings.json. Your personal preferences across every project.
  • Project settings — .claude/settings.json in the repo. Shared with the team via Git. "How this project should behave for everyone."
  • Project-local settings — .claude/settings.local.json. Your personal overrides for this project, git-ignored.

If this layering feels familiar, it should — it mirrors the memory scopes from post 7. More specific scopes override more general ones, and (in an enterprise setup) a managed policy can sit above all of them and cannot be overridden.

The easy way: /config#

You do not have to hand-edit JSON for common changes. Inside a session, run:

text
/config

This opens an interactive view where you can see and change settings without leaving Claude Code. For simple things — switching themes, toggling options — it is the quickest route.

Settings beginners actually change#

You can ignore most keys until you have a reason. The ones people commonly set early:

  • `permissions` — the allow/deny rules from post 5. Often the first thing you customize.
  • `model` — a default model for this project or for you globally.
  • `env` — environment variables Claude Code should have available.
  • `theme` — terminal color theme, if you want to change the look.
  • `enabledPlugins` — which plugins are active (we cover plugins later).

A small, readable example of a project settings file:

.claude/settings.json
{
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Bash(git diff:*)"],
    "deny": ["Bash(rm -rf:*)"]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

Related config files#

A couple of other files round out configuration, good to recognize when you see them:

  • ~/.claude/keybindings.json — customize keyboard shortcuts (e.g. enable Vim-style editing of your prompts).
  • .claude/ directory — the home for your project’s Claude Code assets: settings, commands, skills, agents, and more. You will fill this out as the series continues.

When something is not working#

If a setting does not seem to take effect, remember the layering: a more specific scope (local, then project, then user) may be overriding what you changed, and an enterprise-managed policy can override everything. Check the same key in the other files. We will cover deeper diagnosis in the troubleshooting post near the end of the series.

What’s next#

That wraps the fundamentals. From here the series moves into power features — and we start with Skills, the way to package task-specific expertise that Claude loads exactly when it is relevant.

Share: