Settings.json: Permissions, Env Vars, Model Overrides

Settings.json is where the harness — not the model — gets configured. It is also where most surprises live, so understanding the layers saves debugging time.

9 min · Reviewed 2026

What settings.json controls

Settings.json is the place to configure everything the model isn't deciding for itself: which permissions auto-approve, which env vars get exposed, which model the session defaults to, which hooks fire, which MCP servers connect. The model reads its own instructions; the harness reads settings.json.

The three config layers

Layer	Path	Scope
User	~/.claude/settings.json	All your sessions
Project	.claude/settings.json	Anyone in this repo
Local	.claude/settings.local.json	Just you, this repo (gitignored)

What goes where

User: personal model preference, default permissions, your global hooks
Project: shared permissions, project-specific hooks, MCP servers everyone uses, env vars the project needs exposed
Local: per-repo overrides for just you (an MCP server only you have credentials for)

Permission entries that pay off

{ "permissions": { "allow": [ "Bash(pnpm test:*)", "Bash(pnpm lint:*)", "Bash(git status)", "Bash(git diff:*)", "Read(**)" ], "deny": [ "Bash(git push --force:*)", "Bash(rm -rf:*)" ] } }Common permission setup. Allow the safe, repeated commands; explicitly deny the destructive ones.

Env vars and overrides

Settings.json can expose env vars to the harness — useful for things like alternate API keys or AI Gateway URLs. It can also override the default model for a project (handy when one repo wants Sonnet and another wants Opus). The override happens at the harness level, before the model ever sees the request.

Apply: audit your settings tonight

Open ~/.claude/settings.json
Read every permission entry; ask 'would I be okay if this fired right now without asking?'
Move team-wide entries to project settings
Move personal/secret entries to local settings
Commit the project settings; gitignore the local

The big idea: settings.json is the harness contract. Audit it like you audit credentials, layer it like you layer dotfiles.

End-of-lesson check

8 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-claude-code-settings-creators

What is the main idea of "Settings.json: Permissions, Env Vars, Model Overrides"?
1. Settings.json is where the harness — not the model — gets configured.
2. Use AI as the final authority for the whole decision
3. Avoid checking the answer once it sounds polished
4. Focus only on speed instead of judgment
Which concept is most central to "Settings.json: Permissions, Env Vars, Model Overrides"?
1. permission model
2. settings.json
3. config layering
4. env override
Which use of AI fits this topic best?
1. Let the AI decide what matters without your review
2. Use the answer before checking whether it fits the situation
3. User: personal model preference, default permissions, your global hooks
4. Treat the AI output as automatically correct
What should a careful learner remember about "Project settings get committed"?
1. Use AI to draft or organize ideas about settings.json, then verify before acting.
2. Skip the context so the tool can guess faster
3. Treat the output as private even after sharing it online
4. Use the answer without checking the source
You want to use AI after this lesson. What is the safest next step?
1. Act immediately because the AI answer is written clearly
2. Use AI for drafting and comparison, but verify before publishing or relying on it.
3. Hide uncertainty so the final answer looks cleaner
4. Use private or sensitive details before checking permission
How should AI output about settings.json be treated?
1. As proof that no other source is needed
2. As a replacement for context, consent, or expert review
3. As a draft or helper output that still needs human judgment and verification
4. As something that becomes correct when it sounds confident
Name one way to verify an AI answer about settings.json.
Which action would help you apply "Settings.json: Permissions, Env Vars, Model Overrides" responsibly?
1. Use the tool to avoid thinking through the tradeoff
2. Keep going even if the output conflicts with a trusted source
3. Treat the AI output as automatically correct
4. Project: shared permissions, project-specific hooks, MCP servers everyone uses, env vars the project needs exposed

← Back to interactive lesson

Tendril · Creators · Tools Literacy

Settings.json: Permissions, Env Vars, Model Overrides

Settings.json is where the harness — not the model — gets configured. It is also where most surprises live, so understanding the layers saves debugging time.

9 min · Reviewed 2026

What settings.json controls

The three config layers

Layer	Path	Scope
User	~/.claude/settings.json	All your sessions
Project	.claude/settings.json	Anyone in this repo
Local	.claude/settings.local.json	Just you, this repo (gitignored)

What goes where

User: personal model preference, default permissions, your global hooks
Project: shared permissions, project-specific hooks, MCP servers everyone uses, env vars the project needs exposed
Local: per-repo overrides for just you (an MCP server only you have credentials for)

Permission entries that pay off

{ "permissions": { "allow": [ "Bash(pnpm test:*)", "Bash(pnpm lint:*)", "Bash(git status)", "Bash(git diff:*)", "Read(**)" ], "deny": [ "Bash(git push --force:*)", "Bash(rm -rf:*)" ] } }Common permission setup. Allow the safe, repeated commands; explicitly deny the destructive ones.

Env vars and overrides

Apply: audit your settings tonight

Open ~/.claude/settings.json
Read every permission entry; ask 'would I be okay if this fired right now without asking?'
Move team-wide entries to project settings
Move personal/secret entries to local settings
Commit the project settings; gitignore the local

The big idea: settings.json is the harness contract. Audit it like you audit credentials, layer it like you layer dotfiles.

End-of-lesson check

8 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-claude-code-settings-creators

What is the main idea of "Settings.json: Permissions, Env Vars, Model Overrides"?
1. Settings.json is where the harness — not the model — gets configured.
2. Use AI as the final authority for the whole decision
3. Avoid checking the answer once it sounds polished
4. Focus only on speed instead of judgment
Which concept is most central to "Settings.json: Permissions, Env Vars, Model Overrides"?
1. permission model
2. settings.json
3. config layering
4. env override
Which use of AI fits this topic best?
1. Let the AI decide what matters without your review
2. Use the answer before checking whether it fits the situation
3. User: personal model preference, default permissions, your global hooks
4. Treat the AI output as automatically correct
What should a careful learner remember about "Project settings get committed"?
1. Use AI to draft or organize ideas about settings.json, then verify before acting.
2. Skip the context so the tool can guess faster
3. Treat the output as private even after sharing it online
4. Use the answer without checking the source
You want to use AI after this lesson. What is the safest next step?
1. Act immediately because the AI answer is written clearly
2. Use AI for drafting and comparison, but verify before publishing or relying on it.
3. Hide uncertainty so the final answer looks cleaner
4. Use private or sensitive details before checking permission
How should AI output about settings.json be treated?
1. As proof that no other source is needed
2. As a replacement for context, consent, or expert review
3. As a draft or helper output that still needs human judgment and verification
4. As something that becomes correct when it sounds confident
Name one way to verify an AI answer about settings.json.
Which action would help you apply "Settings.json: Permissions, Env Vars, Model Overrides" responsibly?
1. Use the tool to avoid thinking through the tradeoff
2. Keep going even if the output conflicts with a trusted source
3. Treat the AI output as automatically correct
4. Project: shared permissions, project-specific hooks, MCP servers everyone uses, env vars the project needs exposed

← Back to interactive lesson