fix-claude-settings-missing

Playbook: Fix Missing .claude/settings.json

When to use

• Repo has .claude/ directory but no settings.json (only settings.local.json or nothing)
• Claude Code VS Code extension prompts permission for every single tool call
• repo-consistency-audit.md reports settings.json MISSING for a repo

Root cause

settings.json → committed to git → shared across all clones and CI agents → auto-approve rules active settings.local.json → gitignored → machine-specific (MCP server paths, personal hooks) → NEVER for permissions

When only settings.local.json exists: permissions live in an un-committed file. Fresh clones, CI workers, and bms-4 agents all start without auto-approvals — every tool call generates a permission prompt that blocks execution.

Diagnosis

$repo = "C:\code_2026\<repo>"
Test-Path "$repo\.claude\settings.json"        # should be True
Test-Path "$repo\.claude\settings.local.json"  # True = has MCP/personal config (keep it)
Get-Content "$repo\.claude\settings.json" 2>$null | Select-Object -First 3

---

Fix

Step 1 — Create settings.json with stack-appropriate permissions

Choose the template that matches the repo’s stack:

Next.js / TypeScript (Art-Agency, et-operational-platform, brandpilot):

$repo = "C:\code_2026\<repo>"
[System.IO.File]::WriteAllText("$repo\.claude\settings.json", @'
{
    "permissions": {
        "allow": [
            "Bash(git status)",
            "Bash(git diff*)",
            "Bash(git log*)",
            "Bash(git add*)",
            "Bash(git commit*)",
            "Bash(git checkout*)",
            "Bash(git merge*)",
            "Bash(git branch*)",
            "Bash(git push origin*)",
            "Bash(git push -u origin*)",
            "Bash(git fetch origin*)",
            "Bash(git ls-remote*)",
            "Bash(git show*)",
            "Bash(git stash*)",
            "Bash(git rebase*)",
            "Bash(gh *)",
            "Bash(npm *)",
            "Bash(node *)",
            "Bash(npx *)",
            "Bash(ls *)",
            "Bash(find *)",
            "Bash(cat *)",
            "Bash(grep *)",
            "Bash(tail *)",
            "Bash(head *)",
            "Bash(wc *)",
            "Bash(mkdir -p *)",
            "Bash(cp *)",
            "Bash(mv *)",
            "Bash(touch *)",
            "Bash(curl *)",
            "mcp__github__get_file_contents",
            "mcp__github__list_branches",
            "mcp__github__list_commits",
            "mcp__github__list_issues",
            "mcp__github__list_pull_requests",
            "mcp__github__get_commit",
            "mcp__github__issue_read",
            "mcp__github__pull_request_read",
            "mcp__github__search_code",
            "mcp__github__search_issues",
            "mcp__github__search_pull_requests",
            "mcp__github__get_me",
            "mcp__github__add_issue_comment",
            "mcp__github__issue_write",
            "mcp__github__pull_request_review_write",
            "mcp__github__create_branch",
            "mcp__github__push_files",
            "mcp__github__create_pull_request",
            "mcp__github__update_pull_request",
            "mcp__github__merge_pull_request",
            "PowerShell",
            "Edit",
            "Write",
            "Read",
            "Glob",
            "Grep"
        ]
    }
}
'@, [System.Text.UTF8Encoding]::new($false))

Python CLI / automation (amazon-kdp-tango): Same as above but replace npm/node/npx with:

"Bash(python *)",
"Bash(python3 *)",
"Bash(pytest *)",
"Bash(pip *)",
"Bash(uv *)"

Android / Kotlin (whatsup-android-chat-puller): Same as Next.js template but replace npm/node/npx with:

"Bash(python *)",
"Bash(python3 *)",
"Bash(pytest *)",
"Bash(./gradlew *)",
"Bash(adb *)"

Content / personal brand (radekkonarski-personal-brand): Keep existing settings.json but expand the allow list to include Bash(gh *), Read, Glob, Grep which are blocked by default without explicit grant.

Step 2 — Verify settings.local.json is gitignored

# settings.local.json must NOT be committed — check .gitignore
Select-String "settings.local" "$repo\.gitignore"
# If missing, add it:
Add-Content "$repo\.gitignore" "`n.claude/settings.local.json"

Note: Claude Code automatically gitignores settings.local.json in most versions, but explicit entry in .gitignore is safer.

Step 3 — Commit

git -C $repo add .claude/settings.json
git -C $repo commit -m "chore: add .claude/settings.json — auto-approve permissions for Claude Code
 
Without this file fresh clones and CI agents have no auto-approvals.
settings.local.json (machine-specific MCP servers) remains un-committed.
 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
git -C $repo push origin HEAD

Step 4 — Verify in VS Code

Reload VS Code window in the target repo. Open Claude Code chat and type / — the command dropdown should appear without any permission prompts.

---

Affected repos (as of 2026-06-28)

Repo	Status	Action
Art-Agency	settings.local.json only (MCP config) — no settings.json	Create settings.json with Next.js permissions
amazon-kdp-tango	settings.json exists but only 3 entries (git, PowerShell git, PowerShell gh)	Expand permissions

---

Escalation

If Claude Code still prompts after adding settings.json: reload VS Code window (Ctrl+Shift+P → Developer: Reload Window). If settings.json causes merge conflicts: the allow array is append-safe — add new entries, never remove existing ones without review.