Claude Code Settings: .claude/settings.local.json

What this is: A configuration file that controls how Claude Code behaves on your machine — specifically which tools it can use automatically vs. which require your approval.

Where it lives

Claude Code looks for settings files in three places, applied in order:

~/.claude/settings.json              ← your personal defaults (all projects)
<project>/.claude/settings.json      ← project settings (shared with team, in git)
<project>/.claude/settings.local.json ← your local overrides (NOT in git, machine-specific)

For most researchers, the most useful file is the local one inside your project folder:

your-project/
  .claude/
    settings.local.json   ← create this yourself
  documents/
  notes/
  ...

The .local.json file is gitignored by default — it stays on your machine and is never shared.

What it controls: permissions

The main thing you configure here is permissions — which tools Claude Code can use without asking you first.

Every time Claude Code wants to use a tool (read a file, search the web, run a command), it checks against this list:

• allow — use automatically, no prompt

• ask — pause and ask you before using (default for most tools)

• deny — never use, even if you ask

{
  "permissions": {
    "allow": [
      "WebSearch",
      "WebFetch",
      "Bash(git status)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm *)"
    ]
  }
}

Common tools to allow for research work

Tip: Start with a minimal allow list and expand as you discover what you use. The default (ask) is safe — it just creates more interruptions.

MCP tool permissions

MCP tools follow the pattern mcp__<servername>__<toolname>. You can allow all tools from a server with a wildcard-style entry, or be specific:

{
  "permissions": {
    "allow": [
      "mcp__zotero__search",
      "mcp__zotero__fetch",
      "mcp__logseq-write__getPage",
      "mcp__logseq-write__addNoteContent"
    ]
  }
}

If you add a new MCP server and Claude keeps asking permission for its tools, add them here.

Bash permissions: be specific

Bash is the most powerful tool — it can run any shell command. You can allow specific commands rather than all of Bash:

"allow": [
  "Bash(git *)",
  "Bash(python *.py)",
  "Bash(pandoc *)"
]

Avoid "allow": ["Bash"] (all bash commands) unless you understand what that means. Better to allow specific patterns.

The defaultMode option

You can also set the overall permission behaviour:

{
  "defaultMode": "default"
}

Options:

• "default" — ask for anything not in allow/deny list (recommended)

• "acceptEdits" — auto-approve file edits, ask for other tools

• "plan" — Claude plans but never acts without your approval (read-only mode)

For researchers doing sensitive archival work where you want to review every action, "plan" mode is useful.

A minimal starting config for researchers

{
  "permissions": {
    "allow": [
      "WebSearch",
      "WebFetch",
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(git diff *)"
    ]
  }
}

Add MCP tool entries as you install MCP servers.

Tips

You can have both a project file and a local file. The local file overrides the project file. Use the project file for settings that should apply to everyone working on the project; use the local file for your personal preferences.

Changes take effect immediately. You do not need to restart Claude Code after editing this file — the next tool call will use the updated permissions.

If Claude keeps asking for the same permission, that tool is not in your allow list. Add it.

If Claude does something you did not expect, check what is in your allow list — it may be allowing more than you intended.

The /permissions command inside Claude Code shows you the current effective permissions and which file they came from.

The rules/ folder: modular CLAUDE.md for larger projects

When a project CLAUDE.md grows too long, you can split instructions into separate files under .claude/rules/. Every markdown file in that folder is loaded alongside CLAUDE.md automatically — no import needed.

your-project/
  .claude/
    rules/
      transcription-conventions.md
      data-extraction.md
      writing-style.md

The advantage over @imports in CLAUDE.md is path-scoping: add a YAML frontmatter block to a rules file and it only activates when Claude is working in matching directories:

---
paths:

  - "transcriptions/**/*.md"

  - "sources/**/*.txt"
---
# Transcription conventions

- Preserve original spelling; mark interventions with [brackets]

- Flag illegible passages as [illeg.]

- Date format: DD.MM.YYYY (Julian)

Claude will not load this file when editing files in /notes/ or /output/ — only when it is actively reading or writing in /transcriptions/ or /sources/. This keeps irrelevant rules out of context when they do not apply.

For most solo research projects, a single well-maintained CLAUDE.md is sufficient. The rules/ approach pays off when you have distinct working modes (transcription vs. data extraction vs. writing) with genuinely different conventions that you do not want cluttering each other's context.

Related

• A.issue.personalisation — the full personalisation system: settings.json in context alongside CLAUDE.md, Memory, Skills, and MCP; the complete setup sequence

• A3.code-basics-non-programmers — installation and first launch

• A.concept.agents — why controlling agent permissions matters

• A9.markdown-project-memory — the other key config file: CLAUDE.md