Local agent settings (settings.local.json)

.claude/settings.local.json is per-machine, gitignored Claude Code configuration — it never commits, so it’s the right place for machine-specific permissions and toggles. (The committed .claude/settings.json holds shared hooks; don’t put personal permission grants there.)

The safety classifier (and why an agent can’t disable it)

In an auto-approve permission mode, Claude Code runs a safety classifier on risky Bash commands (production deploys, DB drops, force-push, .env writes) and gates the dangerous ones. This is what blocks vercel deploy --prod unless it’s explicitly pre-approved.

An agent cannot write its own permission-allow rules to bypass that gate — the harness flags it as “self-modification / auto-mode bypass” and denies it. That’s deliberate: if an agent could grant itself permissions, the guardrail would be meaningless. So the permissions below must be added by a human (you), not by the assistant.

Recommended .claude/settings.local.json

{
  "permissions": {
    "allow": [
      "Bash(vercel:*)"
    ]
  }
}

• Bash(vercel:*) pre-approves all vercel commands (preview + prod deploys, env, alias, logs) so they stop hitting the classifier. Scope it to vercel — do not use Bash(*) or full bypass mode, or you lose the guardrail for genuinely destructive commands.
• Prefer narrower grants if you want prod deploys to stay manual but speed up the rest:

  { "permissions": { "allow": [
    "Bash(vercel deploy --target=preview:*)",
    "Bash(vercel env ls:*)", "Bash(vercel ls:*)", "Bash(vercel inspect:*)", "Bash(vercel alias:*)"
  ] } }

  (omit vercel deploy --prod to keep the production cutover human-only).

Per-project MCP toggles (optional)

The same file can disable noisy/irrelevant MCP servers per project to save context budget:

{ "disabledMcpjsonServers": ["some-server"] }

Merge both keys into one object if you use both.

After editing

Restart Claude Code (or start a new session) so the settings load. Confirm the file is not tracked: git check-ignore .claude/settings.local.json should print the path.

See also

• Deploy/env/Neon runbook: .claude/rules/10-vercel-deploy-and-env.md
• Deploy status · Platform architecture