Settings.json: Permissions, Env Vars, Model Overrides

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

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:*)"
    ]
  }
}

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

1. 1Open ~/.claude/settings.json
2. 2Read every permission entry; ask 'would I be okay if this fired right now without asking?'
3. 3Move team-wide entries to project settings
4. 4Move personal/secret entries to local settings
5. 5Commit 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.